Routing Rule for Custom Login Detected
Last Updated:
Overview
Telemetry detected a routing rule configured to redirect unauthenticated users to a custom embedded login experience (ROUTING_RULE_FOR_CUSTOM_LOGIN_DETECTED). After upgrading to Okta Identity Engine, users who authenticate through this routing rule may not be returned to the application they originally tried to access. Instead, they are redirected to the default application or the Okta dashboard, even after a successful login.
User Experience Impact: Affected users complete authentication successfully but land at the wrong destination. From the user's perspective, they appear to be logged out of the application they were trying to reach — they may attempt to log in again or abandon the session entirely.
This is a post-upgrade behavioral change, not an authentication failure. Review the routing rule configuration and test the end-to-end login flow in an OIE preview environment before upgrading production.
Applies To
- ROUTING_RULE_FOR_CUSTOM_LOGIN_DETECTED
- Upgrade Eligibility: Eligible with Warning
- IdP routing rule configured for a custom embedded login experience
- Loss of origin application context after authentication
The upgrade can proceed. However, the routing rule and custom login configuration must be reviewed and tested before upgrading production to prevent post-upgrade authentication destination failures.
Cause
When an IdP routing rule redirects unauthenticated users to a custom embedded login page, the routing context is passed through the SAML request using the relayState parameter. The custom embedded login page typically drops the SAML request and calls the Okta /authn API directly to authenticate the user. After successful authentication, Okta uses the relayState to route the user back to the application they originally tried to access.
After upgrading to Okta Identity Engine, the relayState parameter is no longer passed through the SAML request chain by default. This is an intentional security improvement in OIE. As a result:
- The routing rule still redirects the unauthenticated user to the custom login URL, but the origin application context is no longer preserved in the SAML request.
- After successful authentication, Okta has no record of where the user originally came from and redirects them to the default application configured in the routing rule — or to the Okta dashboard — instead of the application they were trying to access.
- From the user's perspective, authentication appeared to succeed but they are now at the wrong destination. They are authenticated but unaware of it, and may attempt to log in again.
Known Impacting Gap — IdP Chaining and relayState: In configurations where the custom login page is used as part of an IdP chain, the third-party IdP will no longer receive the origin application context through the SAML request after upgrade. This does not block authentication, but it breaks post-login routing for any integration that relied on relayState to return users to their originating application.
Solution
Choose the appropriate solution based on the integration architecture and long-term roadmap. Validate the selected approach in an OIE preview environment before upgrading production.
Option 1: Shift to the Okta Hosted Sign-in Experience (Recommended)
Refactoring to use the Okta Hosted Sign-in experience eliminates the reliance on the custom routing rule and relayState entirely. The Okta Hosted Sign-in Widget v3 provides significant extensibility — including custom branding, JavaScript hooks, CSS customization, and layout control — without requiring a self-hosted integration.
- The Okta Hosted experience handles origin context natively. Post-login routing is correct without any custom state management.
- This approach provides full access to all OIE authentication policy features and reduces long-term maintenance burden on the integration.
See the developer resources in the Related References section below for examples of sign-in page extensibility available with the Okta Hosted Sign-In Widget v3.
Option 2: Configure a Default Routing Application as a SPA with persistent origin state
Configure the Default Routing Application as a Single-Page Application (SPA) that preserves the user's origin application in browser local storage or a cookie accessible to both the origin application and the Default Routing Application. After authentication, the SPA reads the stored origin and completes the redirect to the correct destination.
- Origin state must be persisted on the client side before the federation redirect begins.
- The stored state must be accessible from the same domain or use a cookie with appropriate scope settings.
Option 3: No modifications possible — Contact Okta Support
If the custom login integration cannot be modified at this time and the existing routing path must remain in place, Okta Support can evaluate enabling a compatibility feature that restores origin context routing without requiring changes to the custom login application.
- This option is a temporary measure and is not the recommended long-term solution.
- A migration to the Okta Hosted Sign-in experience or a client-side state approach (Option 1 or Option 2) should be planned in parallel.
To request this option, open a support case at support.okta.com and describe the routing rule configuration and the origin context loss behavior. Reference this article and the validator key ROUTING_RULE_FOR_CUSTOM_LOGIN_DETECTED when submitting the case.
Need help choosing a path? If the routing rule integration is complex, involves IdP chaining, or the long-term migration path is unclear, contact the Okta Account Team to engage a Technical Account Manager (TAM) or Okta Professional Services. They can assess the specific configuration and provide a tailored remediation plan.
