Chapter 3. Authentication [config.openshift.io/v1]

oauthMetadata

object

oauthMetadata contains the discovery endpoint data for OAuth 2.0 Authorization Server Metadata for an external OAuth server. This discovery document can be viewed from its served location: oc get --raw '/.well-known/oauth-authorization-server' For further details, see the IETF Draft: https://tools.ietf.org/html/draft-ietf-oauth-discovery-04#section-2 If oauthMetadata.name is non-empty, this value has precedence over any metadata reference stored in status. The key "oauthMetadata" is used to locate the data. If specified and the config map or expected key is not found, no metadata is served. If the specified metadata is not valid, no metadata is served. The namespace for this config map is openshift-config.

oidcProviders

array

oidcProviders are OIDC identity providers that can issue tokens for this cluster Can only be set if "Type" is set to "OIDC".

At most one provider can be configured.

oidcProviders[]

object

serviceAccountIssuer

string

serviceAccountIssuer is the identifier of the bound service account token issuer. The default is https://kubernetes.default.svc WARNING: Updating this field will not result in immediate invalidation of all bound tokens with the previous issuer value. Instead, the tokens issued by previous service account issuer will continue to be trusted for a time period chosen by the platform (currently set to 24h). This time period is subject to change over time. This allows internal components to transition to use new service account issuer without service distruption.

type

string

type identifies the cluster managed, user facing authentication mode in use. Specifically, it manages the component that responds to login attempts. The default is IntegratedOAuth.

webhookTokenAuthenticator

object

webhookTokenAuthenticator configures a remote token reviewer. These remote authentication webhooks can be used to verify bearer tokens via the tokenreviews.authentication.k8s.io REST API. This is required to honor bearer tokens that are provisioned by an external authentication service.

Can only be set if "Type" is set to "None".

webhookTokenAuthenticators

array

webhookTokenAuthenticators is DEPRECATED, setting it has no effect.

webhookTokenAuthenticators[]

object

deprecatedWebhookTokenAuthenticator holds the necessary configuration options for a remote token authenticator. It’s the same as WebhookTokenAuthenticator but it’s missing the 'required' validation on KubeConfig field.

name

string

name is the metadata.name of the referenced config map

claimMappings

object

claimMappings is a required field that 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.

claimValidationRules

array

claimValidationRules is an optional field that 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 via an AND operation.

claimValidationRules[]

object

issuer

object

issuer is 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.

name

string

name is 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.

name must not be an empty string ("").

oidcClients

array

oidcClients is an optional field that configures how on-cluster, platform clients should request tokens from the identity provider. oidcClients must not exceed 20 entries and entries must have unique namespace/name pairs.

oidcClients[]

object

OIDCClientConfig configures how platform clients interact with identity providers as an authentication method

extra

array

extra is 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.

extra[]

object

ExtraMapping allows specifying a key and CEL expression to evaluate the keys' value. It is used to create additional mappings and attributes added to a cluster identity from a provided authentication token.

groups

object

groups is an optional field that 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 list of groups separated by a comma (','). For example - '"example"' and '"exampleOne", "exampleTwo", "exampleThree"' are valid claim values.

uid

object

uid is an optional field for configuring the claim mapping used to construct the uid for the cluster identity.

When using uid.claim to specify the claim it must be a single string value. When using uid.expression the expression must result in a single string value.

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.

username

object

username is a required field that configures how the username of a cluster identity should be constructed from the claims in a JWT token issued by the identity provider.

key

string

key is a required field that specifies the string to use as the extra attribute key.

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 prior to 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 ':'. It must not exceed 256 characters in length.

valueExpression

string

valueExpression is a required field to specify the CEL expression to extract the extra attribute value from a JWT token’s claims. valueExpression must produce a string or string array value. "", [], and null are treated as the extra mapping not being present. Empty string values within an array are filtered out.

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').

valueExpression must not exceed 1024 characters in length. valueExpression must not be empty.

claim

string

claim is a required field that configures the JWT token claim whose value is assigned to the cluster identity field associated with this mapping.

prefix

string

prefix is an optional field that configures the prefix that will be applied to the cluster identity attribute during the process of mapping JWT claims to cluster identity attributes.

When omitted (""), no prefix is applied to the cluster identity attribute.

Example: if prefix is set to "myoidc:" and the claim in JWT contains an array of strings "a", "b" and "c", the mapping will result in an array of string "myoidc:a", "myoidc:b" and "myoidc:c".

claim

string

claim is 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.

Precisely one of claim or expression must be set. claim must not be specified when expression is set. When specified, claim must be at least 1 character in length and must not exceed 256 characters in length.

