Skip to content

Commit bf1b403

Browse files
alexellisalexellis
committed
Add initial notes on IAM
Signed-off-by: Alex Ellis (OpenFaaS Ltd) <[email protected]>
1 parent 87cb400 commit bf1b403

File tree

6 files changed

+456
-4
lines changed

6 files changed

+456
-4
lines changed

‎README.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ This is the source repository for the OpenFaaS documentation site.
55
For local development:
66

77
```shell
8-
# docker run --rm -it -p 8000:8000 -v `pwd`:/docs squidfunk/mkdocs-material
8+
docker run --rm -it -p 8000:8000 -v `pwd`:/docs squidfunk/mkdocs-material:latest
99
```
1010

1111
## Published page

‎docs/openfaas-pro/iam/example-auth0.md

+136
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
# Auth0 Example for OpenFaaS IAM
2+
3+
In order to access the OpenFaaS API, a JWT Issuer must first be registered with the system.
4+
5+
Create an application on Auth0 for the OpenFaaS gateway, you'll need to obtain the corresponding "client_id".
6+
7+
## Register the Issuer for Auth0
8+
9+
An Issuer for `https://alexellis.eu.auth0.com/` might look like this:
10+
11+
```yaml
12+
apiVersion: openfaas.com/v1
13+
kind: JwtIssuer
14+
metadata:
15+
name: alexellis.eu.auth0.com
16+
namespace: openfaas
17+
spec:
18+
iss: https://alexellis.eu.auth0.com/
19+
aud:
20+
- 17F3M3rS8ORQUPDHsgkq0YVHheZVH8dpaGHRTjAx5x0
21+
- MO7Eq6O53SOxr3ie19TUMvo71ioYouJHsJEIw0PHc
22+
tokenExpiry: 12h
23+
```
24+
25+
## Define a Role
26+
27+
Once registered, a Role must be created which maps users within the Issuer to be mapped to a set of Policies
28+
29+
```yaml
30+
apiVersion: openfaas.com/v1
31+
kind: Role
32+
metadata:
33+
name: dev-staff-deployers
34+
namespace: openfaas
35+
spec:
36+
policy:
37+
- dev-rw
38+
- staging-readonly
39+
principal:
40+
jwt:sub:
41+
- github|1234567
42+
- github|7654321
43+
condition:
44+
StringEqual:
45+
jwt:iss: ["https://alexellis.eu.auth0.com/"]
46+
```
47+
> A Role including statements to evaluate its bindings to: two staff members
48+
49+
Valid conditions include: `StringEqual` or `StringLike`.
50+
51+
Every condition must return true for the Role to be considered as a match.
52+
53+
The principal field is optional, however if it is given, both the principal and the condition must match. If there are multiple items given, then only one must match the token.
54+
55+
If you configure Auth0 to emit a "group" claim such as "example.com/group", you could match this with a condition, instead of specifying individual "sub" fields.
56+
57+
A user's email could also be fuzzy matched with a condition, for example:
58+
59+
```yaml
60+
condition:
61+
StringLike:
62+
jwt:email: ["*@example.com"]
63+
```
64+
65+
## Bind a Policy to a Role
66+
67+
Finally, one or more Policies must be created which describe which permissions a user has, and on which resources.
68+
69+
```yaml
70+
apiVersion: openfaas.com/v1
71+
kind: Policy
72+
metadata:
73+
name: dev-rw
74+
namespace: openfaas
75+
spec:
76+
statement:
77+
- sid: 1-rw-dev
78+
action:
79+
- Function:Read
80+
- Function:Admin
81+
- Secret:Read
82+
effect: Allow
83+
resource: dev:*
84+
```
85+
86+
> Allow read and write to functions and secrets within the `dev` namespace:
87+
88+
```yaml
89+
apiVersion: openfaas.com/v1
90+
kind: Policy
91+
metadata:
92+
name: staging-readonly
93+
namespace: openfaas
94+
spec:
95+
statement:
96+
- sid: 1-ro-staging
97+
action:
98+
- Function:Read
99+
effect: Allow
100+
resource: staging-fn:*
101+
```
102+
103+
> Allow only read access to functions within the `staging-fn` namespace:
104+
105+
The JwtIssuer, Role and Policy resources are Kubernetes Custom Resources, and must be created within the `openfaas` namespace.
106+
107+
## Authenticate as the user
108+
109+
The `faas-cli` needs to be used to obtain a token from Auth0, and then exchange it for an OpenFaaS Access token.
110+
111+
Note the `--audience` flag which must be set to the URL of the OpenFaaS gateway.
112+
113+
```bash
114+
faas-cli pro auth \
115+
--grant code \
116+
--auth-url https://alexellis.eu.auth0.com/authorize \
117+
--token-url https://alexellis.eu.auth0.com/oauth/token \
118+
--client-id 17F3M3rS8ORQUPDHsgkq0YVHheZVH8dpaGHRTjAx5x0 \
119+
--audience https://gw.example.com
120+
```
121+
122+
Exchange the resulting id_token for an OpenFaaS Access token:
123+
124+
```bash
125+
export ID_TOKEN=""
126+
export ACCESS_TOKEN=$(curl -s https://gw.example.com/oauth/token?grant_type=urn:ietf:params:oauth:grant-type:token-exchange -d "$id_token")
127+
```
128+
129+
You can then use the OpenFaaS Access token as follows:
130+
131+
```bash
132+
faas-cli list --token $ACCESS_TOKEN
133+
```
134+
135+
In a future version of the `faas-cli` the above token exchange will be automated.
136+

