How To

How do I redirect users to a different login module if Kerberos/WDSSO authentication fails with a 401 error in OpenAM 11.x and 12.x using the Classic UI?

Last updated Jan 5, 2021

The purpose of this article is to provide information on redirecting users who see a "HTTP 401" error when attempting to authenticate to Kerberos / Windows Desktop SSO (WDSSO). This can be achieved with a custom 401.jsp that will redirect users to failover to a different authentication type when this error occurs.

1 reader recommends this article


This article has been archived and is no longer maintained by ForgeRock.

Redirecting users to a different login module


Only users who have already authenticated with a Kerberos KDC can authenticate to WDSSO without entering their credentials again. If a user attempts to authenticate without a valid Kerberos token, the attempt will fail and the user will see a standard 401 Unauthorized / Access denied error page instead of failing over to the next authentication module in the chain. 

You can workaround this by implementing a custom application or container level 401 error page, which redirects the user (using the refresh meta tag within the HTML head tag) to the OpenAM login page to allow authentication to continue using a different authentication module.

The following example refers to Apache Tomcat™:

  1. Create a custom 401 page (for example 401.jsp) in the /path/to/tomcat/webapps directory where OpenAM is deployed. You can use the following code as the basis for a simple redirect in your custom 401 jsp page: <html> <head> <meta HTTP-EQUIV="refresh" content="0;url="> </head> <body>Authentication is required. You will automatically be redirected to the Login page...</body> </html> If you have a complex authentication chain, you may want the refresh URL to send users to a new authentication chain that does not include the WDSSO module. Therefore you'd have one authentication chain that includes the WDSSO module and a second chain that is a copy of the first chain minus the WDSSO module. You could then set the refresh URL to send them to the second chain, for example: <html> <head> <meta HTTP-EQUIV="refresh" content="0;url="> </head> <body>Authentication is required. You will automatically be redirected to the Login page...</body> </html> For a more dynamic custom 401 error page, you can refer to this third-party website for an example: Chaining kerberos with OpenAM – part 3.
  2. Update the web.xml file (located in the /path/to/tomcat/webapps/openam/WEB-INF directory where OpenAM is deployed) to reference your custom 401 page. For example, add the following code to the bottom of the web.xml file: <error-page> <error-code>401</error-code> <location>/401.jsp</location> </error-page> </web-app>
  3. Restart Tomcat to apply these changes. When a 401 error is encountered now, the browser will automatically redirect the user to your custom 401 page.

See Also

How do I set up Kerberos authentication in AM (All versions)?

OpenAM Windows Desktop SSO deep dive – part 1

Authenticating with Windows Desktop SSO in AM (All versions) does not proceed when using a non-Microsoft Edge browser

Configuring and troubleshooting WDSSO in AM

Chaining kerberos with OpenAM – part 3

Related Training


Related Issue Tracker IDs

OPENAM-8422 (OpenAM 12 WindowsDesktopSSO module does not fallback to the next module in the chain)

Copyright and Trademarks Copyright © 2021 ForgeRock, all rights reserved.