expression

string

expression is an optional field for specifying a CEL expression that produces a string value from JWT token claims.

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').

Precisely one of claim or expression must be set. expression must not be specified when claim is set. When specified, expression must be at least 1 character in length and must not exceed 1024 characters in length.

claim

string

claim is a required field that configures the JWT token claim whose value is assigned to the cluster identity field associated with this mapping.

claim must not be an empty string ("") and must not exceed 256 characters.

prefix

object

prefix configures the prefix that should be prepended to the value of the JWT claim.

prefix must be set when prefixPolicy is set to 'Prefix' and must be unset otherwise.

prefixPolicy

string

prefixPolicy is an optional field that 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 will be prepended to the value of the JWT claim. The prefix field must be set when prefixPolicy is 'Prefix'.

When set to 'NoPrefix', no prefix will be 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'. As an example, consider the following scenario: prefix is unset, issuerURL is set to https://myoidc.tld, the JWT claims include "username":"userA" and "email":"userA@myoidc.tld", and claim is set to: - "username": the mapped value will be "https://myoidc.tld#userA" - "email": the mapped value will be "userA@myoidc.tld"

prefixString

string

prefixString is a required field that configures the prefix that will be applied to cluster identity username attribute during the process of mapping JWT claims to cluster identity attributes.

prefixString must not be an empty string ("").

requiredClaim

object

requiredClaim is an optional field that configures the required claim and value that the Kubernetes API server will use to validate if an incoming JWT is valid for this identity provider.

type

string

type is an optional field that 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 will be configured to validate that the incoming JWT contains the required claim and that its value matches the required value.

Defaults to 'RequiredClaim'.

claim

string

claim is a required field that configures the name of the required claim. When taken from the JWT claims, claim must be a string value.

claim must not be an empty string ("").

requiredValue

string

requiredValue is a required field that 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 will be rejected for authentication.

requiredValue must not be an empty string ("").

audiences

array (string)

audiences is 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.

audiences must contain at least one entry and must not exceed ten entries.

issuerCertificateAuthority

object

issuerCertificateAuthority is an optional field that 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 ConfigMap in the openshift-config namespace containing the PEM-encoded CA certificates under the 'ca-bundle.crt' key in the data field of the ConfigMap.

issuerURL

string

issuerURL is a required field that 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.

Must be at least 1 character and must not exceed 512 characters in length. Must be a valid URL that uses the 'https' scheme and does not contain a query, fragment or user.

name

string

name is the metadata.name of the referenced config map

clientID

string

clientID is a required field that 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.

clientID must not be an empty string ("").

clientSecret

object

clientSecret is an optional field that configures the client secret used by the platform component when making authentication requests to the identity provider.

When not specified, no client secret will be used when making authentication requests to the identity provider.

When specified, clientSecret references a Secret in the 'openshift-config' namespace that contains the client secret in the 'clientSecret' key of the '.data' field. The client secret will be 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.

componentName

string

componentName is a required field that 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.

componentName must not be an empty string ("") and must not exceed 256 characters in length.

componentNamespace

string

componentNamespace is a required field that 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.

componentNamespace must not be an empty string ("") and must not exceed 63 characters in length.

extraScopes

array (string)

extraScopes is an optional field that 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 requires specific scopes to be requested beyond the standard OIDC scopes.

When omitted, no additional scopes are requested.

name

string

name is the metadata.name of the referenced secret

kubeConfig

object

kubeConfig references a secret that contains kube config file data which describes how to access the remote webhook service. The namespace for the referenced secret is openshift-config.

For further details, see:

https://kubernetes.io/docs/reference/access-authn-authz/authentication/#webhook-token-authentication

The key "kubeConfig" is used to locate the data. If the secret or expected key is not found, the webhook is not honored. If the specified kube config data is not valid, the webhook is not honored.

name

string

name is the metadata.name of the referenced secret

kubeConfig

object

kubeConfig contains kube config file data which describes how to access the remote webhook service. For further details, see: https://kubernetes.io/docs/reference/access-authn-authz/authentication/#webhook-token-authentication The key "kubeConfig" is used to locate the data. If the secret or expected key is not found, the webhook is not honored. If the specified kube config data is not valid, the webhook is not honored. The namespace for this secret is determined by the point of use.

name

string

name is the metadata.name of the referenced secret

integratedOAuthMetadata

object

