OpenShift User Management API Guide

Auth method: Bearer token (OpenShift OAuth token or service account token); cluster also supports OAuth 2.0 via configured identity providers

Setup steps

1. Obtain an OAuth access token via oc login or POST to https:///oauth/authorize with configured identity provider credentials.
2. Alternatively, create a ServiceAccount and extract its token secret: oc create serviceaccount <name> -n <namespace> then oc get secret <sa-token-secret> -o jsonpath='{.data.token}' | base64 -d.
3. Grant the service account appropriate ClusterRole (e.g., cluster-admin or a custom role with user/group RBAC verbs) via ClusterRoleBinding.
4. Pass the token in the Authorization header: Authorization: Bearer <token>.
5. For external IdP (OIDC/SAML), configure the OAuth server CR at cluster.config.openshift.io/v1 with the identityProviders field.

Required scopes

List all users

• Method: GET
• URL: https://<cluster-api>/apis/user.openshift.io/v1/users
• Watch out for: Uses Kubernetes list pagination (limit + continue token), not offset. Iterate using the continue field until it is empty.

Request example

GET /apis/user.openshift.io/v1/users?limit=50 HTTP/1.1
Authorization: Bearer <token>
Accept: application/json

Response example

{
  "kind": "UserList",
  "apiVersion": "user.openshift.io/v1",
  "metadata": {"continue": "<token>"},
  "items": [{"metadata":{"name":"jdoe"},"fullName":"Jane Doe"}]
}

Get a specific user

• Method: GET
• URL: https://<cluster-api>/apis/user.openshift.io/v1/users/{name}
• Watch out for: Use name ~ to retrieve the currently authenticated user: GET /apis/user.openshift.io/v1/users/~

Request example

GET /apis/user.openshift.io/v1/users/jdoe HTTP/1.1
Authorization: Bearer <token>

Response example

{
  "kind": "User",
  "apiVersion": "user.openshift.io/v1",
  "metadata": {"name": "jdoe", "uid": "abc-123"},
  "fullName": "Jane Doe",
  "identities": ["ldap:uid=jdoe,ou=users,dc=example,dc=com"]
}

Delete a user

• Method: DELETE
• URL: https://<cluster-api>/apis/user.openshift.io/v1/users/{name}
• Watch out for: Deleting a User object does NOT delete the associated Identity object or revoke active OAuth tokens. You must also DELETE /apis/user.openshift.io/v1/identities/ and revoke OAuthAccessTokens separately.

Request example

DELETE /apis/user.openshift.io/v1/users/jdoe HTTP/1.1
Authorization: Bearer <token>

Response example

{
  "kind": "Status",
  "status": "Success",
  "code": 200
}

Update user (patch fullName or labels)

• Method: PATCH
• URL: https://<cluster-api>/apis/user.openshift.io/v1/users/{name}
• Watch out for: Supports strategic-merge-patch, merge-patch+json, and json-patch. The groups field is read-only on the User object; patch it via the Group resource.

Request example

PATCH /apis/user.openshift.io/v1/users/jdoe HTTP/1.1
Content-Type: application/merge-patch+json
Authorization: Bearer <token>

{"fullName": "Jane A. Doe"}

Response example

{
  "kind": "User",
  "metadata": {"name": "jdoe"},
  "fullName": "Jane A. Doe"
}

List all groups

• Method: GET
• URL: https://<cluster-api>/apis/user.openshift.io/v1/groups
• Watch out for: Group membership is stored in the users[] array on the Group object, not on the User object.

Request example

GET /apis/user.openshift.io/v1/groups?limit=50 HTTP/1.1
Authorization: Bearer <token>

Response example

{
  "kind": "GroupList",
  "items": [{"metadata":{"name":"dev-team"},"users":["jdoe","bsmith"]}]
}

Create or update a group (add members)

• Method: PUT
• URL: https://<cluster-api>/apis/user.openshift.io/v1/groups/{name}
• Watch out for: PUT replaces the entire users[] array. Use PATCH with json-patch to add/remove individual members atomically.

