Signing in with Keycloak
Published:
Updated:
This article explains how single sign-on with Keycloak works in MobilityManager, for both users and the administrator who sets it up.
Signing in with Keycloak
- Open the sign-in page and select your company (tenant).
- Choose the single sign-on button. When the provider is Keycloak, its default label is Login with Keycloak (your administrator may have set a custom label).
- You are redirected to your Keycloak realm to sign in.
- Keycloak returns you to MobilityManager, which verifies the response and starts your session.
Note: On your first Keycloak sign-in, an account is created automatically with the Driver role. See "How single sign-on users are provisioned."
What your administrator configures
A SystemAdmin creates a client in your Keycloak realm and enters these values per company in MobilityManager:
| Setting | Value for Keycloak |
|---|---|
| Provider | Keycloak |
| Authority | Your realm URL, for example https://keycloak.example.com/realms/<realm> |
| Client ID | The client ID configured in the Keycloak realm |
| Client secret | The client secret for a confidential client (stored securely, never displayed back) |
| Redirect URI | The MobilityManager callback URL, added as a valid redirect URI on the Keycloak client |
| Scopes | Defaults to openid profile email |
| Button text | Optional; defaults to "Login with Keycloak" |
How the Keycloak flow works
When a user starts SSO, MobilityManager builds an authorization request to the Keycloak endpoint at {authority}/protocol/openid-connect/auth, requesting an authorization code, and includes a state value for CSRF protection. After the user authenticates, Keycloak returns an identity token that MobilityManager validates using the realm's published discovery document and signing keys, checking the signature, issuer, audience, and lifetime before starting the session.
Tip: The Authority must point at the specific realm, not the Keycloak base URL. MobilityManager reads the realm's /.well-known/openid-configuration from that Authority to discover the endpoints and keys.
Troubleshooting
| Symptom | Likely cause |
|---|---|
| "Invalid redirect_uri" at Keycloak | The callback URL is not listed as a valid redirect URI on the client. |
| "Identity provider token validation failed" | Authority points at the wrong realm, the client ID does not match the token audience, or the client is public rather than confidential. |
| "OIDC configuration is incomplete for this tenant" | Authority or client ID is missing in the company's SSO settings. |
| An email account already exists | A local password account uses the same email; an administrator must link it explicitly. |
Related
- Single sign-on: an overview
- Signing in with Azure AD (Microsoft Entra ID)
- Signing in with ADFS or a generic OIDC provider
- How single sign-on users are provisioned
AH
