Skip to content

Commit 4226449

Browse files
vchrisbvchrisb
authored
Add option to specify origin to be used for authentication (#13)
1 parent 21dc868 commit 4226449

File tree

6 files changed

+242
-125
lines changed

6 files changed

+242
-125
lines changed

‎README.md‎

Lines changed: 175 additions & 92 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,25 @@
11
# setup-cf
22

3-
This action provides the following functionality for GitHub Actions users:
3+
## Overview
44

5-
- Installing a version of [Cloud Foundry CLI](https://github.com/cloudfoundry/cli) and adding it to the PATH
6-
- Authenticating to the Cloud Foundry API using different grant types:
5+
The `setup-cf` GitHub Action enables seamless integration with Cloud Foundry in your CI/CD pipelines. It simplifies the process of installing the Cloud Foundry CLI (cf cli), authenticating with Cloud Foundry services, and targeting specific organizations and spaces.
6+
7+
This action is particularly useful for teams who deploy applications to Cloud Foundry platforms and want to automate their deployment workflows.
8+
9+
## Features
10+
11+
- **Installation**: Automatically installs a specified version of [Cloud Foundry CLI](https://github.com/cloudfoundry/cli) and adds it to the PATH
12+
- **Authentication**: Supports multiple authentication grant types:
713
- Password
814
- Client Credentials
915
- Client Credentials with JWT
1016
- JWT Bearer Token Grant
11-
- Target Org and Space
17+
- **Targeting**: Automatically targets specified organization and space
18+
- **GitHub OIDC Integration**: Works with GitHub's OpenID Connect (OIDC) for secure authentication
1219

13-
## Basic usage
20+
## Basic Usage
1421

15-
See [action.yml](action.yml)
22+
See [action.yml](action.yml) for complete action definition.
1623

1724
```yaml
1825
steps:
@@ -28,113 +35,69 @@ steps:
2835
run: cf apps
2936
```
3037
31-
## Parameter
32-
* `api`
33-
* Url of the cloud controller api
34-
* required
35-
* `audience`
36-
* audience for requesting the GitHub `id_token`
37-
* `client_id`
38-
* client id for `client_credentals` or `jwt-bearer`
39-
* `client_secret`
40-
* client secret for `client_credentals` or `jwt-bearer`
41-
* `grant_type`
42-
* grant type for access
43-
* required
44-
* default: `password`
45-
* valid values:
46-
* `password`
47-
* `client_credentals`
48-
* `jwt-bearer`
49-
* `jwt`
50-
* jwt for usage with `client_credentals` or `jwt-bearer`. If omitted, a GitHub `id_token` will be requested
51-
* `username`
52-
* username for `password` grant
53-
* `password`
54-
* password for `password` grant
55-
* `org`
56-
* Cloud Foundry organization name
57-
* `skip_ssl_validation`
58-
* Skip verification of the API endpoint
59-
* default: `false`
60-
* `space`
61-
* Cloud Foundry space name
62-
* `version`
63-
* cf cli version
64-
* required
65-
* default: `8.12.0`
66-
67-
## Advanced
68-
69-
Requires at least UAA `77.20.4`.
70-
71-
### GitHub id_token
72-
73-
https://docs.github.com/en/actions/security-for-github-actions/security-hardening-your-deployments/about-security-hardening-with-openid-connect
74-
75-
To allow a workflow to request an `id_token`, the workflow needs to have the correct permissions:
38+
## Parameters
7639
77-
```
78-
permissions:
79-
id-token: write # This is required for requesting the JWT
80-
contents: read # This is required for actions/checkout
81-
```
82-
83-
> The `sub` may not be used for the `user_name` attribute mapping, as it can include unsupported characters like `/` and `:`.
40+
| Parameter | Description | Required | Default |
41+
|-----------|-------------|:--------:|:-------:|
42+
| `api` | URL of the Cloud Foundry API endpoint | Yes | - |
43+
| `audience` | Audience for requesting the GitHub `id_token` | No | - |
44+
| `client_id` | Client ID for `client_credentials` or `jwt-bearer` grant types | No | - |
45+
| `client_secret` | Client secret for `client_credentials` or `jwt-bearer` grant types | No | - |
46+
| `grant_type` | Authentication grant type (`password`, `client_credentials`, or `jwt-bearer`) | Yes | `password` |
47+
| `jwt` | JWT token for use with `client_credentials` or `jwt-bearer`. If omitted with these grant types, a GitHub `id_token` will be requested automatically | No | - |
48+
| `org` | Cloud Foundry organization name to target | No | - |
49+
| `origin` | Identity provider origin to use for authentication with `jwt-bearer` or `password` | No | - |
50+
| `username` | Username for `password` grant type | No | - |
51+
| `password` | Password for `password` grant type | No | - |
52+
| `skip_ssl_validation` | Skip verification of the API endpoint (not recommended for production) | No | `false` |
53+
| `space` | Cloud Foundry space name to target | No | - |
54+
| `version` | Cloud Foundry CLI version to install | Yes | `8.12.0` |
8455

85-
The sub can be customized https://docs.github.com/en/actions/security-for-github-actions/security-hardening-your-deployments/about-security-hardening-with-openid-connect#customizing-the-subject-claims-for-an-organization-or-repository
56+
## Authentication Methods
8657

87-
### setup UAA for JWT Bearer Token Grant with GitHub
58+
### Password Authentication
8859

89-
Add the GitHub OIDC provider and use e.g. the `repository_owner` claim as the `user_name`:
60+
The simplest authentication method using username and password:
9061

91-
```
92-
uaac curl /identity-providers -X POST -H "Content-Type: application/json" -d '{"type": "oidc1.0", "name": "GitHub", "originKey": "github", "config": {"discoveryUrl": "https://token.actions.githubusercontent.com/.well-known/openid-configuration", "scopes": ["read:user", "user:email"], "linkText": "Login with GitHub", "showLinkText": false, "addShadowUserOnLogin": true, "clientAuthInBody": true, "relyingPartyId": "uaa", "addShadowUserOnLogin": true, "attributeMappings" : {"given_name": "repository_owner", "family_name": "repository_owner_id", "user_name": "repository_owner"}}}'
62+
```yaml
63+
- uses: vchrisb/setup-cf@v2
64+
with:
65+
api: ${{ secrets.CF_API }}
66+
grant_type: password
67+
username: ${{ secrets.CF_USERNAME }}
68+
password: ${{ secrets.CF_PASSWORD }}
69+
org: myorg
70+
space: myspace
9371
```
9472

95-
The UAA client used does need to include `urn:ietf:params:oauth:grant-type:jwt-bearer` in the `authorized_grant_types`.
96-
This can be the default `cf` client, but also a dedicated one:
73+
### JWT Bearer Token Grant with GitHub OIDC
9774

98-
```
99-
uaac curl /oauth/clients -X POST -H "Content-Type: application/json" -d '{"client_id" : "jwt-bearer-client", "access_token_validity": 1800, "authorities" : [ "uaa.resource" ], "authorized_grant_types" : [ "urn:ietf:params:oauth:grant-type:jwt-bearer" ], "scope": ["openid", "cloud_controller.read"], "allowedproviders" : [ "github" ], "name" : "JWT Bearer Client"}'
100-
```
75+
This method leverages GitHub's OIDC provider for secure, token-based authentication:
10176

10277
```yaml
103-
name: Jwt Bearer Flow using GitHub id_token
78+
name: JWT Bearer Flow using GitHub id_token
10479
on: [push]
10580
permissions:
106-
id-token: write
107-
contents: read
81+
id-token: write # Required for requesting the JWT
82+
contents: read # Required for actions/checkout
10883
jobs:
10984
deploy:
11085
runs-on: ubuntu-latest
11186
steps:
11287
- uses: actions/checkout@v4
11388
- uses: vchrisb/setup-cf@v2
114-
with:
89+
with:
11590
api: ${{ secrets.CF_API }}
11691
grant_type: jwt-bearer
11792
org: test
11893
space: dev
11994
- name: run cf command
120-
run: cf apps
95+
run: cf apps
12196
```
12297

123-
The cf cli will be authenticated as an user, which username is defined by the `attributeMappings`.
98+
### Client Credentials with JWT
12499

125-
### setup UAA for JWT client credentials
126-
127-
The UAA client used does need to include `client_credentials` in the `authorized_grant_types`.
128-
129-
```
130-
uaac client add setup-cf --scope uaa.none --authorities cloud_controller.read --authorized_grant_type "client_credentials"
131-
```
132-
133-
Add the jwt configuration to the client.
134-
The following example is for GitHub. You can also pass a different token using `jwt` parameter, but will need to adapt the configuration to your idp.
135-
```
136-
uaac client jwt add setup-cf --issuer https://token.actions.githubusercontent.com --subject repo:vchrisb/setup-cf:environment:Production --aud https://github.com/vchrisb
137-
```
100+
This method uses client credentials with JWT verification:
138101

139102
```yaml
140103
name: Client Credentials using GitHub id_token
@@ -148,24 +111,144 @@ jobs:
148111
steps:
149112
- uses: actions/checkout@v4
150113
- uses: vchrisb/setup-cf@v2
151-
with:
114+
with:
152115
api: ${{ secrets.CF_API }}
153116
client_id: setup-cf
154117
grant_type: client_credentials
155118
org: test
156119
space: dev
157120
- name: run cf command
158-
run: cf apps
121+
run: cf apps
122+
```
123+
124+
## Advanced Configuration
125+
126+
### Setting up UAA for GitHub Authentication
127+
128+
#### Prerequisites
129+
- UAA version 77.20.4 or higher
130+
- Administrative access to UAA
131+
132+
#### Configuring UAA for JWT Bearer Token Grant with GitHub
133+
134+
1. Add the GitHub OIDC provider to UAA:
135+
136+
```
137+
uaac curl /identity-providers -X POST -H "Content-Type: application/json" -d '{
138+
"type": "oidc1.0",
139+
"name": "GitHub",
140+
"originKey": "github",
141+
"config": {
142+
"discoveryUrl": "https://token.actions.githubusercontent.com/.well-known/openid-configuration",
143+
"scopes": ["read:user", "user:email"],
144+
"linkText": "Login with GitHub",
145+
"showLinkText": false,
146+
"addShadowUserOnLogin": false,
147+
"clientAuthInBody": true,
148+
"relyingPartyId": "uaa",
149+
"addShadowUserOnLogin": true,
150+
"attributeMappings": {
151+
"given_name": "repository_owner",
152+
"family_name": "repository_owner_id",
153+
"user_name": "repository_owner"
154+
}
155+
}
156+
}'
157+
```
158+
159+
2. Ensure your UAA client includes the JWT bearer grant type:
160+
161+
Either create a dedicated client to be used for JWT bearer grant:
162+
163+
```
164+
uaac curl /oauth/clients -X POST -H "Content-Type: application/json" -d '{
165+
"client_id": "jwt-bearer-client",
166+
"access_token_validity": 1800,
167+
"authorities": ["uaa.resource"],
168+
"authorized_grant_types": ["urn:ietf:params:oauth:grant-type:jwt-bearer"],
169+
"scope": ["openid", "cloud_controller.read"],
170+
"allowedproviders": ["github"],
171+
"name": "JWT Bearer Client"
172+
}'
173+
```
174+
175+
Or add the grant type to the default `cf` client:
176+
177+
```
178+
uaac client update cf \
179+
--authorized_grant_types refresh_token,password,urn:ietf:params:oauth:grant-type:jwt-bearer
180+
```
181+
182+
#### Configuring UAA for JWT Client Credentials
183+
184+
1. Create a client with client credentials grant type:
185+
186+
```
187+
uaac client add setup-cf \
188+
--scope uaa.none \
189+
--authorities cloud_controller.read,cloud_controller.write,clients.read \
190+
--authorized_grant_type "client_credentials"
159191
```
160192

161-
The cf cli will be authenticated as the client `setup-cf`.
193+
2. Add JWT configuration to the client:
162194

163-
## Developmet
195+
```
196+
uaac client jwt add setup-cf \
197+
--issuer https://token.actions.githubusercontent.com \
198+
--subject repo:vchrisb/setup-cf:environment:Production \
199+
--aud https://github.com/vchrisb
200+
```
164201

165-
### update action
202+
Subject and Audience need to adapted to your repo and workflow.
203+
204+
### GitHub OIDC Configuration
205+
206+
To use GitHub's OIDC provider, your workflow must have the appropriate permissions:
207+
208+
```yaml
209+
permissions:
210+
id-token: write # Required for requesting the JWT
211+
contents: read # Required for actions/checkout
212+
```
213+
214+
Note: The `sub` claim from GitHub may contain characters like `/` and `:` which are not supported for the `user_name` attribute. Consider using alternative claims or customizing the subject as described in [GitHub's documentation](https://docs.github.com/en/actions/security-for-github-actions/security-hardening-your-deployments/about-security-hardening-with-openid-connect#customizing-the-subject-claims-for-an-organization-or-repository).
215+
216+
## Troubleshooting
217+
218+
### Common Issues
219+
220+
1. **Authentication Failures**
221+
- Verify your credentials are correct
222+
- Check that your client has the necessary authorities and grant types
223+
- Ensure the UAA version is 77.20.4 or higher for JWT-based auth
224+
225+
2. **Permission Issues**
226+
- For GitHub OIDC, make sure the workflow has `id-token: write` permission
227+
- Verify the client or user has appropriate Cloud Foundry permissions
228+
229+
3. **Targeting Issues**
230+
- Confirm the organization and space exist
231+
- Check that the authenticated user/client has access to the specified org/space
232+
233+
### Debugging
234+
235+
Add the following to your workflow to see more detailed output:
236+
237+
```yaml
238+
env:
239+
CF_LOG_LEVEL: DEBUG
240+
```
241+
242+
## Development
243+
244+
To update the action:
166245

167246
```
168247
npm i -g @vercel/ncc
169248
npm run format
170249
npm run build
171250
```
251+
252+
## License
253+
254+
This project is licensed under the MIT License - see the LICENSE file for details.

‎action.yaml‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -24,15 +24,18 @@ inputs:
2424
jwt:
2525
description: "jwt for usage with `client_credentials` or `jwt-bearer`."
2626
required: false
27+
org:
28+
description: "org"
29+
required: false
30+
origin:
31+
description: "origin"
32+
required: false
2733
username:
2834
description: "username"
2935
required: false
3036
password:
3137
description: "password"
3238
required: false
33-
org:
34-
description: "org"
35-
required: false
3639
skip_ssl_validation:
3740
description: "skip_ssl_validation"
3841
required: false

0 commit comments

Comments
 (0)