‎docs/openfaas-pro/iam/github-actions-federation.md

+106
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
# GitHub Actions - Web Identity Federation
2+
3+
In this guide, you'll learn how to deploy from GitHub Actions CI/CD using OpenFaaS's IAM support and Web Identity Federation.
4+
5+
You'll need to create YAML files for an Issuer, a Policy and a Role. These need to be applied through kubectl, Helm or a GitOps tool.
6+
7+
Your build will need to be adapted in order to receive an id_token from GitLab, which will be exchanged for an OpenFaaS access token.
8+
9+
## Define an Issuer for GitHub Actions
10+
11+
First define a new JwtIssuer resource, setting the `aud` field to the URL of your OpenFaaS Gateway.
12+
13+
```yaml
14+
apiVersion: openfaas.com/v1
15+
kind: JwtIssuer
16+
metadata:
17+
name: token.actions.githubusercontent.com
18+
namespace: openfaas
19+
spec:
20+
iss: https://token.actions.githubusercontent.com
21+
aud:
22+
- https://gw.example.com
23+
tokenExpiry: 30m
24+
```
25+
26+
> Issuer for https://token.actions.githubusercontent.com
27+
28+
## Create a Policy
29+
30+
Next, define a Policy with the least privileges required to perform the desired actions.
31+
32+
```yaml
33+
apiVersion: openfaas.com/v1
34+
kind: Policy
35+
metadata:
36+
name: dev-rw
37+
namespace: openfaas
38+
spec:
39+
statement:
40+
- sid: 1-rw-dev
41+
action:
42+
- Function:Read
43+
- Function:Admin
44+
- Secret:Read
45+
effect: Allow
46+
resource: dev:*
47+
```
48+
49+
## Bind a Policy to a Role
50+
51+
Next, you need to bind the Policy to a Role.
52+
53+
There are around a dozen different fields available within the GitHub Actions `id_token`:
54+
55+
```json
56+
{
57+
"actor": "aidansteele",
58+
"aud": "https://github.com/aidansteele/aws-federation-github-actions",
59+
"base_ref": "",
60+
"event_name": "push",
61+
"exp": 1631672856,
62+
"head_ref": "",
63+
"iat": 1631672556,
64+
"iss": "https://token.actions.githubusercontent.com",
65+
"job_workflow_ref": "aidansteele/aws-federation-github-actions/.github/workflows/test.yml@refs/heads/main",
66+
"jti": "8ea8373e-0f9d-489d-a480-ac37deexample",
67+
"nbf": 1631671956,
68+
"ref": "refs/heads/main",
69+
"ref_type": "branch",
70+
"repository": "aidansteele/aws-federation-github-actions",
71+
"repository_owner": "aidansteele",
72+
"run_attempt": "1",
73+
"run_id": "1235992580",
74+
"run_number": "5",
75+
"sha": "bf96275471e83ff04ce5c8eb515c04a75d43f854",
76+
"sub": "repo:aidansteele/aws-federation-github-actions:ref:refs/heads/main",
77+
"workflow": "CI"
78+
}
79+
```
80+
81+
> Example from: [Deploy without credentials with GitHub Actions and OIDC](https://blog.alexellis.io/deploy-without-credentials-using-oidc-and-github-actions/)
82+
83+
```yaml
84+
apiVersion: openfaas.com/v1
85+
kind: Role
86+
metadata:
87+
name: dev-actions-deployer
88+
namespace: openfaas
89+
spec:
90+
policy:
91+
- dev-rw
92+
condition:
93+
StringEqual:
94+
jwt:iss: ["https://token.actions.githubusercontent.com"]
95+
jwt:repository_owner: ["openfaas"]
96+
StringLike:
97+
jwt:ref: ["refs/heads/*"]
98+
```
99+
100+
The example must match the issuer and organisation name of "openfaas", and can match any branch name.
101+
102+
You could restrict this further by looking at the "actor" for instance.
103+
104+
Finally, you need to apply all of the above objects, and can test it end to end.
105+
106+
See an example [GitHub Actions Workflow](https://github.com/alexellis/minty/blob/master/.github/workflows/federate.yml)

‎docs/openfaas-pro/iam/gitlab-federation.md

+82
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
# GitLab - Web Identity Federation
2+
3+
In this guide, you'll learn how to deploy from GitLab CI/CD using OpenFaaS's IAM support and Web Identity Federation.
4+
5+
You'll need to create YAML files for an Issuer, a Policy and a Role. These need to be applied through kubectl, Helm or a GitOps tool.
6+
7+
Your build will need to be adapted in order to receive an id_token from GitLab, which will be exchanged for an OpenFaaS access token.
8+
9+
## Define an Issuer for GitLab.com
10+
11+
First define a new JwtIssuer resource, setting the `aud` field to the URL of your OpenFaaS Gateway.
12+
13+
```yaml
14+
apiVersion: openfaas.com/v1
15+
kind: JwtIssuer
16+
metadata:
17+
name: token.actions.githubusercontent.com
18+
namespace: openfaas
19+
spec:
20+
iss: https://token.actions.githubusercontent.com
21+
aud:
22+
- https://gw.example.com
23+
tokenExpiry: 30m
24+
```
25+
26+
> Issuer for https://token.actions.githubusercontent.com
27+
28+
## Create a Policy
29+
30+
Next, define a Policy with the least privileges required to perform the desired actions.
31+
32+
```yaml
33+
apiVersion: openfaas.com/v1
34+
kind: Policy
35+
metadata:
36+
name: dev-rw
37+
namespace: openfaas
38+
spec:
39+
statement:
40+
- sid: 1-rw-dev
41+
action:
42+
- Function:Read
43+
- Function:Admin
44+
- Secret:Read
45+
effect: Allow
46+
resource: dev:*
47+
```
48+
49+
## Bind a Policy to a Role
50+
51+
Next, you need to bind the Policy to a Role.
52+
53+
There are around a dozen different fields available within GitLab's `id_token`, you can view a complete list at: [GitLab OIDC: Shared information](https://docs.gitlab.com/ee/integration/openid_connect_provider.html#shared-information)
54+
55+
```yaml
56+
apiVersion: openfaas.com/v1
57+
kind: Role
58+
metadata:
59+
name: gitlab-dev-actions-deployer
60+
namespace: openfaas
61+
spec:
62+
policy:
63+
- dev-rw
64+
condition:
65+
StringEqual:
66+
jwt:iss: ["https://gitlab.com"]
67+
jwt:user_login: ["alexellis"]
68+
StringLike:
69+
jwt:project_path: ["consortia/*"]
70+
```
71+
72+
The example must match the GitLab issuer, for the login of "alexellis", with any project within the "consortia" group.
73+
74+
Within your GitLab job, you must obtain an id_token with the proper audience `aud` field set with the address of your OpenFaaS gateway:
75+
76+
```yaml
77+
id_tokens:
78+
ID_TOKEN_1:
79+
aud: https://gw.example.com
80+
```
81+
82+
See an example repository and `.gitlab-ci.yml` file on GitLab [gitlab.com/consortia/deploy-fn](https://gitlab.com/consortia/deploy-fn/-/blob/main/.gitlab-ci.yml)

0 commit comments

Comments
 (0)