Identity domains¶

A domain is where your identities live. Everything else in this section hangs off one: users belong to a domain, groups belong to a domain, and applications authenticate against a domain.

Underneath, a domain is a Keycloak realm. Realms are fully separate - a user in one cannot sign in to an application in another, even with the same username. That separation is the point.

Create one domain per organisation whose identities should not mix. Most projects need exactly one.

For the same steps in the console, see the console walkthrough.

Prerequisites¶

The project needs an identity server. Check:

oc get keycloaks.v1.edp.epam.com -n <project>

If that returns nothing, run Set up IAM for the project from the console first. It provisions the server and the connection the domain objects need, and takes a few minutes.

Create¶

domain.yaml

apiVersion: v1.edp.epam.com/v1
kind: KeycloakRealm
metadata:
  name: <domain-with-hyphens>
  namespace: <project>
spec:
  realmName: <domain>
  keycloakRef:
    kind: Keycloak
    name: keycloak

keycloakRef points at the identity server in the same project. Set up IAM names that server keycloak, so this reference is the same in every project.

oc apply -f domain.yaml

The object name and the realm name are not the same string

spec.realmName is the domain as you would write it - example.com. metadata.name has to be a DNS-1123 label, which cannot contain dots, so the dots become hyphens: example-com.

The whole name must still fit in 63 characters after that substitution, so a very long domain is rejected on the Kubernetes name alone, before Keycloak's own rules are reached.

Use the real domain your users belong to. It appears in sign-in pages and in tokens, and it cannot be renamed afterwards.

List¶

oc get keycloakrealms.v1.edp.epam.com -n <project>

The status column reports OK once the realm exists on the server. Anything else names what went wrong:

oc get keycloakrealms.v1.edp.epam.com <name> -n <project> \
  -o jsonpath='{.status}{"\n"}'

A message about a Keycloak not being found means the identity server is not ready - most often because Set up IAM has not finished.

Change¶

The realm name is fixed. A domain that reports an error because the server was not ready has to be deleted and recreated once it is; editing it does not retry the creation.

Settings inside the realm - password policies, session lifetimes, login themes - are managed in Keycloak itself rather than through this object.

Delete¶

oc delete keycloakrealms.v1.edp.epam.com <name> -n <project>

This deletes every identity in the domain

Users, groups and clients all belong to the realm. Deleting it removes them, and anything authenticating against it stops working immediately.

The user, group and client objects in your project are left behind as orphans pointing at a realm that no longer exists. Delete them too, or a later domain with the same name will pick up unexpected members.

Security & identity - what the identity offering covers
Users - people who can sign in
Groups - what permissions are actually granted to
Clients - applications that authenticate against a domain