Red Hat OpenShift Container Platform

Configuring user validation rules

You can define validation rules to enforce security policies on the user object created from an authenticated token. This helps prevent privilege escalation by blocking reserved usernames and group prefixes.

User validation rules are evaluated after claim mapping is complete, including all prefix transformations. Your CEL expressions must validate the final username and group names as they will appear in RBAC policies, not the raw claim values from the JWT token.

All user validation rules must pass for authentication to succeed. Incorrectly configured validation rules can lock all users out of the cluster. Ensure you:

Have a backup authentication method, such as a certificate-based kubeconfig file, before applying these rules
Test validation rules in a non-production environment first
Verify your CEL expressions correctly validate the final username and groups to avoid blocking valid users or allowing unauthorized access

Prerequisites

You have configured an external OIDC identity provider for direct authentication.
You have access to the cluster as a user with the cluster-admin role.
You have access to a long-lived authentication method, such as a certificate-based kubeconfig file.
You are familiar with CEL expression syntax.

Procedure

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.

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

Apply the configuration:

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

Verification

Verify that the authentication configuration is applied successfully:
```
$ oc get authentication.config.openshift.io/cluster -o yaml
```
Authenticate with credentials that would create a user matching your validation rules to confirm they are enforced correctly.

Check the cluster authentication Operator logs for validation errors:

$ oc logs -n openshift-authentication-operator deployments/authentication-operator

When writing CEL expressions for user validation:

Access user fields: user.username, user.groups (array), user.uid, user.extra (map)
Expressions must evaluate to boolean values
Use startsWith(), endsWith(), contains() for string matching
Use exists() for array checks (for example, user.groups.exists(g, g == "admin"))

Common use cases include:

Prevent reserved username prefixes

userValidationRules:
- expression: "!user.username.startsWith('system:')"
  message: 'Username cannot use reserved system: prefix'

Prevent reserved group prefixes

userValidationRules:
- expression: "!user.groups.exists(g, g.startsWith('system:'))"
  message: 'Groups cannot use reserved system: prefix'

Require username format

userValidationRules:
- expression: "user.username.matches('^[a-z0-9]([-a-z0-9]*[a-z0-9])?$')"
  message: 'Username must be a valid DNS subdomain'

Validate group membership

userValidationRules:
- expression: "user.groups.exists(g, g == 'verified-users')"
  message: 'User must be a member of verified-users group'

Combine conditions

userValidationRules:
- expression: "!user.username.startsWith('system:') && !user.username.startsWith('kube:')"
  message: 'Username cannot use reserved system: or kube: prefixes'

Troubleshooting

If you incorrectly configure validation rules and lock users out of the cluster:

Use your certificate-based kubeconfig to authenticate as cluster-admin.
Edit the Authentication custom resource to remove or fix invalid rules:
```
$ oc edit authentication.config.openshift.io/cluster
```
Monitor the cluster authentication Operator to confirm it returns to Available status:
```
$ oc get clusteroperator authentication
```