IWA to Forms-Based Fallback Skip to main content
How satisfied are you with the Okta Help Center?
Thank you for your feedback!
How satisfied are you with the Okta Help Center?
Very Dissatisfied
Very satisfied
Enter content less than 200 characters.

IWA to Forms-Based Fallback

Sep 20, 2015 | by Thomas Hill in Managing Apps with Single Sign On

Original Author: Christopher Niggel, Sr. Manager, Security and Compliance, Okta

During our presentation at Oktane13, we shared how we created forms-based failover using the IWA (Desktop SSO) application.  That slide generated a huge amount of interest, so I wanted to share more details with the Okta community.  This solution isn't perfect, but it has made a difference to our users.


Using the Okta IWA application, if a user has a Kerberos ticket failure, they are redirected to an HTTP Basic authentication prompt.  We would like them to see a forms-based authentication


Kerberos / Integrated Windows Authentication is a great tool, especially in Microsoft shops. We have a significant Mac population, however, and as OS X will only refresh a Kerberos ticket when an authentication event happens while the user is on the network, it's pretty common for users to have expired Kerberos tickets (Unlocking your Mac from sleep doesn't count as an authentication event, because the Wireless is turned off until you've logged back into your session).  We needed a way to redirect users to a forms-based authentication source that they would be familiar with.  Okta's IWA application is a .Net Web Application that runs on top of Microsoft IIS and is closed source.  This unfortunately limits us in what we can do, particularly because IIS cannot fall back to forms-based authentication when using Kerberos / Integrated Windows Auth, and we cannot run ASP code inside of a custom error page.  Finally, the way that Kerberos is implemented in HTTP requires the server to present a 401 error page, meaning we can't just redirect on 401.  We can leverage browser-based Meta redirects, however, taking an old HTML trick and reusing it.


To present your users with the Okta login page after an IWA failure, we chose to use a meta redirect.

  1. Log into your Okta IWA server and open the Internet Information Services (IIS) Manager
  2. Navigate to <your_server>/Sites/Default Web Site/IWA
  3. The right-hand pane should be in the Features view. Locate Authentication under the IIS heading and open it up
  4. You will now see your Authentication providers.  Highlight Windows Authentication and click on Providers in the Actions panel
  5. By default your Enabled Providers will be Negotiate and NTLM. Remove NTLM.  You have just forced your users to use Kerberos / IWA, and gotten rid of that browser pop-up.  We must now give them a fall-back option to a form
  6. Close the IIS Manager and open Notepad with elevated permissions by locating Notepad in your start menu, right-clicking on it, and selecting Run As Administrator
  7. An elevated Notepad window will open. It looks just like regular Notepad.  Go to File / Open and locate <system_drive>\inetpub\custerr\en-us\401.htm  (you may need to change the file type drop-down from *.txt to all files)
  8. Using Notepad, find the <head> </head> tags.  Add this line in between these tags:  <meta http-equiv="refresh" content="0;https://<your_org>.okta.com/login/default" />  replacing <your_org> with your organization's account name
  9. Sometimes users will have a Meta Refresh blocker in place.  To resolve this, you may want to add another line between the <body> tags to allow users to click and be forwarded to Okta:   <h3>SSO ticket not found. Please <a href="https://<your_org>.okta.com/login/default">click here</a> to log into Okta.</h3>
  10. Save your changes and repeat on all of your production IWA servers

Known Issues

This isn't a perfect solution, as you'll note that there is no method of capturing the RelayState parameter or the Application-Specific URL that is passed when a user clicks on a deep link.  For example, we have an internal link to a learning application.  If a user clicks on that link and experiences a kerberos failure, they will be directed to their Okta dashboard, NOT the learning application.  The user will then have to follow the internal link a second time - since they now have an active Okta session, they'll be directed correctly into the application.  We hope to address this issue in early Q1 '14 with a project we're calling Universal Login Server.

There is a second issue with this solution, involving Firefox directly.  Somehow Firefox triggers a code path inside of IIS that does not display our custom 401 error page, but instead a generic page that we cannot modify.  I have not yet understood why this happens, or if there is anything we can do about it.  We've trained our Desktop Support team on this issue, and how to work around it by causing an authentication event on the user's Mac.  This can be easily performed by having the user go into System Preferences, and opening any panel with a "lock" icon, like the user properties.  When a user unlocks that icon using their password, an auth event occurs and their Kerberos ticket is refreshed.


I hope this helps some of you with your IWA problems.  We have a proof-of-concept available internally for handling these deep-link issues, but it's not yet ready for prime-time.  Hopefully we can release that project in late Q1 if the community doesn't solve the problem first!