LAB 02: Keycloak Realm Design
and OIDC Clients

Step 1.1: Run the Keycloak container

Launch Keycloak 26 in development mode on the Lab 01 network, with a bootstrap administrator and persistent storage.

Keycloak is a Java application that, in production, runs behind TLS with an external database. Development mode (start-dev) relaxes those requirements so you can learn the identity concepts without a database build; Section 9 lists exactly what changes for production. Joining ib-lab-net matters because Keycloak will later reach the directory at the hostname ib-openldap. Choose a third password now for the Keycloak administrator, referred to below as <KC_ADMIN_PASSWORD>, distinct from your Lab 01 values.

# Deploy Keycloak 26 in development mode.
# Purpose: provides the Identity Provider for the whole track.
# Enterprise context: the open source engine behind Red Hat Build of Keycloak,
# used as the workforce and customer IdP in banking and government.
#
# SECURITY NOTE: start-dev disables TLS and strict hostname checking.
# Acceptable only because this listens on localhost in a lab.

docker run -d \
  --name ib-keycloak \
  --network ib-lab-net \
  -p 8081:8080 \
  -e KC_BOOTSTRAP_ADMIN_USERNAME="admin" \
  -e KC_BOOTSTRAP_ADMIN_PASSWORD="<KC_ADMIN_PASSWORD>" \
  -v ib-keycloak-data:/opt/keycloak/data \
  quay.io/keycloak/keycloak:26.0 \
  start-dev

Docker prints a container ID. First start takes 30 to 60 seconds while Keycloak builds and boots.

Step 2.1: Log in to the admin console and create the realm

Create an isolated realm named northgate for all Northgate users, clients, and policies.

A realm is Keycloak's isolation boundary: each realm has its own users, clients, sessions, signing keys, and login policies, comparable to a tenant in Entra ID or an org in Okta. The built in master realm exists to administer Keycloak itself, and using it for end users is a recognised anti pattern in the Keycloak server administration guide, because a compromise of any application in master is a compromise of the whole platform. Realm design, deciding how many realms and what lives in each, is a genuine architecture decision you will defend in interviews: one realm per identity population (workforce, customers, partners), not one per application.

1. Open http://localhost:8081 and click Administration Console. Log in as admin with <KC_ADMIN_PASSWORD>.
2. In the top left, the realm selector currently shows Keycloak (the master realm). Click it, then click Create realm.
3. Realm name: northgate (lower case, exactly, because it becomes part of every URL). Leave Enabled on. Click Create.
4. Enable auditing while you are here: go to Realm settings, open the Sessions tab and note the default SSO session idle of 30 minutes, then open the User events settings area under Realm settings → Events (called Event configs in some 26.x builds), and switch Save events on for user events. Click Save.

The realm selector now shows northgate, and everything you configure from here on happens inside it.

Step 3.1: Add the LDAP user federation provider

Connect the realm to OpenLDAP so directory accounts can log in through Keycloak, in read only mode, with the directory remaining the source of truth.

Federation here means delegation: Keycloak looks users up in LDAP and validates their passwords by binding to LDAP as them, exactly the four stage sequence you proved by hand in Lab 01 Section 8. We bind with the svc-hrportal service account rather than the directory administrator, applying least privilege: the connection only needs to read user entries, never write them. READ_ONLY edit mode enforces the same principle in the other direction, preventing anyone from modifying directory data through Keycloak.

1. Go to User federation in the left menu, click Add LDAP providers.
2. General options: UI display name northgate-ldap. Vendor: Other.
3. Connection and authentication settings: Connection URL ldap://ib-openldap:389 (the container name resolves because both containers share ib-lab-net). Click Test connection; a green success banner must appear. Bind type simple. Bind DN uid=svc-hrportal,ou=service-accounts,dc=identitybytes,dc=lab. Bind credentials: your <USER_PASSWORD> from Lab 01. Click Test authentication; a second success banner must appear.
4. LDAP searching and updating: Edit mode READ_ONLY. Users DN ou=people,dc=identitybytes,dc=lab. Username LDAP attribute uid. RDN LDAP attribute uid. UUID LDAP attribute entryUUID. User object classes inetOrgPerson.
5. Leave synchronisation settings at defaults for now and click Save.
6. Back on the provider page, open the Action menu in the top right and choose Sync all users.

The sync action reports 3 users imported (the service account sits outside ou=people, so it is correctly excluded from the human population).

Step 3.2: Prove federated login with the account console

Perform the first real end user login through Keycloak, before any client exists, using Keycloak's built in account console as the test application.

The account console is a small self service application that ships inside every realm, which makes it the perfect zero code test target: if a federated user can sign in there, the entire chain of browser, Keycloak, federation provider, and LDAP bind works.

1. Open a private or incognito browser window (so your admin session does not interfere).
2. Go to http://localhost:8081/realms/northgate/account.
3. Sign in as asmith with the Lab 01 <USER_PASSWORD>.

The account console loads and shows personal info populated from LDAP: first name Amina, last name Smith, email amina.smith@identitybytes.lab, with the fields read only because the federation is read only.

Step 3.3: Import LDAP groups with a group mapper

Map finance-team and it-admins from the directory into Keycloak groups, so authorisation data can flow into tokens.

Federation providers use mappers to translate between directory schema and Keycloak's model. The group LDAP mapper reads groupOfNames entries and their DN valued member attributes, the exact structures you built in Lab 01 Step 4.4, and mirrors them as Keycloak groups with correct memberships.

