What this is about
The CodamAI user interfaces (the hub, the CIAS portal, the CDMS portal) have no login form of their own. When you sign in, you land on a page from Keycloak. You enter your password there and, if needed, a one-time code. Then you come back.
In between sits the BFF, short for Backend for Frontend: the server part of the user interface. It runs the sign-in and keeps the tokens. The browser only gets an encrypted session cookie.
The procedure is called Authorization Code Flow. The “code” is the one-time code that Keycloak returns to the application after the login.
The flow
sequenceDiagram
participant B as Browser
participant F as BFF (server of the user interface)
participant K as Keycloak
B->>F: opens /kunden
F-->>B: not signed in → /login?redirect=/kunden
B->>F: /login starts the sign-in
F-->>B: redirect to Keycloak (with state and PKCE)
B->>K: login page
K-->>B: password, one-time code if needed
B->>K: input
K-->>B: redirect back with code
B->>F: /api/auth/callback/keycloak?code=…
F->>K: exchanges code for tokens
K-->>F: access, refresh and ID token
F-->>B: sets session cookie, back to /kunden
Three terms from the diagram:
- state is a random value. The BFF sends it along and expects it back on the return. This way it knows that the return belongs to its own request.
- PKCE (“pixie”) is a second secret. The BFF only sends Keycloak a hash of it and shows the original when it exchanges the code. If someone intercepts the code on the way, they cannot redeem it without the original.
- The three tokens: The access token is your ID card for every request to the APIs. With the refresh token, the BFF gets a new access token before the old one expires. The BFF needs the ID token later to sign out.
The variants
When: Someone opens a page without a valid session.
-
1Browser→BFFopens a protected page
-
2BFFIs there a valid session without errors?
-
3BFF→Browserredirects to
/login. The CIAS and CDMS portals append the path as?redirect=, the hub always goes to/afterwards
Result: The login page takes over.
When: The page /login is opened without a sign-out just before.
-
1BFFIs the session valid? Then go straight to the target
-
2BFF→Keycloakstarts the sign-in by itself, without anyone clicking
-
3KeycloakIs there still a session at Keycloak? Then no password is needed
-
4Keycloak→BFFsends the code back
Result: If you are still signed in at Keycloak, you do not notice the login. If the browser lands on the login page automatically a second time within 15 seconds, the hub stops and shows a “Sign in again” button. This prevents an endless loop.
When: The sign-out redirects to /login?loggedOut=1.
-
1BFFIs
loggedOutin the address? Then no automatic login -
2User→BFFclicks “Sign in” themselves
Result: The login page stays. Without this brake, the sign-out would sign you in again right away.
When: After the login, you go to the page from ?redirect=.
-
1BFFDoes the target start with
/and not with//? -
2BFFotherwise: target is
/ -
3BFF→Browserredirects to the target
Result: Only paths of the own application are allowed. //andere-seite.de or https://… become /.
The Keycloak pages
What the person sees at Keycloak comes from the login theme in hub-login. A theme is the design of the Keycloak pages, in German and English.
| Page | When it appears |
|---|---|
| Username and password | on every sign-in without an existing Keycloak session |
| One-time code (OTP) | when a second factor is set up for the account |
| Forgot password | link on the login page. Keycloak sends an email to reset it |
| Set or change password | after the link from the welcome email, or when Keycloak requires a new password |
| Page expired | when the login page was open for too long |
| Confirm sign-out | when signing out without an ID token, see Sign out |
OTP means One-Time Password: a code from an authenticator app. It is valid only once and only for a short time.
What is in the browser after the login
An encrypted session cookie that no script on the page can read. It holds the tokens. The refresh token and the ID token never leave the BFF. For the details, see Session in the BFF and cookies.