Request example

PUT /apis/user.openshift.io/v1/groups/dev-team HTTP/1.1
Content-Type: application/json
Authorization: Bearer <token>

{"apiVersion":"user.openshift.io/v1","kind":"Group","metadata":{"name":"dev-team"},"users":["jdoe","bsmith","anew"]}

Response example

{
  "kind": "Group",
  "metadata": {"name": "dev-team"},
  "users": ["jdoe", "bsmith", "anew"]
}

List identities

• Method: GET
• URL: https://<cluster-api>/apis/user.openshift.io/v1/identities
• Watch out for: Identity objects are auto-created on first login. Manually creating them without a matching User object will cause login failures.

Request example

GET /apis/user.openshift.io/v1/identities HTTP/1.1
Authorization: Bearer <token>

Response example

{
  "kind": "IdentityList",
  "items": [{"metadata":{"name":"ldap:uid=jdoe"},"user":{"name":"jdoe"},"providerName":"ldap"}]
}

Delete an OAuth access token (revoke session)

• Method: DELETE
• URL: https://<cluster-api>/apis/oauth.openshift.io/v1/oauthaccesstokens/{token-name}
• Watch out for: Token names are SHA256-hashed. List tokens for a user by filtering: GET /apis/oauth.openshift.io/v1/oauthaccesstokens?fieldSelector=userName=jdoe

Request example

DELETE /apis/oauth.openshift.io/v1/oauthaccesstokens/<sha256~...> HTTP/1.1
Authorization: Bearer <admin-token>

Response example

{
  "kind": "Status",
  "status": "Success"
}

• Rate limits: OpenShift does not publish fixed global API rate limits. Rate limiting is enforced by the Kubernetes API server's built-in flow control (APF - API Priority and Fairness) introduced in Kubernetes 1.20+, which OpenShift 4.x uses. Limits are configurable per cluster by administrators via FlowSchema and PriorityLevelConfiguration objects.
• Rate-limit headers: No
• Retry-After header: Yes
• Rate-limit notes: When throttled, the API server returns HTTP 429 with a Retry-After header. Administrators can tune APF FlowSchemas. Default kube-apiserver max-requests-inflight is 400 and max-mutating-requests-inflight is 200 but these are cluster-configurable.
• Pagination method: token
• Default page size: 0
• Max page size: 0
• Pagination pointer: limit / continue

• Webhooks available: No
• Webhook notes: OpenShift does not provide native outbound webhooks for user lifecycle events (create/delete/update). The Kubernetes API server supports Admission Webhooks (ValidatingWebhookConfiguration, MutatingWebhookConfiguration) which can intercept API calls to user/group resources, but these are inbound validation hooks, not outbound event notifications.
• Alternative event strategy: Use Kubernetes watch API (GET /apis/user.openshift.io/v1/users?watch=true) for real-time change streams, or configure audit logging to an external SIEM. For IdP-driven provisioning events, use LDAP sync jobs (oc adm groups sync) on a schedule.

• SCIM available: No
• SCIM version: Not documented
• Plan required: N/A - not available on any plan
• Endpoint: Not documented

Limitations:

• OpenShift has no native SCIM 2.0 endpoint.
• User provisioning is handled via identity provider login (just-in-time), LDAP group sync (oc adm groups sync), or direct REST API calls.
• Red Hat SSO (Keycloak) can be deployed alongside OpenShift and does support SCIM via third-party extensions, but this is not part of OpenShift itself.
• ROSA and ARO managed services also lack native SCIM; they rely on OIDC/SAML IdP integration.

Full user deprovisioning requires three sequential API calls minimum: DELETE all OAuthAccessTokens for the user (filtered via fieldSelector=userName=<username>), DELETE the User object at `/apis/user. openshift.

io/v1/users/, and DELETE the Identity object at /apis/user. openshift.

io/v1/identities/:`. Skipping the Identity deletion leaves a dangling record; the same IDP account will re-create the User object on next login with no error surfaced.

