Chapter 9. Configuring advanced direct authentication fields

Procedure

1. Create a YAML file named authentication-discovery-url.yaml with your custom discovery URL configuration:

   apiVersion: config.openshift.io/v1
   kind: Authentication
   metadata:
     name: cluster
   spec:
     type: OIDC
     oidcProviders:
     - name: my-oidc-provider
       issuer:
         issuerURL: https://idp.example.com
         discoveryURL: https://custom-discovery.example.com/.well-known/openid-configuration
         audiences:
         - my-audience
       claimMappings:
         username:
           claim: email

   where:

   issuerURL

   Specifies the issuer URL displayed in JWT token iss claim.

   discoveryURL

   Specifies the custom OIDC discovery endpoint URL. Must differ from issuerURL, use HTTPS, and must not contain query parameters, fragments, or user info. Maximum length: 2048 characters.

   Note

   Replace the placeholder values (my-oidc-provider, https://idp.example.com, https://custom-discovery.example.com/.well-known/openid-configuration, my-audience) with your actual OIDC provider configuration.

2. Apply the configuration:

   $ oc apply -f authentication-discovery-url.yaml

Procedure

1. Create a YAML file named authentication-cel-mapping.yaml with your CEL expression configuration:

   Important

   When using expression, do not set the claim field. You must use either claim or expression, but not both. Setting both will result in a validation error. Additionally, when using expression, do not set prefixPolicy to Prefix. Prefix policies are only compatible with claim-based mappings.

   Note

   When using the email claim in CEL expressions, you must also validate email_verified to ensure the email address has been verified by the identity provider.

   apiVersion: config.openshift.io/v1
   kind: Authentication
   metadata:
     name: cluster
   spec:
     type: OIDC
     oidcProviders:
     - name: my-oidc-provider
       issuer:
         issuerURL: https://idp.example.com
         audiences:
         - my-audience
       claimMappings:
         username:
           expression: 'claims.?upn.orValue(claims.?oid.orValue(claims.sub))'
         groups:
           expression: 'claims.?groups.orValue([])'
   # ...

   where:

   username.expression

   Specifies the fallback logic for username: upn if present, else oid, else sub.

   groups.expression

   Specifies that the groups claim is used if present, else an empty array.

   Note

   Replace the placeholder values (my-oidc-provider, https://idp.example.com, my-audience) with your actual OIDC provider configuration.

2. Apply the configuration:

   $ oc apply -f authentication-cel-mapping.yaml

Procedure

1. Create a YAML file named authentication-claim-validation.yaml with your claim validation rules:

   apiVersion: config.openshift.io/v1
   kind: Authentication
   metadata:
     name: cluster
   spec:
     type: OIDC
     oidcProviders:
     - name: my-oidc-provider
       issuer:
         issuerURL: https://idp.example.com
         audiences:
         - my-audience
       claimMappings:
         username:
           claim: email
       claimValidationRules:
       - type: CEL
         cel:
           expression: 'claims.exp - claims.nbf <= 86400'
           message: 'Total token lifetime must not exceed 24 hours'
       - type: CEL
         cel:
           expression: 'has(claims.email) && claims.email_verified && claims.email.contains("@example.com")'
           message: 'Email claim must be verified and from example.com domain'

   where:

   claimValidationRules

   Specifies an array of validation rules. All must pass for authentication.

   type

   Specifies the validation type. Set to CEL for CEL-based validation.

   cel.expression

   Specifies the CEL expression that must evaluate to true.

   cel.message

   Specifies the error message displayed when validation fails.

   Note

   Replace the placeholder values (my-oidc-provider, https://idp.example.com, my-audience, @example.com) with your actual OIDC provider configuration and validation requirements.

2. Apply the configuration:

   $ oc apply -f authentication-claim-validation.yaml

Procedure

1. Create a YAML file named authentication-user-validation.yaml with your user validation rules:

   apiVersion: config.openshift.io/v1
   kind: Authentication
   metadata:
     name: cluster
   spec:
     type: OIDC
     oidcProviders:
     - name: my-oidc-provider
       issuer:
         issuerURL: https://idp.example.com
         audiences:
         - my-audience
       claimMappings:
         username:
           claim: email
         groups:
           claim: groups
       userValidationRules:
       - expression: "!user.username.startsWith('system:')"
         message: 'Username cannot use reserved system: prefix'
       - expression: "!user.groups.exists(g, g.startsWith('system:'))"
         message: 'Groups cannot use reserved system: prefix'

   where:

   userValidationRules

   Specifies an array of validation rules. All must pass for authentication.

   expression

   Specifies the CEL expression that must evaluate to true.

   message

   Specifies the error message displayed when validation fails.

   Note

   Replace the placeholder values (my-oidc-provider, https://idp.example.com, my-audience) with your actual OIDC provider configuration.

2. Apply the configuration:

   $ oc apply -f authentication-user-validation.yaml

1. Use your certificate-based kubeconfig to authenticate as cluster-admin.

2. Edit the Authentication custom resource to remove or fix invalid rules:

   $ oc edit authentication.config.openshift.io/cluster

3. Monitor the cluster authentication Operator to confirm it returns to Available status:

   $ oc get clusteroperator authentication