Integrated Windows Authentication(IWA) with Kerberos and WSO2 Identity Server
Integrated Windows Authentication (IWA), huh?
Imagine you are logged in to your windows machine at university. Now you are trying to access some application related to your university (at UoM it was the famous Moodle), what if you could automatically be logged into the application with your currently logged in windows account.
Yes, that is exactly what Integrated Windows Authentication does. You simply use your already authenticated windows session (or credentials) to log into other applications seamlessly.
Why is this useful?
The main advantage of IWA is that it gives the user a great experience when accessing applications. It takes away the pain of having to enter usernames passwords. So the user can log in to multiple application seamlessly with a combination of an Single Sign On protocol and IWA.
How does Integrated Windows Authentication with Kerberos work?
First of all, Kerberos is only one way to achieve IWA. The other most common way of achieving IWA is to use NTLM. In Identity Server 5.2.0 and before, we used NTLM achieve IWA. Read more about how it works here.
However, we came across a limitation with using NTLM for IWA. In order to get IWA to work, you were forced to run Identity Server on a windows server. With Kerberos now you can run the Identity Server on any OS (Windows or Linux) and still do IWA.
Okay, let’s get to how we can use Kerberos to achieve IWA.
In order for Kerberos to work, the Identity Server, User’s Windows machine and the Kerberos Server (we will be using an active directory as our Kerberos Server) should all be in the same realm. This means that the Kerberos Server or the Active Directory has a shared secret with both Identity Server and User’s machine. In simple terms, both Identity Server and User’s machine have accounts in the Active Directory(Kerberos Server)
Let me start with how IWA with Kerberos works,
Integrated Windows Authentication with Kerberos flow
- A user tries to access an application typically by entering the URL in the browser.
- Since the app uses Single Sign On using SAML, the app sends a SAML Authentication Request to the Identity Server. (Of course this can be any other inbound authentication protocol like OpenID Connect etc.)
- Identity Server checks whether there’s an authenticated session, if not it will prompt for authentication. In this flow the configured authentication mechanism is Kerberos. Kerberos credentials are usually sent in an Authorization header. If that header is not present, Identity Server will respond with a 401 with a www-authenticate : Negotiate header.
- When the browser sees the www-authenticate : Negotiate header, it knows that the Identity Server is looking for a Kerberos Ticket for authentication. Browser would initiate a Kerberos flow with the Kerberos Server (The Active Directory of the domain acts as a Kerberos Server)
- In Kerberos token request, browser will pass the domain name (eg: idp.wso2.com) of Identity Server that came in with the 401 response in step 3 as the intended audience of the token. For a Kerberos Ticket to be issued to Identity Server, the domain name of Identity Server should have been registered as a service principal already (I will explain how we do this in the setup section.) Kerberos server then will include the authenticated windows user’s fully qualified username in the ticket and encrypt the token with the credentials of the Identity Server. (Kerberos Server knows the credentials of the Identity Server since it is a shared secret between the two. ie. Identity Server has an account in the Kerberos Server)
- Browser will POST the Kerberos Token received to the Identity Server along with a context identifier sent in step 3. Identity Server will use its credentials to decrypt the Kerberos Token it receives and extract the authenticated windows username.
- Once the authentication is completed, Identity Server responds to the application with a SAML response containing attributes of the authenticated user.
- Now the user can access application logged in with the username of the windows local account.
How do I set it up?
Setting up IWA with Kerberos on IS 5.3.0 is easy. You will see :)
- Download Identity Server(version 5.3.0 or above) and host(run) it on either Linux or Windows.
2. Add a DNS host entry in the Active Directory to map the IP address of Identity Server to a hostname .
When adding the DNS entry usually we can give the first part of the hostname, AD will append rest of the part with it’s AD domain. So if your AD domain is WSO2.COM, you may end up with something like idp.wso2.com
3. Set the hostname (idp.wso2.com) in IS_HOME/repository/conf/carbon.xml (IS_HOME is the root of the Identity Server installation)
4. Configure the jaas.conf in IS_HOME/repository/conf/identity as below.
5. Create a service account in the Kerberos Server (AD) for IS. Let’s the username of this account be is_service_account
Note : The account used by IS need to be different from the one that is used by any user trying to login to an app.
6. Register the IS as a service principal in Kerberos Server(AD) by using the below commands.
Usually a web server/service is registered in HTTP/<URL_of_Service> format.
setspn -A HTTP/idp.wso2.com is_service_account
setspn -A HTTP/idp is_service_account[setspn -A HTTP/<url of Identity Server> <service_account>]
7. In Identity Server create an Identity Provider (Identity Provider → Add). In the federated authenticators section find the IWA Kerberos Authenticator config section.
IWA Kerberos Configuration in Identity Server
- Service Principal Name → Service Principal name registered in Step 6 along with the Kerberos(AD) domain (ie. SPN_name@<AD_domain>)
- Service Principal Password → password of the account we associate the Service Principal with.
- User Store Domain → You need to fill this only if you want to check the user’s existence in any mounted user stores. If you fill this, Identity Server will check the username found in decrypted Kerberos Token in the specified user stores.
8. Browser settings
You need to tweak your browser a bit to get IWA with Kerberos to work
Firefox:
- Type about:config in address bar
- Search for “negotiate”
- Add the IS URL as a value in “network.negotiate-auth.trusted-uris”
Internet Explorer / Chrome
Follow the last section of this article to get the steps to configure Internet Explorer for IWA. Chrome simply inherits the settings from Internet Explorer. So you don’t have to configure anything additionally.
IWA Authenticator in Action….
To test this authenticator,
- Set up IWA Authenticator following the previous section. So now you have an IDP configured with IWA Kerberos Authenticator. You can engage this IDP with any app to test the flow.
- Setup travelocity.com sample following this doc.
- In the Local & Outbound Authentication Configuration of the Service Provider you will be configuring choose the IDP configured with IWA Kerberos Authentication (This will appear in the federated authenticators drop down)
- From a windows machine run the travelocity.com web app. Note that the windows machine you are logging in from needs to be connected to the AD (Kerberos Server) we configured in Step 1.