Group membership is managed exclusively on the Group object's users[] array - the groups[] field on the User object is read-only and computed. Use PATCH with application/json-patch+json to add or remove individual members atomically; a PUT replaces the entire users[] array and risks race conditions in concurrent environments.

For service account automation, OCP 4.11+ no longer auto-creates long-lived token secrets. Use oc create token (TokenRequest API) for bounded tokens, or explicitly create a kubernetes.io/service-account-token Secret for a persistent credential. Bind a least-privilege ClusterRole scoped to users, groups, and identities resources rather than using cluster-admin in production.

Deprovision a user completely

1. List and delete all OAuthAccessTokens for the user: GET /apis/oauth.openshift.io/v1/oauthaccesstokens?fieldSelector=userName=, then DELETE each token.
2. Delete the User object: DELETE /apis/user.openshift.io/v1/users/.
3. Find and delete the Identity object: GET /apis/user.openshift.io/v1/identities, filter by user.name=, then DELETE /apis/user.openshift.io/v1/identities/.
4. Remove the user from all Group objects: PATCH each Group's users[] array to exclude the username.
5. Remove any ClusterRoleBindings or RoleBindings referencing the user: oc get clusterrolebindings -o json | grep , then delete relevant bindings.

Watch out for: Skipping step 3 leaves a dangling Identity; if the same IdP account logs in again, OpenShift will re-create the User object automatically.

Bulk sync LDAP groups to OpenShift groups

1. Create an LDAP sync config file (ldap-sync.yaml) specifying url, bindDN, bindPassword, and groupUIDNameMapping.
2. Dry-run to preview: oc adm groups sync --sync-config=ldap-sync.yaml.
3. Apply the sync: oc adm groups sync --sync-config=ldap-sync.yaml --confirm.
4. Verify groups created/updated: oc get groups.
5. Schedule as a CronJob or external cron to keep groups in sync continuously.

Watch out for: LDAP sync creates Group objects and populates users[] but does NOT create User objects. Users are only created in OpenShift upon their first login via the LDAP identity provider.

Grant a service account permission to manage users via API

1. Create a service account: oc create serviceaccount user-manager -n openshift-config.
2. Create a ClusterRole with required verbs: oc create clusterrole user-manager-role --verb=get,list,watch,create,update,patch,delete --resource=users,groups,identities.
3. Bind the role: oc create clusterrolebinding user-manager-binding --clusterrole=user-manager-role --serviceaccount=openshift-config:user-manager.
4. Extract the service account token: oc create token user-manager -n openshift-config --duration=8760h (OCP 4.11+ uses TokenRequest API).
5. Use the token in API calls: Authorization: Bearer <token>.

Watch out for: On OCP 4.11+, long-lived service account token secrets are no longer auto-created. Use oc create token (TokenRequest) for bounded tokens or explicitly create a Secret of type kubernetes.io/service-account-token for a persistent token.

The most common integration failure is treating the User object as the authoritative identity record. It is not. The identity graph in OpenShift spans User objects, Identity objects, OAuthAccessTokens, Group memberships, ClusterRoleBindings, and RoleBindings - all stored as separate Kubernetes resources with no single API call to retrieve the full picture for a given principal.

Any automation that only operates on /users will produce an incomplete and potentially misleading view of who has access to what.

A second trap is the just-in-time provisioning model. LDAP group sync populates Group objects and their users[] arrays, but User objects are not created until the user authenticates.

An identity graph built from /users alone will be missing every user who has been synced into a group but has not yet logged in - a silent gap that affects access audits.

Webhooks for user lifecycle events do not exist natively. The Kubernetes watch API (GET /apis/user.openshift.io/v1/users?watch=true) provides a real-time change stream, but it requires a persistent connection and client-side reconnect logic. For event-driven provisioning pipelines, this is the only supported mechanism short of polling or external audit log ingestion.