The previous two lessons have left Kilometre Zero with RS256 tokens that every service verifies and with encrypted channels for them to travel over. But they have treated as solved something that is not: where identities come from. services/identity/tokens.py signs with a key whose .pub was copied by hand to each service; login is a home-grown form with Argon2; Kilometre Zero's employees have corporate accounts in another system; producers would rather sign in with their Google account; the courier app should never display a long-lived password; and orders needs a machine token to call inventory when it acts on its own (a compensating saga from 03-05, for example) with no user behind it. Solving each case in each service is unworkable and, worse, insecure: every home-made login implementation is an opportunity for error.

This lesson centralises identity in an identity provider (IdP) and explains the protocols that let an identity established there be valid across the whole platform: LDAP as the employee directory, SAML 2.0 for enterprise single sign-on, and OAuth 2.0 with OpenID Connect for web, mobile and machine-to-machine applications. We will look at federation with social identities, the lifecycle of an identity (joining, role changes, leaving), multi-factor authentication and account recovery. And we will get it running: Keycloak as the IdP in docker-compose.yml with a km0 realm, three clients, roles and per-producer groups, and OpenLDAP for the employees; an OIDC client in Python with PKCE, obtaining a machine token for orders, and an LDAP search. Certificate-based service identity (mTLS) and the custody of secrets are 06-04; the edge that validates all of this centrally, 06-05.

1. Why centralise identity
2. Identity provider versus applications
3. LDAP directories: DIT, dn, ou, searches and bind
4. SAML 2.0: enterprise single sign-on
5. OAuth 2.0: delegating access
6. OpenID Connect: identity on top of OAuth 2.0
7. LDAP, SAML and OAuth2/OIDC compared
8. Federation and social identities
9. Lifecycle, MFA and recovery
10. Kilometre Zero: Keycloak as the IdP and OpenLDAP for employees
11. Code: OIDC client with PKCE, client credentials and LDAP search
12. Common Mistakes and Tips
13. Exercises
14. Conclusion

Kilometre Zero has four populations with different needs:

If every service manages its own users, the familiar problems appear: different passwords everywhere (and reused), an employee who leaves the company still has access to analytics because nobody removed them there, MFA on the web but not on the operator dashboard, and four password recovery implementations with four sets of bugs. Centralisation solves this: one source of truth for who exists and what attributes they have, one place to apply MFA and password policies, one deactivation that closes every door, and applications that stop handling credentials.

The identity provider (IdP) is the system that authenticates subjects and issues proofs of identity (SAML assertions, OIDC tokens) that applications consume. Applications become relying parties (or service providers in SAML): they never see the password, only the signed proof.

Keycloak, the IdP we will use, covers the whole picture: its own user base, federation with LDAP and with social providers, issuing OIDC tokens and SAML assertions, MFA, and an administration console. Alternatives playing the same role: Auth0/Okta, Azure AD (Entra ID), AWS Cognito, Ory, Authentik. The protocols are standard; changing IdP should not change the applications' code.

LDAP (Lightweight Directory Access Protocol) is the protocol for querying directories: hierarchical databases optimised for reads, which store people, groups, machines and their attributes. Microsoft's Active Directory is the most widespread implementation in companies (with Kerberos for authentication on Windows); OpenLDAP and 389 Directory Server are the open-source ones. In Kilometre Zero the directory holds the employees, which is what any company tends to have already before the platform exists.

The directory is a tree, the DIT (Directory Information Tree). Each entry has a unique DN (distinguished name), which is the path from the root:

Concepts:

• Entry and attributes: each node has attributes with types defined by object classes (inetOrgPerson brings cn, sn, mail, uid; groupOfNames brings member). The schema is strict: you cannot invent an attribute without declaring it.
• dn, ou, cn, uid, dc: distinguished name, organizational unit, common name, user id, domain component. The dn is the primary key; the rest are attributes with conventions.
• Search: you give a base (ou=people,dc=km0,dc=internal), a scope (base, one, subtree) and a filter in prefix syntax: (&(objectClass=inetOrgPerson)(memberOf=cn=operators,ou=groups,dc=km0,dc=internal)) returns the operators; (|(mail=j*)(uid=j*)) those beginning with j.
• Bind: LDAP authentication. A simple bind sends a dn and a password; the server checks them against the stored hash (SSHA or, better, Argon2 in modern OpenLDAP). Authenticating a user "against LDAP" means: (1) with the technical account, search for the dn whose uid or mail matches; (2) attempt a bind with that dn and the password the user typed. If the bind succeeds, the password is correct.
• LDAPS / StartTLS: plain LDAP sends passwords in the clear; always use TLS (port 636) or StartTLS over 389.

