{"templateId":"markdown","versions":[{"version":"v1.40","label":"v1.40 STS","link":"/products/custody/identity-and-access/sso/troubleshooting","default":true,"active":false,"folderId":"c15a2701"},{"version":"v1.39","label":"v1.39 STS","link":"/products/custody/v1.39/identity-and-access/sso/troubleshooting","default":false,"active":false,"folderId":"c15a2701"},{"version":"v1.38","label":"v1.38 STS","link":"/products/custody/v1.38/identity-and-access/sso/troubleshooting","default":false,"active":true,"folderId":"c15a2701"},{"version":"v1.34","label":"v1.34 LTS","link":"/products/custody/v1.34/identity-and-access/sso/troubleshooting","default":false,"active":false,"folderId":"c15a2701"},{"version":"v1.26","label":"v1.26 LTS","link":"/products/custody/v1.26/identity-and-access/sso/troubleshooting","default":false,"active":false,"folderId":"c15a2701"},{"version":"v1.19","label":"v1.19 LTS","link":"/products/custody/v1.19/identity-and-access/sso/troubleshooting","default":false,"active":false,"folderId":"c15a2701"},{"version":"v1.15","label":"v1.15 LTS","link":"/products/custody/v1.15/identity-and-access/sso/troubleshooting","default":false,"active":false,"folderId":"c15a2701"}],"sharedDataIds":{"sidebar":"sidebar-products/custody/@v1.15/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Troubleshoot SSO","description":"User guides, API reference, and support resources.","siteUrl":"https://docs.ripple.com","lang":"en-US","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"troubleshoot-sso","__idx":0},"children":["Troubleshoot SSO"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use this page to investigate federated identity and SSO issues without exposing sensitive identity data."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"start-with-the-failure-point","__idx":1},"children":["Start with the failure point"]},{"$$mdtype":"Tag","name":"Diagram","attributes":{"data-language":"mermaid","diagramType":"mermaid","diagramSource":"flowchart TD\n A[\"User starts login\"] --> B{\"Redirect to Keycloak works?\"}\n B -- No --> R[\"Check URLs, ingress, TLS, and Keycloak availability\"]\n B -- Yes --> C{\"External IdP login works?\"}\n C -- No --> I[\"Check discovery, client ID, client secret, redirect URI, scopes, and IdP policy\"]\n C -- Yes --> D{\"Keycloak maps the user?\"}\n D -- No --> M[\"Check provider mappers and required claims\"]\n D -- Yes --> E{\"Custody accepts the token?\"}\n E -- No --> T[\"Check issuer, audience, subject, loginIds, and user domain access\"]\n E -- Yes --> S[\"Check session, role, policy, and application-specific behavior\"]\n","diagramHtml":"

No

Yes

No

Yes

No

Yes

No

Yes

User starts login

Redirect to Keycloak works?

Check URLs, ingress, TLS, and Keycloak availability

External IdP login works?

Check discovery, client ID, client secret, redirect URI, scopes, and IdP policy

Keycloak maps the user?

Check provider mappers and required claims

Custody accepts the token?

Check issuer, audience, subject, loginIds, and user domain access

Check session, role, policy, and application-specific behavior

","diagramHtmlDark":"

No

Yes

No

Yes

No

Yes

No

Yes

User starts login

Redirect to Keycloak works?

Check URLs, ingress, TLS, and Keycloak availability

External IdP login works?

Check discovery, client ID, client secret, redirect URI, scopes, and IdP policy

Keycloak maps the user?

Check provider mappers and required claims

Custody accepts the token?

Check issuer, audience, subject, loginIds, and user domain access

Check session, role, policy, and application-specific behavior

"},"children":["flowchart TD\n A[\"User starts login\"] --> B{\"Redirect to Keycloak works?\"}\n B -- No --> R[\"Check URLs, ingress, TLS, and Keycloak availability\"]\n B -- Yes --> C{\"External IdP login works?\"}\n C -- No --> I[\"Check discovery, client ID, client secret, redirect URI, scopes, and IdP policy\"]\n C -- Yes --> D{\"Keycloak maps the user?\"}\n D -- No --> M[\"Check provider mappers and required claims\"]\n D -- Yes --> E{\"Custody accepts the token?\"}\n E -- No --> T[\"Check issuer, audience, subject, loginIds, and user domain access\"]\n E -- Yes --> S[\"Check session, role, policy, and application-specific behavior\"]\n"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"common-symptoms","__idx":2},"children":["Common symptoms"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Symptom"},"children":["Symptom"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Check first"},"children":["Check first"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["User cannot reach the sign-in page"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Keycloak availability, ingress, TLS, hostname, and browser redirect URL."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["IdP rejects the login request"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Client ID, client secret, redirect URI, requested scopes, and IdP application assignment."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["User loops through the identity provider"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["IdP prompt and consent settings, and whether the user has already granted required consent."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Login succeeds at the IdP but fails in Keycloak"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Keycloak provider settings, client secret, discovery endpoint, JWKS, and provider mappers."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Web login remains stuck after identity-provider authentication"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Keycloak client configuration, required claims, and token mapper configuration."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Token validation returns 401"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Issuer, audience, token expiry, signing key, and whether the token subject matches a Custody login ID."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["User signs in but sees only some domains"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["loginIds"]},", roles, and domain access for each domain where the user should operate."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Repeat login creates or finds the wrong user"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Mapper templates, chosen claim, sync mode, and whether the claim is stable and populated."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Keycloak or dependent services fail after deployment"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Database connection URL encoding, Keycloak database state, client secrets, and deployment secret references."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"claim-and-mapper-checks","__idx":3},"children":["Claim and mapper checks"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For a federated user, confirm:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The upstream ID token contains the claim used by ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["${CLAIM.}"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The Keycloak provider alias matches the Custody ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["loginIds.providerId"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Username template mappers use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[":"]}," as the separator."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Hardcoded user session attribute"]}," mapper sets ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["identity_provider_alias"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The Keycloak-issued token subject is the value Custody expects for the user's login ID."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If a mapper template resolves to an empty value, request the missing scope in Keycloak or configure the upstream identity provider to emit the required claim."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"browser-visible-and-server-side-failures","__idx":4},"children":["Browser-visible and server-side failures"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Some SSO failures are not visible in browser developer tools. During OIDC federation, the browser sees the redirects, but Keycloak also performs server-side calls to the upstream provider."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Failure area"},"children":["Failure area"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Where to look"},"children":["Where to look"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Authorization redirect"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Browser network trace, redirect URI, provider alias, and IdP application assignment."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Token exchange"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Keycloak logs, upstream token endpoint availability, client secret, TLS trust, and network policy."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["User mapping"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Keycloak logs, provider mappers, token claims, and Custody ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["loginIds"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Custody authorization"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Custody API response, user roles, domain access, policy requirements, and signing state."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If login fails after the upstream IdP step, do not rely only on the browser trace. Check Keycloak logs for token endpoint, TLS, issuer, audience, and mapper errors."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"secret-and-redirect-checks","__idx":5},"children":["Secret and redirect checks"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Client secret and redirect URI mismatches are common because both Keycloak and the upstream identity provider must agree on the values."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Area"},"children":["Area"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"What to compare"},"children":["What to compare"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Identity provider client secret"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Secret configured on the Keycloak identity provider and the secret configured for the application in the upstream IdP."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Component client secrets"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Secrets stored in Keycloak and the deployment secrets consumed by Custody components."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Redirect URI"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Redirect URI registered in the upstream IdP and the Keycloak broker endpoint for the provider alias."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Issuer URL"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Issuer in tokens and the issuer expected by the downstream verifier. Match scheme, host, port, realm, and trailing slash behavior exactly."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Audience"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Audience in the token and the value expected by the receiving service."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When rotating secrets, remember that Keycloak stores some configuration in its realm database. Updating a Kubernetes secret alone might not update the value already stored in Keycloak. Confirm the value in the upstream IdP, Keycloak, and the deployment secret reference."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For deployment-level secret references, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/v1.38/deployment/reference/auth-secrets"},"children":["Secret management for authentication"]}," and ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/v1.38/deployment/reference/keycloak"},"children":["Keycloak configuration"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"keycloak-deployment-checks","__idx":6},"children":["Keycloak deployment checks"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If Keycloak or a dependent service fails immediately after deployment:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Confirm Keycloak can connect to its PostgreSQL database."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Percent-encode reserved URL characters in database usernames or passwords used in connection strings."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Confirm Keycloak realm import or synchronization completed successfully."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Confirm client secrets in Keycloak match the secrets consumed by dependent services."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Confirm the Keycloak issuer URL is reachable from both the browser path and the in-cluster service path."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"evidence-to-collect","__idx":7},"children":["Evidence to collect"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Collect enough evidence to isolate the failure point:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The Keycloak provider alias."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The non-secret IdP client settings: discovery endpoint, redirect URI, scopes, and issuer."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Sanitized Keycloak logs around the failed login."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Sanitized application logs around the failed API call."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Decoded JWT headers and claims with signatures, secrets, and personal data removed."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Timestamp, redacted user identifier, and whether repeat login or first login failed."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Do not collect client secrets, private keys, full JWTs, or unredacted identity data in tickets or chat."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"when-login-succeeds-but-authorization-fails","__idx":8},"children":["When login succeeds but authorization fails"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["SSO proves who the user is. It does not grant custody permissions by itself. If authentication succeeds but the user cannot perform an action, check:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The user exists in the expected domain."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The user has the expected ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["loginIds"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The user has the roles required by policies and domain read access."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The operation still has the required signature and approval path."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The user is not locked."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For user operations, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/v1.38/governance/users/manage-users-and-roles"},"children":["Manage users and roles"]},". For the policy model, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/v1.38/governance/policies"},"children":["Policies"]},"."]}]},"headings":[{"value":"Troubleshoot SSO","id":"troubleshoot-sso","depth":1},{"value":"Start with the failure point","id":"start-with-the-failure-point","depth":2},{"value":"Common symptoms","id":"common-symptoms","depth":2},{"value":"Claim and mapper checks","id":"claim-and-mapper-checks","depth":2},{"value":"Browser-visible and server-side failures","id":"browser-visible-and-server-side-failures","depth":2},{"value":"Secret and redirect checks","id":"secret-and-redirect-checks","depth":2},{"value":"Keycloak deployment checks","id":"keycloak-deployment-checks","depth":2},{"value":"Evidence to collect","id":"evidence-to-collect","depth":2},{"value":"When login succeeds but authorization fails","id":"when-login-succeeds-but-authorization-fails","depth":2}],"frontmatter":{"seo":{"title":"Troubleshoot SSO"}},"lastModified":"2026-07-27T10:10:43.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/products/custody/v1.38/identity-and-access/sso/troubleshooting","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}