Skip to content

OSDOCS-14026 Adding UID and Extras to table #100764

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

OSDOCS-14026 Adding UID and Extras to table #100764

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
59 changes: 32 additions & 27 deletions modules/external-auth-configuring.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -64,48 +64,53 @@ kind: Authentication
metadata:
# ...
spec:
oidcProviders: <1>
type: OIDC # <1>
webhookTokenAuthenticator: null # <2>
oidcProviders: # <3>
- claimMappings:
extra: # <4>
- key: example.com/role
valueExpression: claims.?role.orValue("unknown")
groups:
claim: groups <2>
claim: groups # <5>
prefix: 'oidc-groups-test:'
uid: # <6>
claim: "sub"
username:
claim: email <3>
claim: email #<7>
prefixPolicy: Prefix
prefix:
prefixString: 'oidc-user-test:'
issuer:
audiences: <4>
audiences: # <8>
- console-test
- oc-cli-test
issuerCertificateAuthority:
name: keycloak-oidc-ca <5>
issuerURL: https://keycloak-keycloak.apps.example.com/realms/master <6>
name: 'keycloak-oidc-server' <7>
name: keycloak-oidc-ca # <9>
issuerURL: https://keycloak-keycloak.apps.example.com/realms/master # <10>
name: 'keycloak-oidc-server' # <11>
oidcClients:
- clientID: oc-cli-test <8>
- clientID: oc-cli-test # <12>
componentName: cli
componentNamespace: openshift-console
- clientID: console-test <9>
- clientID: console-test # <13>
clientSecret:
name: console-secret <10>
componentName: console
componentNamespace: openshift-console
type: OIDC <11>
webhookTokenAuthenticator: null <12>
----
<1> The OIDC provider configuration. Currently, only one OIDC provider configuration is allowed.
<2> The name of the claim to construct group names for the cluster identity.
<3> The name of the claim to construct usernames for the cluster identity.
<4> The list of audiences that this authentication provider issues tokens for.
<5> The name of the config map that contains the `ca-bundle.crt` key. If unset, system trust is used instead.
<6> The URL for the token issuer.
<7> The name for external OIDC provider.
<8> The client ID that your provider uses for the {oc-first}.
<9> The client ID that your provider uses for the {product-title} web console.
<10> The name of the secret that stores the secret value for the console client.
<11> Must be set to `OIDC` to indicate to use an external OIDC identity provider.
<12> Must be set to `null` when `type` is set to `OIDC`.
name: console-secret # <14>
----
<1> Must be set to `OIDC` to indicate to use an external OIDC identity provider.
<2> Must be set to `null` when `type` is set to `OIDC`.
<3> The OIDC provider configuration. Currently, only one OIDC provider configuration is allowed.
<4> An optional field for configuring the mappings used to construct the extra attributes for the cluster identity.
<5> The name of the claim to construct group names for the cluster identity.
<6> An optional field for configuring the claim mapping used to construct the uid for the cluster identity.
<7> The name of the claim to construct usernames for the cluster identity.
<8> The list of audiences that this authentication provider issues tokens for.
<9> The name of the config map that contains the `ca-bundle.crt` key. If unset, system trust is used instead.
<10> The URL for the token issuer.
<11> The name for external OIDC provider.
<12> The client ID that your provider uses for the {oc-first}.
<13> The client ID that your provider uses for the {product-title} web console.
<14> The name of the secret that stores the secret value for the console client.
+
For more details on all available parameters, see "OIDC provider configuration parameters".

Expand Down
46 changes: 45 additions & 1 deletion modules/external-auth-fields.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,36 @@ The following table lists all available OIDC provider parameters for direct auth
|Description

|`claimMappings`
|Configures the rules to be used by the Kubernetes API server for translating claims in a JWT token, issued by the identity provider, to a cluster identity.
|Configures the rules to be used by the Kubernetes API server for translating claims in a JSON web token (JWT), issued by the identity provider, to a cluster identity.