LDAP is not an SSO protocol: every application that authenticates against LDAP sees the user's password. That is why LDAP's role in a modern platform is to be the source of users and groups the IdP queries, not something applications touch directly. Only the IdP binds.

SAML (Security Assertion Markup Language, 2005) is the classic protocol for SSO between companies: an employee logs in once at the corporate IdP and accesses dozens of third-party applications (email, payroll, CRM) without authenticating again. It is signed XML, carried by browser redirects.

Actors and pieces:

• IdP: authenticates and issues assertions: signed XML documents stating "the subject [email protected] authenticated at 10:02 with password and MFA, and has these attributes (groups, department)".
• SP (service provider): the application, which trusts the IdP because it has its signing certificate, and which consumes the assertion.
• Metadata: each party publishes an XML document with its URLs and certificates; they are exchanged once when setting up the trust.
• Bindings: how the message travels: HTTP-Redirect (in the URL), HTTP-POST (auto-submitted form). Everything goes through the browser; IdP and SP do not talk to each other directly.

The SP-initiated flow (the user starts at the application):

The IdP-initiated flow starts at an IdP portal with application icons; it is less secure (there is no InResponseTo tying the response to a request) and is discouraged unless necessary. SAML remains mandatory when a corporate customer's IdP only speaks SAML; for new applications, OIDC is simpler and better suited to APIs and mobile. Keycloak speaks both, so Kilometre Zero's operator dashboard could use SAML if it is integrated with an external corporate IdP tomorrow, and OIDC today.

OAuth 2.0 (RFC 6749, 2012) was born for a problem other than authentication: delegating access. Anna wants a third-party app to read her Kilometre Zero orders without giving it her password. OAuth defines how that app obtains a limited access token (restricted to certain scopes, for a certain time) with Anna's consent. Its later use as the basis for authentication is the work of OpenID Connect (section 6).

Roles:

Scopes are strings that bound the permission: orders:read, orders:create, delivery:position. The token carries the granted scopes and the resource server checks them. The client types: confidential (can keep a secret: a backend service) and public (cannot: an SPA in the browser, a mobile app; any embedded secret can be extracted).

