Troubleshooting
Symptoms and fixes, the complete provider settings reference, and the differences in Keycloak 24 and 25.
Symptoms and fixes
| Symptom | Cause | Fix |
|---|---|---|
| Ver.iD shows an error before the wallet step | The broker callback is not registered on the Studio flow, or the flow is inactive | Compare the provider's Redirect URI with the flow's redirect URIs. Scheme, host, port, deployment path, realm and alias must match exactly. |
| Keycloak reports invalid client credentials after the wallet step | The secret's key identifier was entered instead of its value, or a masked value was copied from the Admin API | Enter the secret's Key (as base64url) value directly in the Admin Console. |
| Keycloak logs a signature validation error | Signature validation points at the wrong keys | Keep Validate signatures and Use JWKS URL on with the discovered JWKS URI. Compare the token's kid with the published keys. |
Keycloak logs Could not fetch attributes from userinfo endpoint | Disable user info is off | Set Disable user info = On under the provider's advanced OpenID Connect settings. |
Login succeeds but the verid_* attributes are empty | The scope is not requested, the mapper claim path is wrong, or the attribute is not defined | Check the provider's Scopes, the mappers' Claim values against Scopes and claims, and the user profile attributes. |
| Login is denied right after the wallet step | The post-login flow found a missing or unverified attribute | Inspect the user's attributes, the conditions' Negate output, and that Allow access is a top-level Required execution. |
| The wallet step is skipped and the user is signed in immediately | An existing Keycloak session | Test in a new private window. A session login proves nothing about the wallet. |
| A second user is created for the same wallet identity | The first login flow override is not bound, or email verification is still enabled in it | Check First login flow override on the provider and Verify existing account by Email = Disabled in verid-first-login. |
| Keycloak asks for name or email on the first login | The wallet did not supply them and the realm requires them | Expected: Review Profile collects them. Alternatively request the profile scope or relax the realm's required fields. |
| Saving a mapper leaves you on its edit page | Keycloak 26 behaviour | Return to Mappers and click Add mapper for the next one. |
Login succeeds but the application's token has no wallet_* claims | The client scope is not assigned to that client, or the mapper's Add to ID token is off | Check the client's Client scopes tab and the mapper's token flags, then verify with the client's Evaluate tab. |
For a managed or brokered Keycloak installation, ask its administrator for the login event under Events → User events and the matching server log line.
Provider settings reference
| Section | Setting | Value |
|---|---|---|
| Add provider | Provider type | OpenID Connect v1.0 |
| Add provider | Use discovery endpoint | On, https://ssi.oauth.ver.id/.well-known/openid-configuration |
| General settings | Alias | verid |
| General settings | Display name | Log in with Digital Identity Wallet |
| OpenID Connect settings | Authorization, token, user info, JWKS URL | As imported from discovery |
| OpenID Connect settings | Client authentication | Client secret sent in the request body |
| OpenID Connect settings | Client ID | The Studio flow's client identifier |
| OpenID Connect settings | Client Secret | The secret's Key (as base64url) value |
| OpenID Connect settings | Validate signatures | On |
| OpenID Connect settings | Use JWKS URL | On |
| OpenID Connect settings → Advanced | Use PKCE | On, S256 |
| OpenID Connect settings → Advanced | Scopes | openid plus the requested scopes |
| OpenID Connect settings → Advanced | Disable user info | On |
| OpenID Connect settings → Advanced | Disable nonce | Off |
| OpenID Connect settings → Advanced | Access Token is JWT | Off |
| Advanced settings | Store tokens | Off |
| Advanced settings | Trust Email | Off |
| Advanced settings | Hide on login page | Off |
| Advanced settings | Account linking only | Off |
| Advanced settings | First login flow override | verid-first-login |
| Advanced settings | Post login flow | verid-require-verified-contact when used |
| Advanced settings | Sync mode | Force |
Keycloak 24 and 25 differences
The settings are identical in Keycloak 24.0.1, 25.0.6 and 26.8.1. Only these labels, screens and two behaviours differ.
| Action | Keycloak 26 | Keycloak 24 and 25 |
|---|---|---|
| Create a realm | Manage realms → Create realm | Realm selector in the upper left → Create realm |
| Add the provider | Identity providers → OpenID Connect v1.0, or Add provider when providers exist | Identity providers → Add provider → OpenID Connect v1.0 |
| Client authentication label | Client secret sent in the request body | Client secret sent as post |
| Add a step to a flow | Add execution | Add step |
| After saving a mapper | Stays on the mapper's edit page | Does not stay on the edit page |
| Allow Nullable Property on a mapper | Present; leave it off | May be absent; leave it off where shown |
| Default first broker login flow | Contains Conditional 2FA and Conditional Organization branches | Contains a Conditional OTP branch; keep its requirements as shown below |
The first broker login flow in Keycloak 24 and 25, after disabling email verification:
verid-first-login
├── Review Profile Required
└── User creation or linking Required
├── Create User If Unique Alternative
└── Handle Existing Account Alternative
├── Confirm link existing account Required
└── Account verification options Required
├── Verify existing account by Email Disabled
└── Verify Existing Account by Re-authentication Alternative
├── Username Password Form for identity
│ provider reauthentication Required
└── First broker login - Conditional OTP Conditional
├── Condition - user configured Required
└── OTP Form RequiredKeycloak 24 and 25 only accept signing keys whose JWK carries use. Ver.iD publishes it, so no fixed public key is needed on any version.
Getting help
Contact support with:
- Your Keycloak version, the realm name and the provider alias.
- The time of the failed login, the Keycloak login event and the matching server log line.
- The name of the Studio authentication flow.
Never include client secrets or tokens. For Keycloak's own configuration reference, see the Keycloak server administration guide.