integratedOAuthMetadata contains the discovery endpoint data for OAuth 2.0 Authorization Server Metadata for the in-cluster integrated OAuth server. This discovery document can be viewed from its served location: oc get --raw '/.well-known/oauth-authorization-server' For further details, see the IETF Draft: https://tools.ietf.org/html/draft-ietf-oauth-discovery-04#section-2 This contains the observed value based on cluster state. An explicitly set value in spec.oauthMetadata has precedence over this field. This field has no meaning if authentication spec.type is not set to IntegratedOAuth. The key "oauthMetadata" is used to locate the data. If the config map or expected key is not found, no metadata is served. If the specified metadata is not valid, no metadata is served. The namespace for this config map is openshift-config-managed.

oidcClients

array

oidcClients is where participating operators place the current OIDC client status for OIDC clients that can be customized by the cluster-admin.

oidcClients[]

object

OIDCClientStatus represents the current state of platform components and how they interact with the configured identity providers.

name

string

name is the metadata.name of the referenced config map

componentName

string

componentName is a required field that specifies the name of the platform component using the identity provider as an authentication mode. It is used in combination with componentNamespace as a unique identifier.

componentName must not be an empty string ("") and must not exceed 256 characters in length.

componentNamespace

string

componentNamespace is a required field that specifies the namespace in which the platform component using the identity provider as an authentication mode is running. It is used in combination with componentName as a unique identifier.

componentNamespace must not be an empty string ("") and must not exceed 63 characters in length.

conditions

array

conditions are used to communicate the state of the oidcClients entry.

Supported conditions include Available, Degraded and Progressing.

If Available is true, the component is successfully using the configured client. If Degraded is true, that means something has gone wrong trying to handle the client configuration. If Progressing is true, that means the component is taking some action related to the oidcClients entry.

conditions[]

object

Condition contains details for one aspect of the current state of this API Resource.

consumingUsers

array (string)

consumingUsers is an optional list of ServiceAccounts requiring read permissions on the clientSecret secret.

consumingUsers must not exceed 5 entries.

currentOIDCClients

array

currentOIDCClients is an optional list of clients that the component is currently using. Entries must have unique issuerURL/clientID pairs.

currentOIDCClients[]

object

OIDCClientReference is a reference to a platform component client configuration.

lastTransitionTime

string

lastTransitionTime is the last time the condition transitioned from one status to another. This should be when the underlying condition changed. If that is not known, then using the time when the API field changed is acceptable.

message

string

message is a human readable message indicating details about the transition. This may be an empty string.

observedGeneration

integer

observedGeneration represents the .metadata.generation that the condition was set based upon. For instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date with respect to the current state of the instance.

reason

string

reason contains a programmatic identifier indicating the reason for the condition’s last transition. Producers of specific condition types may define expected values and meanings for this field, and whether the values are considered a guaranteed API. The value should be a CamelCase string. This field may not be empty.

status

string

status of the condition, one of True, False, Unknown.

type

string

type of condition in CamelCase or in foo.example.com/CamelCase.

clientID

string

clientID is a required field that specifies the client identifier, from the identity provider, that the platform component is using for authentication requests made to the identity provider.

clientID must not be empty.

issuerURL

string

issuerURL is a required field that specifies the URL of the identity provider that this client is configured to make requests against.

issuerURL must use the 'https' scheme.

oidcProviderName

string

oidcProviderName is a required reference to the 'name' of the identity provider configured in 'oidcProviders' that this client is associated with.

oidcProviderName must not be an empty string ("").

200 - OK

Status schema

401 - Unauthorized

Empty

200 - OK

AuthenticationList schema

401 - Unauthorized

Empty

dryRun

string

When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed

fieldValidation

string

fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered.

body

Authentication schema

200 - OK

Authentication schema

201 - Created

Authentication schema

202 - Accepted

Authentication schema

401 - Unauthorized

Empty

name

string

name of the Authentication

dryRun

string

When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed

200 - OK

Status schema

202 - Accepted

Status schema

401 - Unauthorized

Empty

200 - OK

Authentication schema

401 - Unauthorized

Empty

dryRun

string

When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed

fieldValidation

string

fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered.

200 - OK

Authentication schema

401 - Unauthorized

Empty

dryRun

string

When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed

fieldValidation

string

fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered.

body

Authentication schema

200 - OK

Authentication schema

201 - Created

Authentication schema

401 - Unauthorized

Empty

name

string

name of the Authentication

200 - OK

Authentication schema

401 - Unauthorized

Empty

dryRun

string

When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed

fieldValidation

string

fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered.

200 - OK

Authentication schema

401 - Unauthorized

Empty

dryRun

string

When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed

fieldValidation

string

fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered.

body

Authentication schema

200 - OK

Authentication schema

201 - Created

Authentication schema

401 - Unauthorized

Empty