openshift/openshift-docs
1
0
Fork 0
mirror of https://github.com/openshift/openshift-docs.git synced 2026-02-05 12:46:18 +01:00
Code Issues Releases Activity
Files
2ca0fddfdb4cf087bd4fdc08c4e79210d6e335f3
openshift-docs/modules/external-auth-fields.adoc
cbippley c2ec984046 OSDOCS-14026 Adding UID and Extras to table
2025-11-25 14:27:26 +00:00

162 lines
11 KiB
Plaintext
Raw Blame History

// Module included in the following assemblies:
//
// * authentication/external-auth.adoc
:_mod-docs-content-type: PROCEDURE
[id="external-auth-fields_{context}"]
= OIDC provider configuration parameters
// Note: Because this is tech preview, the API docs won't contain this information, so we're including this table now. Consider whether to continue including this table or not once it's GA and in the API docs.
The following table lists all available OIDC provider parameters for direct authentication:
.`oidcProviders` configuration
[cols="1,2",options="header"]
|===
|Parameter
|Description
|`claimMappings`
|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.
|`claimMappings.groups.claim`
|Configures the JWT token claim whose value is assigned to the cluster identity field associated with this mapping.
|`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.
|`claimMappings.username.claim`
|Configures the JWT token claim whose value is assigned to the cluster identity field associated with this mapping.
|`claimMappings.username.prefix`
|Configures the prefix that should be prepended to the value of the JWT claim. Must be set when `prefixPolicy` is set to `Prefix` and must be unset otherwise.
|`claimMappings.username.prefix.prefixString`
|Configures the prefix that is applied to the cluster identity username attribute during the process of mapping JWT claims to cluster identity attributes. Must not be an empty string (`""`).
|`claimMappings.username.prefixPolicy`
|Configures how a prefix should be applied to the value of the JWT claim specified in the `claim` field. Allowed values are `Prefix`, `NoPrefix`, and omitted (not provided or an empty string).
When set to `Prefix`, the value specified in the prefix field is prepended to the value of the JWT claim. The prefix field must be set when `prefixPolicy` is `Prefix`.
When set to `NoPrefix`, no prefix is prepended to the value of the JWT claim.
When omitted, this means no opinion and the platform is left to choose any prefixes that are applied which is subject to change over time.
Currently, the platform prepends `{issuerURL}#` to the value of the JWT claim
when the claim is not `email`.
|`claimValidationRules`
|Configures the rules to be used by the Kubernetes API server for validating the claims in a JWT token issued by the identity provider. Validation rules are joined by an `AND` operation.
|`claimValidationRules.requiredClaim`
|Configures the required claim and value that the Kubernetes API server uses to validate if an incoming JWT is valid for this identity provider.
|`claimValidationRules.requiredClaim.claim`
|Configures the name of the required claim. When taken from the JWT claims, the claim must be a string value. Must not be an empty string (`""`).
|`claimValidationRules.requiredClaim.requiredValue`
|Configures the value that `claim` must have when taken from the incoming JWT claims. If the value in the JWT claims does not match, the token is rejected for authentication. Must not be an empty string (`""`).
|`claimValidationRules.type`
|Configures the type of the validation rule. Allowed values are `RequiredClaim` and omitted (not provided or an empty string).
When set to `RequiredClaim`, the Kubernetes API server is configured to validate that the incoming JWT contains the required claim and that its value matches the required value. The default value is `RequiredClaim`.
|`issuer`
|A required field that configures how the platform interacts with the identity provider and how tokens issued from the identity provider are evaluated by the Kubernetes API server.
|`issuer.audiences`
|A required field that configures the acceptable audiences the JWT token, issued by the identity provider, must be issued to. At least one of the entries must match the `aud` claim in the JWT token. Must contain at least one entry and must not exceed 10 entries.
|`issuer.issuerCertificateAuthority`
|Configures the certificate authority, used by the Kubernetes API server, to validate the connection to the identity provider when fetching discovery information. When not specified, the system trust is used. When specified, it must reference a config map in the `openshift-config` namespace containing the PEM-encoded CA certificates under the `ca-bundle.crt` key in the `data` field of the config map.
|`issuer.issuerCertificateAuthority.name`
|The name of the referenced config map.
|`issuer.issuerURL`
|Configures the URL used to issue tokens by the identity provider. The Kubernetes API server determines how authentication tokens should be handled by matching the `iss` claim in the JWT to the issuerURL of configured identity providers. This field is required and must use the `https://` scheme.
|`name`
|A required field that configures the unique human-readable identifier associated with the identity provider. It is used to distinguish between multiple identity providers and has no impact on token validation or authentication mechanics. Must not be an empty string (`""`).
|`oidcClients`
|Configures how on-cluster, platform clients should request tokens from the identity provider. Must not exceed 20 entries and entries must have unique namespace/name pairs.
|`oidcClients.clientID`
|Configures the client identifier, from the identity provider, that the platform component uses for authentication requests made to the identity provider. The identity provider must accept this identifier for platform components to be able to use the identity provider as an authentication mode. Must not be an empty string (`""`).
|`oidcClients.clientSecret`
|Configures the client secret used by the platform component when making authentication requests to the identity provider.
When not specified, no client secret is used when making authentication requests to the identity provider.
When specified, it references a secret in the `openshift-config` namespace that contains the client secret in the `clientSecret` key of the `.data` field. The client secret is used when making authentication requests to the identity provider.
Public clients do not require a client secret, but private clients do require a client secret to work with the identity provider.
|`oidcClients.clientSecret.name`
|The name of the referenced secret.
|`oidcClients.componentName`
|Specifies the name of the platform component being configured to use the identity provider as an authentication mode. It is used in combination with `componentNamespace` as a unique identifier. Must not be an empty string (`""`) and must not exceed 256 characters in length.
|`oidcClients.componentNamespace`
|Specifies the namespace in which the platform component being configured to use the identity provider as an authentication mode is running. It is used in combination with `componentName` as a unique identifier. Must not be an empty string (`""`) and must not exceed 63 characters in length.
|`oidcClients.extraScopes`
|Configures the extra scopes that should be requested by the platform component when making authentication requests to the identity provider. This is useful if you have configured claim mappings that require specific scopes to be requested beyond the standard OIDC scopes. When omitted, no additional scopes are requested.
|===
View Git Blame Copy Permalink