Skip to content

Commit 1c11747

Browse files
xrstfxrstf
committed
add documentation
On-behalf-of: @SAP [email protected]
1 parent 242e852 commit 1c11747

File tree

2 files changed

+271
-134
lines changed

2 files changed

+271
-134
lines changed

‎docs/content/concepts/authentication/oidc.md‎

Lines changed: 128 additions & 134 deletions
Original file line numberDiff line numberDiff line change
@@ -8,170 +8,164 @@ description: >
88
OpenID Connect (OIDC) is a simple identity layer on top of the OAuth 2.0 protocol, which allows clients to verify the identity of users based on the authentication performed by an external authorization server. In this guide, we will set up OIDC authentication in kcp using Dex as the identity provider.
99
For more details on Kubernetes specific configuration, please refer to this [page](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#openid-connect-tokens).
1010

11-
1211
## Configure kcp OIDC Authentication Using OIDC Flags
1312

1413
kcp server will configure the OIDC authentication using the same Kubernetes control plane settings, to start kcp with OIDC authentication enabled, you can simply pass OIDC flags during the start of the kcp server:
1514

1615
```bash
1716
kcp start \
18-
--oidc-issuer-url=<url of the issuer> \
19-
--oidc-client-id=<client-id>\
20-
--oidc-groups-claim=<jwt-claim-name> \
21-
--oidc-ca-file=<ca-file-path>
17+
--oidc-issuer-url "<url of the issuer>" \
18+
--oidc-client-id "<client-id>" \
19+
--oidc-groups-claim "<jwt-claim-name>" \
20+
--oidc-ca-file "<ca-file-path>"
2221
```
2322

24-
- `--oidc-issuer-url` URL of the provider that allows the API server to discover public signing keys.
25-
26-
- `--oidc-client-id` A client id that all tokens must be issued for.
27-
28-
- `--oidc-groups-claim` JWT claim to use as the user's group.
29-
30-
- `--oidc-ca-file` The path to the certificate for the CA that signed your identity provider's web certificate.
23+
- `--oidc-issuer-url` – URL of the provider that allows the API server to discover public signing keys.
24+
- `--oidc-client-id` – A client ID that all tokens must be issued for.
25+
- `--oidc-groups-claim` – JWT claim to use as the user's group.
26+
- `--oidc-ca-file` – The path to the certificate for the CA that signed your identity provider's web certificate.
3127

3228
You can also set:
3329

34-
- `--oidc-username-claim` JWT claim to use as the user name.
35-
36-
- `--oidc-required-claim` A key=value pair that describes a required claim in the ID Token.
37-
38-
- `--oidc-signing-algs` The signing algorithms accepted.
39-
40-
- `--oidc-username-prefix` Prefix prepended to username claims to prevent clashes with existing names.
41-
42-
- `--oidc-groups-prefix` Prefix prepended to group claims to prevent clashes with existing names
30+
- `--oidc-username-claim` – JWT claim to use as the user name.
31+
- `--oidc-required-claim` – A key=value pair that describes a required claim in the ID Token.
32+
- `--oidc-signing-algs` – The signing algorithms accepted.
33+
- `--oidc-username-prefix` – Prefix prepended to username claims to prevent clashes with existing names.
34+
- `--oidc-groups-prefix` – Prefix prepended to group claims to prevent clashes with existing names
4335

4436
## Configure kcp OIDC Authentication Using Structured Authentication Configuration
4537

4638
Alternatively, you can use the beta feature of authentication configuration from a file and set up the kcp server with it.
4739
Please note that if you specify `--authentication-config` along with any of the `--oidc-*` command line arguments, this will be treated as a misconfiguration.
4840

49-
```bash
41+
```yaml
5042
apiVersion: apiserver.config.k8s.io/v1beta1
5143
kind: AuthenticationConfiguration
5244
# list of authenticators to authenticate Kubernetes users using JWT compliant tokens.
5345
# the maximum number of allowed authenticators is 64.
5446
jwt:
55-
- issuer:
56-
# url must be unique across all authenticators.
57-
# url must not conflict with issuer configured in --service-account-issuer.
58-
url: https://example.com # Same as --oidc-issuer-url.
59-
# discoveryURL, if specified, overrides the URL used to fetch discovery
60-
# information instead of using "{url}/.well-known/openid-configuration".
61-
# The exact value specified is used, so "/.well-known/openid-configuration"
62-
# must be included in discoveryURL if needed.
63-
#
64-
# The "issuer" field in the fetched discovery information must match the "issuer.url" field
65-
# in the AuthenticationConfiguration and will be used to validate the "iss" claim in the presented JWT.
66-
# This is for scenarios where the well-known and jwks endpoints are hosted at a different
67-
# location than the issuer (such as locally in the cluster).
68-
# discoveryURL must be different from url if specified and must be unique across all authenticators.
69-
discoveryURL: https://discovery.example.com/.well-known/openid-configuration
70-
# PEM encoded CA certificates used to validate the connection when fetching
71-
# discovery information. If not set, the system verifier will be used.
72-
# Same value as the content of the file referenced by the --oidc-ca-file flag.
73-
certificateAuthority: <PEM encoded CA certificates>
74-
# audiences is the set of acceptable audiences the JWT must be issued to.
75-
# At least one of the entries must match the "aud" claim in presented JWTs.
76-
audiences:
77-
- my-app # Same as --oidc-client-id.
78-
- my-other-app
79-
# this is required to be set to "MatchAny" when multiple audiences are specified.
80-
audienceMatchPolicy: MatchAny
81-
# rules applied to validate token claims to authenticate users.
82-
claimValidationRules:
83-
# Same as --oidc-required-claim key=value.
84-
- claim: hd
85-
requiredValue: example.com
86-
# Instead of claim and requiredValue, you can use expression to validate the claim.
87-
# expression is a CEL expression that evaluates to a boolean.
88-
# all the expressions must evaluate to true for validation to succeed.
89-
- expression: 'claims.hd == "example.com"'
90-
# Message customizes the error message seen in the API server logs when the validation fails.
91-
message: the hd claim must be set to example.com
92-
- expression: 'claims.exp - claims.nbf <= 86400'
93-
message: total token lifetime must not exceed 24 hours
94-
claimMappings:
95-
# username represents an option for the username attribute.
96-
# This is the only required attribute.
97-
username:
98-
# Same as --oidc-username-claim. Mutually exclusive with username.expression.
99-
claim: "sub"
100-
# Same as --oidc-username-prefix. Mutually exclusive with username.expression.
101-
# if username.claim is set, username.prefix is required.
102-
# Explicitly set it to "" if no prefix is desired.
103-
prefix: ""
104-
# Mutually exclusive with username.claim and username.prefix.
105-
# expression is a CEL expression that evaluates to a string.
47+
- issuer:
48+
# url must be unique across all authenticators.
49+
# url must not conflict with issuer configured in --service-account-issuer.
50+
url: https://example.com # Same as --oidc-issuer-url.
51+
# discoveryURL, if specified, overrides the URL used to fetch discovery
52+
# information instead of using "{url}/.well-known/openid-configuration".
53+
# The exact value specified is used, so "/.well-known/openid-configuration"
54+
# must be included in discoveryURL if needed.
10655
#
107-
# 1. If username.expression uses 'claims.email', then 'claims.email_verified' must be used in
108-
# username.expression or extra[*].valueExpression or claimValidationRules[*].expression.
109-
# An example claim validation rule expression that matches the validation automatically
110-
# applied when username.claim is set to 'email' is 'claims.?email_verified.orValue(true) == true'.
111-
# By explicitly comparing the value to true, we let type-checking see the result will be a boolean, and
112-
# to make sure a non-boolean email_verified claim will be caught at runtime.
113-
# 2. If the username asserted based on username.expression is the empty string, the authentication
114-
# request will fail.
115-
expression: 'claims.username + ":external-user"'
116-
# groups represents an option for the groups attribute.
117-
groups:
118-
# Same as --oidc-groups-claim. Mutually exclusive with groups.expression.
119-
claim: "sub"
120-
# Same as --oidc-groups-prefix. Mutually exclusive with groups.expression.
121-
# if groups.claim is set, groups.prefix is required.
122-
# Explicitly set it to "" if no prefix is desired.
123-
prefix: ""
124-
# Mutually exclusive with groups.claim and groups.prefix.
125-
# expression is a CEL expression that evaluates to a string or a list of strings.
126-
expression: 'claims.roles.split(",")'
127-
# uid represents an option for the uid attribute.
128-
uid:
129-
# Mutually exclusive with uid.expression.
130-
claim: 'sub'
131-
# Mutually exclusive with uid.claim
132-
# expression is a CEL expression that evaluates to a string.
133-
expression: 'claims.sub'
134-
# extra attributes to be added to the UserInfo object. Keys must be domain-prefix path and must be unique.
135-
extra:
136-
# key is a string to use as the extra attribute key.
137-
# key must be a domain-prefix path (e.g. example.org/foo). All characters before the first "/" must be a valid
138-
# subdomain as defined by RFC 1123. All characters trailing the first "/" must
139-
# be valid HTTP Path characters as defined by RFC 3986.
140-
# k8s.io, kubernetes.io and their subdomains are reserved for Kubernetes use and cannot be used.
141-
# key must be lowercase and unique across all extra attributes.
142-
- key: 'example.com/tenant'
143-
# valueExpression is a CEL expression that evaluates to a string or a list of strings.
144-
valueExpression: 'claims.tenant'
145-
# validation rules applied to the final user object.
146-
userValidationRules:
147-
# expression is a CEL expression that evaluates to a boolean.
148-
# all the expressions must evaluate to true for the user to be valid.
149-
- expression: "!user.username.startsWith('system:')"
150-
# Message customizes the error message seen in the API server logs when the validation fails.
151-
message: 'username cannot used reserved system: prefix'
152-
- expression: "user.groups.all(group, !group.startsWith('system:'))"
153-
message: 'groups cannot used reserved system: prefix'
56+
# The "issuer" field in the fetched discovery information must match the "issuer.url" field
57+
# in the AuthenticationConfiguration and will be used to validate the "iss" claim in the presented JWT.
58+
# This is for scenarios where the well-known and jwks endpoints are hosted at a different
59+
# location than the issuer (such as locally in the cluster).
60+
# discoveryURL must be different from url if specified and must be unique across all authenticators.
61+
discoveryURL: https://discovery.example.com/.well-known/openid-configuration
62+
# PEM encoded CA certificates used to validate the connection when fetching
63+
# discovery information. If not set, the system verifier will be used.
64+
# Same value as the content of the file referenced by the --oidc-ca-file flag.
65+
certificateAuthority: <PEM encoded CA certificates>
66+
# audiences is the set of acceptable audiences the JWT must be issued to.
67+
# At least one of the entries must match the "aud" claim in presented JWTs.
68+
# Note that when per-workspace authentication is used, every token admitted into a workspace
69+
# must also match these audiences, regardless of the workspace's configuration.
70+
audiences:
71+
- my-app # Same as --oidc-client-id.
72+
- my-other-app
73+
# this is required to be set to "MatchAny" when multiple audiences are specified.
74+
audienceMatchPolicy: MatchAny
75+
# rules applied to validate token claims to authenticate users.
76+
claimValidationRules:
77+
# Same as --oidc-required-claim key=value.
78+
- claim: hd
79+
requiredValue: example.com
80+
# Instead of claim and requiredValue, you can use expression to validate the claim.
81+
# expression is a CEL expression that evaluates to a boolean.
82+
# all the expressions must evaluate to true for validation to succeed.
83+
- expression: 'claims.hd == "example.com"'
84+
# Message customizes the error message seen in the API server logs when the validation fails.
85+
message: the hd claim must be set to example.com
86+
- expression: 'claims.exp - claims.nbf <= 86400'
87+
message: total token lifetime must not exceed 24 hours
88+
claimMappings:
89+
# username represents an option for the username attribute.
90+
# This is the only required attribute.
91+
username:
92+
# Same as --oidc-username-claim. Mutually exclusive with username.expression.
93+
claim: "sub"
94+
# Same as --oidc-username-prefix. Mutually exclusive with username.expression.
95+
# if username.claim is set, username.prefix is required.
96+
# Explicitly set it to "" if no prefix is desired.
97+
prefix: ""
98+
# Mutually exclusive with username.claim and username.prefix.
99+
# expression is a CEL expression that evaluates to a string.
100+
#
101+
# 1. If username.expression uses 'claims.email', then 'claims.email_verified' must be used in
102+
# username.expression or extra[*].valueExpression or claimValidationRules[*].expression.
103+
# An example claim validation rule expression that matches the validation automatically
104+
# applied when username.claim is set to 'email' is 'claims.?email_verified.orValue(true) == true'.
105+
# By explicitly comparing the value to true, we let type-checking see the result will be a boolean, and
106+
# to make sure a non-boolean email_verified claim will be caught at runtime.
107+
# 2. If the username asserted based on username.expression is the empty string, the authentication
108+
# request will fail.
109+
expression: 'claims.username + ":external-user"'
110+
# groups represents an option for the groups attribute.
111+
groups:
112+
# Same as --oidc-groups-claim. Mutually exclusive with groups.expression.
113+
claim: "sub"
114+
# Same as --oidc-groups-prefix. Mutually exclusive with groups.expression.
115+
# if groups.claim is set, groups.prefix is required.
116+
# Explicitly set it to "" if no prefix is desired.
117+
prefix: ""
118+
# Mutually exclusive with groups.claim and groups.prefix.
119+
# expression is a CEL expression that evaluates to a string or a list of strings.
120+
expression: 'claims.roles.split(",")'
121+
# uid represents an option for the uid attribute.
122+
uid:
123+
# Mutually exclusive with uid.expression.
124+
claim: 'sub'
125+
# Mutually exclusive with uid.claim
126+
# expression is a CEL expression that evaluates to a string.
127+
expression: 'claims.sub'
128+
# extra attributes to be added to the UserInfo object. Keys must be domain-prefix path and must be unique.
129+
extra:
130+
# key is a string to use as the extra attribute key.
131+
# key must be a domain-prefix path (e.g. example.org/foo). All characters before the first "/" must be a valid
132+
# subdomain as defined by RFC 1123. All characters trailing the first "/" must
133+
# be valid HTTP Path characters as defined by RFC 3986.
134+
# k8s.io, kubernetes.io and their subdomains are reserved for Kubernetes use and cannot be used.
135+
# key must be lowercase and unique across all extra attributes.
136+
- key: 'example.com/tenant'
137+
# valueExpression is a CEL expression that evaluates to a string or a list of strings.
138+
valueExpression: 'claims.tenant'
139+
# validation rules applied to the final user object.
140+
userValidationRules:
141+
# expression is a CEL expression that evaluates to a boolean.
142+
# all the expressions must evaluate to true for the user to be valid.
143+
- expression: "!user.username.startsWith('system:')"
144+
# Message customizes the error message seen in the API server logs when the validation fails.
145+
message: 'username cannot used reserved system: prefix'
146+
- expression: "user.groups.all(group, !group.startsWith('system:'))"
147+
message: 'groups cannot used reserved system: prefix'
154148
```
155149
156150
To set up the AuthenticationConfiguration, similarly to the previous example with OIDC flags(`--oidc-issuer-url`, `--oidc-client-id`, `--oidc-groups-claim`, `--oidc-ca-file`), you can set it in the file:
157151

158-
```bash
152+
```yaml
159153
apiVersion: apiserver.config.k8s.io/v1beta1
160154
kind: AuthenticationConfiguration
161155
jwt:
162-
- issuer:
163-
url: <url of the issuer>
164-
certificateAuthority: |
165-
<ca-file-content>
166-
audiences:
167-
- <client-id>
168-
audienceMatchPolicy: MatchAny
169-
claimMappings:
170-
groups:
171-
claim: <jwt-claim-name>
172-
prefix: ""
173-
claimValidationRules: []
174-
userValidationRules: []
156+
- issuer:
157+
url: <url of the issuer>
158+
certificateAuthority: |
159+
<ca-file-content>
160+
audiences:
161+
- <client-id>
162+
audienceMatchPolicy: MatchAny
163+
claimMappings:
164+
groups:
165+
claim: <jwt-claim-name>
166+
prefix: ""
167+
claimValidationRules: []
168+
userValidationRules: []
175169
```
176170

177171
To start the kcp server with the specified OIDC authentication configuration, pass the file path to the `--authentication-config` flag.

0 commit comments

Comments
 (0)