Troubleshooting

The PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target error is one of the most common issues when deploying ForgeRock Directory Services (DS) in production. It means the Java runtime cannot verify the TLS certificate chain — and until you fix it, LDAPS connections, replication, and AM-to-DS communication will all fail. Clone the companion repo: All diagnostic and fix scripts from this guide are available at IAMDevBox/forgerock-ds-cert-troubleshoot. Clone it, configure config.env, and run ./scripts/diagnose.sh ds.example.com 1636 for instant diagnosis. ...

The redirect_uri mismatch is the second most common OAuth error after invalid_grant. Every OAuth provider requires that the redirect URI in your request exactly matches a pre-registered value — and “exactly” means character-for-character, including trailing slashes, ports, and protocol. This guide covers every cause and provider-specific fix. Quick Diagnostic: Which Provider Error Are You Seeing? Error Message Provider Jump To Invalid parameter: redirect_uri Keycloak Keycloak Callback URL mismatch Auth0 Auth0 redirect_uri must be a Login redirect URI in the client app settings Okta Okta AADSTS50011 Azure AD / Entra ID Azure AD Error 400: redirect_uri_mismatch Google Google The redirection URI provided does not match a pre-registered value ForgeRock AM ForgeRock redirect_mismatch AWS Cognito AWS Cognito Every Cause of redirect_uri Mismatch Before checking provider-specific fixes, work through this checklist. Most mismatches fall into one of these 10 categories: ...

Keycloak session errors are the most common source of unexpected logouts. Your application works perfectly in development, then users report being logged out randomly in production. The token refresh returns invalid_grant with a cryptic error_description like “Session not active” — and the Keycloak admin console shows no obvious misconfiguration. This guide explains every Keycloak session type, how their timeouts interact, and how to fix each session error. Quick Diagnostic: Which Error Are You Seeing? error_description Jump To Session not active SSO Session Expired Token is not active Refresh Token Expired Session doesn't have required client Cache Eviction Offline session not active Offline Session Expired Client session not active Client Session Expired authentication_expired in redirect URL Authentication Session Timeout All of these appear as invalid_grant in the OAuth error response: ...

Keycloak LDAP integration fails silently with generic error messages. The admin console shows “Connection refused” or “Test authentication failed” without revealing the actual cause. This guide catalogs every Keycloak LDAP error with exact log messages, Active Directory sub-codes, and fix commands. For initial LDAP setup instructions, see Keycloak User Federation with LDAP and Active Directory. Quick Diagnostic: Which Error Are You Seeing? Admin Console / Log Message Jump To Connection refused Connection Errors LDAP: error code 49 Bind / Authentication Errors SSLHandshakeException: PKIX path building failed TLS / SSL Errors Test Connection passes, Test Authentication fails TLS / SSL Errors PartialResultException: Referral Search and Sync Errors SizeLimitExceededException Search and Sync Errors Sync shows 0 imported, 0 updated Search and Sync Errors LDAP: error code 53 - WILL_NOT_PERFORM Password Change Errors Groups sync but clicking a group raises errors Group Mapper Errors Connection Errors Connection Refused javax.naming.CommunicationException: ldap.example.com:389 [Root exception is java.net.ConnectException: Connection refused] Causes (in order of likelihood): ...

CORS errors are the most frustrating errors in OAuth development. The browser blocks your request, the error message is generic, and the actual cause could be any of 8+ different scenarios. This guide covers every CORS error you’ll encounter in OAuth 2.0 and OIDC flows, with exact browser error messages and provider-specific fixes. Quick Diagnostic: Which Error Are You Seeing? Browser Console Error Jump To No 'Access-Control-Allow-Origin' header on /authorize Scenario 1: Calling /authorize via fetch No 'Access-Control-Allow-Origin' header on /token Scenario 2: Token endpoint CORS AADSTS9002327: Cross-origin token redemption Scenario 3: Azure AD SPA registration CORS error only after session timeout Scenario 4: Keycloak error response bug wildcard '*' when credentials mode is 'include' Scenario 5: Wildcard with credentials Response to preflight request doesn't pass Scenario 6: Preflight failures CORS error on /revoke endpoint Scenario 7: Token revocation Everything works except in production Scenario 8: Proxy/CDN stripping headers Which OAuth Endpoints Support CORS? Before debugging, know which endpoints are designed to accept cross-origin requests: ...

The invalid_grant error is the most common and most confusing OAuth error. It appears during token exchange or refresh token requests, but the same error code covers 18+ different root causes. This guide catalogs every known cause with provider-specific error messages and exact debugging commands. Quick Diagnostic Checklist When you encounter invalid_grant, work through this list in order: Read the error_description — most providers include specific details Is the authorization code fresh? — Exchange immediately, never retry with the same code Does redirect_uri match exactly? — Check trailing slashes, protocol, port Is the PKCE code_verifier correct? — Verify the stored value matches the challenge Are client credentials correct? — Verify client_id and client_secret for the right environment Is the refresh token still valid? — Check idle timeout, absolute lifetime, rotation Has the user’s password changed? — Password resets invalidate tokens on most providers Is the server clock in sync? — Run ntpdate -q pool.ntp.org Check IdP logs — Keycloak events, Auth0 logs, Azure AD sign-in logs Is Google app in “Testing” mode? — Tokens expire after exactly 7 days All Causes of invalid_grant Authorization Code Issues Expired code — Authorization codes have short lifetimes: ...

Replication issues in ForgeRock Directory Services (DS) can be a nightmare, especially when dealing with critical data across multiple servers. I’ve debugged this 100+ times, and each time, I’ve learned something new. This post will cover some advanced techniques to help you troubleshoot and resolve replication issues effectively. Identifying Replication Issues The first step is to identify that there’s a problem. Common symptoms include: Data discrepancies between replicas Slow performance Errors in logs Replication status showing as “Degraded” or “Offline” Let’s dive into specific techniques to diagnose and fix these issues. ...

Visual Overview: sequenceDiagram participant User participant App as Client App participant AuthServer as Authorization Server participant Resource as Resource Server User->>App: 1. Click Login App->>AuthServer: 2. Authorization Request AuthServer->>User: 3. Login Page User->>AuthServer: 4. Authenticate AuthServer->>App: 5. Authorization Code App->>AuthServer: 6. Exchange Code for Token AuthServer->>App: 7. Access Token + Refresh Token App->>Resource: 8. API Request with Token Resource->>App: 9. Protected Resource Token misrouting is a challenging issue that can disrupt authentication and authorization flows in identity platforms like ForgeRock Identity Cloud. It causes users to receive tokens intended for other sessions or clients, leading to security risks and failed user experiences. ...