The reason for PKCE deserves a pause. On a mobile phone, the IdP returns the code to the app through a custom URL (km0://callback?code=...), and another, malicious app could register the same scheme and capture it. With PKCE, the code is only of use together with the original code_verifier, which never left the legitimate app. In an SPA, it protects in the same way against a code stolen by a script or through a proxy's logs.

OpenID Connect (OIDC, 2014) adds to OAuth 2.0 what it lacked in order to authenticate: an ID token (a JWT, exactly those from 06-01, signed by the IdP) with claims about who the user is and how they authenticated, a userinfo endpoint for fetching more attributes, and automatic discovery of the configuration.

• ID token: claims iss, sub, aud (= client_id), exp, iat, plus auth_time, nonce (anti-replay, generated by the client), amr (methods: pwd, otp), and profile claims (email, name, preferred_username) depending on the scopes openid profile email. It is addressed to the client: it tells it who has logged in.
• Access token: still the OAuth one, addressed to the resource servers (aud: [orders, inventory]). Keycloak also issues it as an RS256 JWT with the realm roles, which is what the AuthInterceptor from 06-01 verifies. You must not use the ID token to call the APIs, nor the access token to find out who is on the web.
• Discovery: GET https://identity.km0/realms/km0/.well-known/openid-configuration returns a JSON document with all the endpoints (authorization_endpoint, token_endpoint, userinfo_endpoint, jwks_uri, end_session_endpoint) and the supported algorithms.
• JWKS (JSON Web Key Set): jwks_uri publishes the IdP's signing public keys, each with its kid. This replaces the hand-copied .pub file from 06-01: services download the keys, cache them, and refresh them when they see an unknown kid. Signing key rotation becomes automatic.

The complete flow with authorization code + PKCE, in Kilometre Zero:

Note that web-km0 is a confidential client (it has a backend and a secret) and uses PKCE even so: it costs nothing and OAuth 2.1 requires it. courier-app is public and uses PKCE alone.

They do not compete: the usual pattern is LDAP behind the IdP, SAML or OIDC in front, and OIDC for anything new.

Federating means accepting identities from another IdP. Keycloak acts as a broker: Montblanc Dairy clicks "Sign in with Google", Keycloak redirects to Google (which is in turn an OIDC IdP), receives Google's ID token, verifies it, and creates or links a local account in the km0 realm with its own sub. Kilometre Zero's applications only ever see Keycloak tokens: they neither know nor care whether the user signed in with a password, with Google or with Apple.

Advantages: fewer passwords to manage, one-click sign-up, MFA delegated to the social provider. Precautions: the unverified email from some providers must not be used to link automatically to an existing account (an attacker registers someone else's email with provider X and inherits the account); Keycloak forces it to be verified. And employee accounts are never federated with social providers: they come from the corporate LDAP, with mandatory MFA.

An identity is not a static record:

• Joining (onboarding): customers self-register (with email verification); producers are approved by an operator (producer role and the producer's group, section 10); employees appear in LDAP from HR and Keycloak synchronises them. SCIM (System for Cross-domain Identity Management) is the REST standard that lets an HR system or an IdP create, modify and delete users in other applications automatically; it is what avoids "someone has to set them up by hand in five places".
• Role changes: Martha moves from customer support to operations: her group changes in LDAP, Keycloak reflects it at the next synchronisation or the next login, and her next token carries the new roles. With 15-minute tokens (06-01), that is the maximum latency.
• Leaving (offboarding): deactivate in LDAP or in Keycloak, revoke sessions and refresh tokens. Live access tokens expire within minutes. This is the reason leavers are handled at the IdP and never application by application.
• Periodic review (access review): list who has operator and confirm it is still true. Permissions only grow if nobody reviews them.
• MFA: mandatory for operators and producers (TOTP with an app, or WebAuthn/passkeys); optional but encouraged for customers. It is configured once at the IdP and applies to everything. Keycloak enforces it per authentication flow and per role.
• Recovery: the most attacked point. A single-use link by email with a short expiry, never security questions, additional verification for accounts with MFA (backup codes), and a record of every recovery in the audit log from 06-05. A weak recovery flow undoes the best MFA.

We add two services to docker-compose.yml. Keycloak needs its own database; OpenLDAP is initialised with an LDIF containing the sample employees:

start-dev and --hostname=http://localhost:8080 are for development: in production, Keycloak sits behind TLS with start and a real hostname. The identity/employees.ldif file creates the tree from section 3:

And the realm, exported to identity/realm-km0.json (Keycloak imports it on start-up). The essentials, in table form because the full JSON runs to hundreds of lines:

With docker compose up -d keycloak openldap, the console at http://localhost:8080 shows the km0 realm, and curl http://localhost:8080/realms/km0/.well-known/openid-configuration returns the discovery document. Jordan and Martha appear as users federated from LDAP, with the operator role inherited from the group; none of their passwords is in Keycloak.

The services/identity/tokens.py from 06-01 is now retired: Keycloak does the issuing. What survives is services/common/auth.py, with a single modification: instead of the .pub file, it uses the JWKS.

The AuthInterceptor in inventory and the requires_role decorator do not change by a single line: Keycloak's tokens carry roles and producer_id thanks to the mappers.

This module is the one used by the web-km0 backend (and, with the differences noted in the comments, the courier app). It is implemented with requests so that every step is visible; authlib wraps it in three calls and is what you would use in production.

Integrated into Flask, /login calls start_login, stores pending in the session and redirects; /callback calls complete_login, stores sub, access_token and refresh_token in the server-side session (Redis, 06-01) and redirects to the page. The browser only has the session's HttpOnly cookie.

A quick check from the terminal, with a user anna created in the realm:

When orders acts on its own (compensating a saga, nightly reconciliation), there is no user token to forward. It requests its own:

The resulting token has sub: service-account-orders-service, roles: [svc-orders], aud: inventory. In inventory's ROLES_BY_METHOD (06-01), svc-orders is added to ReserveStock and ReleaseReservation. It is the platform's first real machine identity; 06-04 will strengthen it with a certificate instead of a client_secret.

Services should not talk to LDAP (Keycloak does that), but an operator does sometimes need to query the directory: for example, an internal script that lists who is in operators for the access review from section 9.

Two security details in the code: the search filter is built from controlled values (group comes from a script argument); if it came from user input it would have to be escaped (ldap3.utils.conv.escape_filter_chars) to prevent LDAP injection, the equivalent of SQL injection. And the technical account is read-only: if someone steals read-only, they can list employees but not modify groups.

• Using the ID token to call the APIs (or the access token to identify the user on the web). The ID token has aud: web-km0 and orders must reject it; the access token may be opaque with other IdPs. Each token for its intended recipient.
• Omitting state or nonce "because there's PKCE already". They protect against different attacks: state against CSRF on the callback (being logged in to the attacker's account), nonce against the reuse of an ID token, PKCE against interception of the code.
• redirect_uri with wildcards. The IdP must accept exact URIs only; a wildcard lets the code end up on a domain the attacker controls.
• Password flow "because it's our own app". It defeats MFA, consent and federation, and gets users used to typing their password into apps. Authorization code + PKCE works for native apps too.
• Client secrets in mobile apps or SPAs. They are public by definition; register them as public with PKCE.
• Applications that bind against LDAP directly. Every one of them sees passwords and none of them applies MFA. LDAP behind the IdP.
• Linking social accounts by unverified email. It is the classic route to account takeover.
• Offboarding application by application. Offboarding means deactivating at the IdP (or in LDAP) and revoking sessions; if you need to touch five systems, the design is wrong (SCIM exists for that).
• Copying the JWKS by hand or pinning a single key. The IdP rotates keys; use jwks_uri with caching and a refresh on an unknown kid.
• Tip: export the Keycloak realm (kc.sh export) and version it in identity/realm-km0.json: identity configuration is code, reviewed and deployed like everything else.
• Tip: test the flow with a real IdP in development (Keycloak in Compose), not with a "no authentication mode". Differences in authentication between environments are the classic source of surprises in production.
• Compliance warning. Identity data (emails, names, employee groups, linked social providers) is personal data; its processing, its retention and the MFA and recovery policy must be reviewed with a security and data protection professional.

A courier has a malicious app installed that registers the km0:// scheme and captures the redirect km0://callback?code=XYZ&state=... before courier-app does. Explain what the malicious app can do with that code (a) if courier-app were a confidential client with the secret embedded in the APK, (b) if it were public without PKCE, (c) with the configuration from section 10. State in each case which Keycloak check fails or does not fail.

Martha Hill (mhill) leaves Kilometre Zero on a Friday at 17:00. Describe what actions HR/IT take, in which system, and what happens to: her open session on the operator dashboard, her refresh token, an access token issued at 16:55, her account on the internal wiki (which uses SAML against Keycloak) and her permissions in analytics. What would have to exist for all of this to be a single action? And what fails if analytics kept its own users table?

km0_daily_sales (05-05) and the Flink consumer of orders.events (05-04) have no user. Design for each: the client in the km0 realm (name, type, flow, scopes/audience), the service roles, how they obtain and renew the token, and what check inventory or the Kafka broker adds. Point out which part of this design 06-04 is going to change and why.

Exercise 1.

(a) The malicious app extracts the secret from the APK (it is trivial), exchanges the code with client_id + client_secret and obtains the courier's tokens: Keycloak cannot tell it apart from the legitimate app; no check fails. (b) Without PKCE, a public client exchanges the code with just client_id and redirect_uri; the malicious app does so before the legitimate one and obtains the tokens; the legitimate one gets an error when trying to exchange an already used code, which is the only signal, and a late one. (c) With mandatory S256 PKCE, the exchange requires the code_verifier whose SHA-256 was sent as the code_challenge in the authorization request; the malicious app has the code but not the verifier (it never left courier-app); Keycloak hashes whatever verifier it sends (or rejects its absence) and responds invalid_grant. The code is rendered useless; the legitimate app, if it is the first to exchange, gets in as normal. state plays no part in this attack (it protects the callback against CSRF, not against interception).

Exercise 2.

IT deactivates uid=mhill in OpenLDAP (or HR does it via SCIM/synchronisation from its own system). Keycloak, in READ_ONLY mode with periodic synchronisation, sees the deactivated account on the next cycle (or immediately if IT also deactivates it in Keycloak and revokes her sessions from the console, which is the recommended course). The operator dashboard session: if the dashboard keeps a server-side session with the access token, it keeps working until the token expires (16:55 + 15 min = 17:10 at the latest) or until it tries to refresh; the refresh token was revoked when her sessions were closed in Keycloak, so the refresh fails and the dashboard throws her out. The wiki with SAML: the next time she needs to re-authenticate (or immediately if the wiki receives a single logout), the IdP will not authenticate her; her local session on the wiki lasts as long as its cookie does, which is why sessions in SAML applications are configured to be short. analytics: if it validates Keycloak tokens, there is nothing to do there. For all of this to be a single action, the deactivation has to be done only at the source (LDAP/HR) and flow through synchronisation or SCIM to the IdP, with automatic revocation of sessions. If analytics kept its own users table with passwords, the deactivation would never arrive: Martha would still be getting into analytics on Monday, which is exactly the point of section 1.

Exercise 3.

Airflow: client airflow-service, confidential, service accounts only (client credentials), scope/audience analytics and hdfs (if the lake is protected with tokens; in practice HDFS uses Kerberos, outside this course), service role svc-analytics-write; the DAG obtains the token in an initial PythonOperator (or a hook that caches it like service_token) and, since the tasks last longer than 15 minutes, renews it via client credentials when it expires (no refresh token: client credentials is simply repeated). Flink: client flink-orders-consumer, confidential, client credentials, audience kafka, role svc-orders-consumer; the Kafka broker is configured with SASL_SSL and the OAUTHBEARER mechanism, which validates the JWT against Keycloak's JWKS and applies ACLs: that principal can only read orders.events with its consumer group, and cannot write to anything. inventory adds svc-analytics-... to the read-only methods if Airflow queries it. What 06-04 changes: the client_secret of both currently lives in the configuration of Airflow and of the Flink job, that is, in a file or environment variable; it will be replaced by client certificate authentication (mTLS) or by a secret injected and rotated by Vault, and the DAG's PostgreSQL credentials will become dynamic.

Centralising identity means there is a single place where it is decided who exists, how they authenticate and what attributes they have, and that applications consume signed proofs instead of passwords. LDAP is the directory: a tree of entries with dn, organizational units, groups and bind, ideal as the source of employees behind the IdP and dreadful as an application login protocol. SAML 2.0 is enterprise SSO through XML assertions, still needed to integrate corporate IdPs. OAuth 2.0 delegates access with scopes and flows, of which only three matter today (authorization code with PKCE, client credentials and refresh), and OpenID Connect adds identity to it: an ID token for the application, an access token for the APIs, discovery for self-configuration and JWKS so that the RS256 verification from 06-01 rotates keys with no intervention. Federation with social identities, the lifecycle with SCIM, MFA per role and careful recovery complete the picture. Kilometre Zero now has Keycloak with the km0 realm, the clients web-km0, courier-app and orders-service, roles and per-producer groups, OpenLDAP with Jordan and Martha, oidc_client.py with PKCE and validation against JWKS, service_token() for orders, and an LDAP query for the access review.

And yet two things are still fragile. orders-service identifies itself with a client_secret, which is a machine password stored somewhere; inventory accepts that identity because the token is valid, but it has no way of knowing whether the TLS connection reaching it really comes from the orders container or from any process that has stolen the secret. And the km0_analytics password is still in an environment variable of the DAG, just as 05-05 left it. The next lesson abandons the idea of a perimeter: each service will have its own certificate, every connection will be authenticated in both directions (mTLS), authorization will also be done by service identity, and secrets will stop being written to files and live in Vault instead, with dynamic credentials that expire on their own.