|`claimMappings.extra`
|An optional field for configuring the mappings used to construct the extra attribute for the cluster identity. When omitted, no extra attributes will be present on the cluster identity. Key values for extra mappings must be unique. A maximum of 32 extra attribute mappings may be provided.

|`claimMappings.extra.key`
a|A required field that specifies the string to use as the extra attribute key. The following restrictions apply:

* Key must be a domain-prefix path (e.g `example.org/foo`).
* Key must not exceed 510 characters in length.
* Key must contain the `/` character, separating the domain and path characters.
* Key must not be empty.
* The domain portion of the key (string of characters before the `/`) must be a valid RFC1123 subdomain.
* It must not exceed 253 characters in length.
* It must start and end with an alphanumeric character.
* It must only contain lower case alphanumeric characters and `-` or `.`.
* It must not use the reserved domains, or be subdomains of, `kubernetes.io`, `k8s.io`, and `openshift.io`.
* The path portion of the key (string of characters after the `/`) must not be empty and must consist of at least one alphanumeric character, percent-encoded octets, `-`, `.`, `_`, `~`, `!`, `$`, `&`, `'`, `(`, `)`, `*`, `+`, `,`, `;`, `=`, and `:`.
* Domain portion of the key must not exceed 256 characters in length.

|`claimMappings.extra.valueExpression`
a|A required field to specify the CEL expression to extract the extra attribute value from claims of a JWT token. The `valueExpression` field must produce a string or string array value. The following restrictions apply:

* CEL expressions that return "", [], and null are treated as the extra mapping not being present.
* Empty string values within an array are filtered out. For example, [`one`, ``, `three`] becomes [`one`, `three`].
* CEL expressions have access to the token claims through a CEL variable, `claims`.
* `claims` is a map of claim names to claim values. For example, the `sub` claim value can be accessed as `claims.sub`.
* Nested claims can be accessed using dot notation (`claims.foo.bar`).
* The `valueExpression` value must not exceed 1024 characters in length.
* The `valueExpression` value must not be empty.

|`claimMappings.groups`
|Configures how the groups of a cluster identity should be constructed from the claims in a JWT token issued by the identity provider. When referencing a claim, if the claim is present in the JWT token, its value must be a comma-separated list of groups.
Expand All @@ -28,6 +57,21 @@ The following table lists all available OIDC provider parameters for direct auth
|`claimMappings.groups.prefix`
|Configures the prefix that is applied to the cluster identity attribute during the process of mapping JWT claims to cluster identity attributes.

|`claimMappings.uid`
| An optional field for configuring the claim mapping used to construct the UID for the cluster identity. When omitted, this means the user has no opinion and the platform is left to choose a default, which is subject to change over time. The current default is to use the `sub` claim.

|`claimMappings.uid.claim`
|An optional field for specifying the JWT token claim that is used in the mapping. The value of this claim will be assigned to the field in which this mapping is associated. To specify the claim, use a single string value for `uid.claim`.

You must set either `claim` or `expression`. Do not specify `claim` when `expression` is set. The value of `claim` must be at least 1 character and must not exceed 256 characters in length.

|`claimMappings.uid.expression`
|An optional field for specifying a CEL expression that produces a string value from JWT token claims. When using `uid.expression` the expression must result in a single string value.

CEL expressions have access to the token claims through a CEL variable, `claims`. The `claims` variable is a map of claim names to claim values. For example, you can access the `sub` claim value as `claims.sub`. Nested claims can be accessed using dot notation for example, `claims.foo.bar`.

You must set either `claim` or `expression`. Do not specify `expression` when `claim` is set. The value of `expression` must be at least 1 character and must not exceed 1024 characters in length.

|`claimMappings.username`
|Configures how the username of a cluster identity should be constructed from the claims in a JWT token issued by the identity provider.

Expand Down