Skip to content

Identity domains

You want your own users, in your own namespace of identity, signing in to your own applications. On AWS that is a Cognito user pool. Here it is a domain, and underneath it is a Keycloak realm.

Everything else in this section hangs off one. Users belong to a domain, groups belong to a domain, and applications authenticate against a domain.

Prerequisites

  • A project with an identity server - oc get keycloaks.v1.edp.epam.com -n <project> returns one

If it returns nothing, run Set up IAM for the project first. It provisions the server and the connection the domain needs, and takes a few minutes.

The step-by-step guide and the console walkthrough cover the operations. The rest of this page explains how it fits together.

How it fits together

flowchart TB
    subgraph P["your project"]
        direction TB
        KC["Keycloak server<br/>created by Set up IAM"]
        RE["KeycloakRealm<br/>your domain"]
        U["KeycloakRealmUser"]
        G["KeycloakRealmGroup"]
        C["KeycloakClient"]
        KC --- RE
        RE --> U
        RE --> G
        RE --> C
    end
    APP["your application"] -->|authenticates via| C
    U -->|member of| G

Identity here is per tenant: each project gets its own Keycloak server, not a slice of a shared one. The domain is a realm on that server.

Realms are fully separate from one another. A user in one cannot sign in to an application in another, even with the same username. Create one domain per organisation whose identities should not mix. Most projects need exactly one.

Two names for the same thing

A domain is written the way you would write it - example.com - but Kubernetes object names cannot contain dots.

Field Value Why
spec.realmName example.com the domain, as users see it
metadata.name example-com dots become hyphens for the object name

The console does the conversion for you. Writing the manifest by hand, you do it yourself.

A domain longer than 63 characters is rejected

The converted name still has to fit a 63-character DNS label, so a very long domain fails on the Kubernetes name before Keycloak's own rules are reached.

A domain cannot be renamed

The domain appears in sign-in pages and in tokens. Use the real one - a placeholder is awkward to live with, and there is no rename.

What deleting takes with it

Deleting a domain deletes every identity in it

Users, groups and clients all belong to the realm. 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 those too, or a later domain with the same name picks up unexpected members.