1. Go to User federation → northgate-ldap, open the Mappers tab, click Add mapper.
2. Name northgate-groups. Mapper type group-ldap-mapper.
3. LDAP groups DN ou=groups,dc=identitybytes,dc=lab. Group name LDAP attribute cn. Group object classes groupOfNames. Membership LDAP attribute member. Membership attribute type DN. Mode READ_ONLY. Leave the remaining fields at defaults and click Save.
4. From the mapper's Action menu, choose Sync LDAP groups to Keycloak.

The sync reports 2 groups imported.

Step 4.1: Create the confidential client

Register hr-portal as a confidential OIDC client: the named, authenticated party permitted to send users to Keycloak and redeem tokens.

An OIDC client is an application's registration record at the IdP. Confidential means the application runs server side and can hold a secret, so Keycloak will refuse token requests that do not present it; the alternative, a public client, is for browser and mobile apps that cannot keep secrets and rely on PKCE instead, which IB-SIA-04 covers in depth. The redirect URI list is a security control, not a convenience: Keycloak will only ever send authorisation codes to exact matches, which is what prevents an attacker redirecting your users' codes to a hostile site.

1. Go to Clients, click Create client.
2. Client type OpenID Connect. Client ID hr-portal. Name Northgate HR Portal. Click Next.
3. Capability config: switch Client authentication ON (this is what makes it confidential). Under Authentication flow, keep Standard flow ticked, and additionally tick Direct access grants for this lab only, so we can demonstrate tokens from curl without building an application; the security analysis explains why this stays off in production. Click Next.
4. Login settings: Root URL http://localhost:9090. Valid redirect URIs http://localhost:9090/*. Web origins http://localhost:9090. Click Save.
5. Open the client's Credentials tab and copy the Client secret. This value is <CLIENT_SECRET> in every command below.

The client appears in the list with a Credentials tab present, confirming it is confidential.

Step 4.2: Add a groups claim with a protocol mapper

Shape the token so it carries the user's group memberships, turning the token into a complete authentication and authorisation statement.

By default, Keycloak keeps tokens minimal and does not include groups. Protocol mappers are the claims engineering layer: per client rules that add, rename, or transform claims. Deciding what goes into a token is a real architectural judgement, balancing application needs against token size and data minimisation under UK GDPR, and this mapper is your first deliberate decision of that kind.

1. Go to Clients → hr-portal, open the Client scopes tab, and click the scope named hr-portal-dedicated.
2. Click Configure a new mapper (or Add mapper, By configuration), and choose Group Membership.
3. Name groups. Token claim name groups. Switch Full group path OFF, so the claim reads finance-team rather than /finance-team. Keep Add to ID token, Add to access token, and Add to userinfo ON. Click Save.

The dedicated scope lists a mapper named groups. Proof arrives in the next step, inside a real token.

Step 5.1: Request tokens from the command line

Act as the HR portal: authenticate as the client, present Amina's credentials through the direct access grant, and receive her tokens.

The direct access grant (the OAuth resource owner password flow) lets a client exchange a username and password for tokens in one call. It is deprecated for real applications, because it puts the password back in the client's hands, defeating the pattern; we enable it in the lab purely because it makes token mechanics visible in a single curl command. IB-SIA-04 replaces it with the browser based authorisation code flow plus PKCE, the production standard.

# Ask the northgate token endpoint for tokens.
# The client authenticates with its ID and secret; the user authenticates
# with username and password; scope openid requests an ID token too.

curl -s -X POST http://localhost:8081/realms/northgate/protocol/openid-connect/token \
  -d grant_type=password \
  -d client_id=hr-portal \
  -d client_secret="<CLIENT_SECRET>" \
  -d username=asmith \
  -d password="<USER_PASSWORD>" \
  -d scope=openid | jq . | tee /tmp/tokens.json

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6...",
  "expires_in": 300,
  "refresh_expires_in": 1800,
  "refresh_token": "eyJhbGciOiJIUzUxMiIsInR5cCIgOiAiSldUIiwia2lkIiA6...",
  "token_type": "Bearer",
  "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6...",
  "scope": "openid profile email"
}

Step 5.2: Decode the JWT and read its claims

Open the access token and read the identity and authorisation statements inside, the core diagnostic skill of SSO operations.

A JWT is three base64url encoded parts joined by dots: a header naming the signature algorithm and key ID, a payload of claims, and the signature. Decoding is not decrypting; anyone holding a JWT can read it, which is why tokens must never carry secrets and why possession of a token is treated as sensitive. Trust comes from the signature, which only the realm's private key can produce.

# Extract the access token, take its middle segment, base64url decode it,
# and parse as JSON. jq's @base64d handles the decoding.

jq -r '.access_token | split(".")[1] | @base64d | fromjson' /tmp/tokens.json

{
  "exp": 1751791234,
  "iat": 1751790934,
  "iss": "http://localhost:8081/realms/northgate",
  "aud": "account",
  "sub": "f:2f9a...:asmith",
  "typ": "Bearer",
  "azp": "hr-portal",
  "preferred_username": "asmith",
  "email": "amina.smith@identitybytes.lab",
  "name": "Amina Smith",
  "groups": [
    "finance-team"
  ],
  ...
}

Step 5.3: Verify the signature chain via JWKS

Confirm the token's signing key ID matches a public key the realm publishes, which is how applications verify tokens without contacting Keycloak per request.

# The token header names the key that signed it
jq -r '.access_token | split(".")[0] | @base64d | fromjson | .kid' /tmp/tokens.json

# The realm publishes its public keys at the JWKS endpoint from discovery
curl -s http://localhost:8081/realms/northgate/protocol/openid-connect/certs \
  | jq -r '.keys[] | select(.alg=="RS256") | .kid'

The two commands print the same key ID string.