The Mechanics of How This WorksBefore we get started, let me explain a little bit about how this works. Outlook Web App is just like any other ASP.Net application – it uses IIS for hosting the site, which means that IIS also handles authentication for the web app.
Now, typically, applications that are claims aware use Windows Identity Foundation (WIF). WIF is the API that does all of the token-handling things that the application needs to happen. If I want to use ADFS and claims-based access in my application, I would use WIF as a fundamental component of that app. WIF would do a lot of the heavy lifting so my app doesn’t have to. For example, WIF would take care of receiving the token from ADFS, verifying that it’s legitimate, and even taking the claims out of it and making them consumable by my application.
WIF uses an HTTP module that listens for unauthenticated requests to the application and then takes over. For example, if I access an application without having logged in already, WIF will step in and take care of redirecting me to the ADFS server that it trusts – whom I might use for authentication. We add this HTTP module to an application by putting it in the app’s web.config file. Easy enough.
So what happens after I’m authenticated and my federated identity token is returned to the app? Typically, the token would be validated and parsed so that the claims can be used. However, let’s say that I’m using an app like OWA. OWA doesn’t know anything about claims and tokens, so if I gave it an ADFS token, it wouldn’t know what to do with it.
So what can we do? In older versions of ADFS (v1), there was an agent that you could install on the web server called the NT Token agent. This agent would sit on the server as an ISAPI filter, and after the token is passed to the server, it would map it to an Active Directory account and create an NT token for the user. This effectively turned an ADFS token into an NT token. This way, the application did not require claims – any old app could use ADFS for authentication. The only requirement was that an account has to exist in Active Directory for the user.
The NT Token agent got canned with ADFS v1 and is no longer available in ADFS v2. Some people found this disappointing, but one thing that many people missed is that we now have something even better. When you install WIF on a server, it installs a new Windows service that is Disabled by default. This service is called the Claims to Windows Token Service – or C2WTS. This service effectively does the same thing as the NT Token agent used to do – it turns an ADFS token into a Windows token. However, this time it doesn’t use an NT token – rather, it uses Kerberos Constrained Delegation (KCD) to request a Kerberos ticket on behalf of the identity specified in the UPN claim of the token. The target scenario of this capability is being able to use Kerberos delegation from a claims-based web app to a back-end system such as SQL Server.
Now, if we enable the C2WTS service, it basically steps in when a token is received, gets a Kerberos ticket, and passes it to the app instead. Since OWA is an ASP.Net application, and since it can use Windows Integrated Authentication, there is no reason why we should not be able to configure this in OWA.
Configuring OWA for ADFSAt a high level, here are the things that we are going to do to federate OWA with ADFS:
- Make sure OWA works fine without ADFS first
- Install WIF on the Exchange Client Access Server
- Configure the OWA web.config file to use the WS-Federation Authentication Module supplied by WIF
- Enable and configure the Claims to Windows Token Service
- Configure the Relying Party trust in ADFS
Step 1: Make Sure that OWA is Working Without ADFSThis may be common sense, but it’s a good idea to make sure that OWA is working normally before getting started. In this example, I’ve installed Exchange 2010 on a server called CONTOSO-EX1 and URL for OWA is mail.contoso.com. As you can see, when I browse to OWA, I’m prompted for my Active Directory credentials in Exchange’s Forms Based Authentication page.
Step 2: Install Windows Identity FoundationThe next thing to do is to install Windows Identity Foundation on the Client Access Server. You can download WIF from here. After you install WIF, you should see a new service on the Client Access Server called the Claims to Windows Token Service. This service is not enabled by default. This is what we will be using to turn our SAML token into a Kerberos ticket.
Step 3: Install the Windows Identity Foundation SDKYou installed WIF in the previous step, so you may be wondering why you need the SDK. There is one tool included in the SDK that you need – FedUtil.exe. If you have the SDK installed somewhere else, you can just grab that tool from the SDK and copy it to the Client Access Server. Otherwise, you can download the WIF SDK from here and install it on the Client Access Server. After you install the WIF SDK, you should have FedUtil in the “c:\Program Files (x86)\Windows Identity Foundation SDK\v3.5\” folder.
Step 4: Configure OWANow, you need to run the utility called FedUtil.exe. This tool will update the web.config file for OWA and configure it to trust the ADFS server. You will find the tool on the Client Access Server under “c:\Program Files (x86)\Windows Identity Foundation SDK\v3.5\”. When you run FedUtil.exe, you will get the following dialog:
For the Application Configuration Location field, enter the path to the OWA web.config, which will be “c:\Program Files\Microsoft\Exchange Server\V14\ClientAccess\Owa\web.config” if you are using a default installation of Exchange.
In the Application URI field, enter the URL for OWA – https://mail.contoso.com/owa in my example.
After you click Next, you will need to enter the URL of your ADFS server so FedUtil can grab the federation metadata file. You can just type in the DNS name of the ADFS service, and FedUtil will fill in the rest.
You can walk through the rest of wizard, leaving everything else at the default value. If you were to browse to OWA now, you would see that the authentication module is working, and it will redirect you to the ADFS server instead of presenting you with the OWA forms-based logon page. You can see from the following screen capture that I’m being asked to logon at sts.contoso.com (the ADFS server) instead of mail.contoso.com (the Exchange server).
However, we don’t have the ADFS side of the trust configured yet. And even if we did, OWA would get the SAML token back from ADFS and not know what to do with it because we didn’t configure C2WTS yet.
But before we do, there is one other thing we have to do in OWA. We need to turn off Forms Based Auth. In the Exchange Management Console, open your OWA authentication settings dialog and tell OWA to use IIS. You can get to this dialog by choosing Server Configuration > Client Access, and then select the OWA virtual directory in the bottom pane of the Exchange Management Console.
Just choose Properties to bring up the configuration dialog. Go to the Authentication tab and set the option to “Use one or more standard authentication methods”.
Then, you’ll need to go into IIS on the Client Access server and enable Anonymous Authentication on the OWA virtual directory. To do this, open IIS Manager, browse to the OWA virtual directory, and double-click on the Authentication icon.
Set the Anonymous Authentication setting to Enabled. After you are done, make sure that you run iisreset.
Step 5: Configure C2WTSThere are a few things that you need to do to configure C2WTS. The first is to configure the service and turn it on. To configure it, you will need to allow the Exchange server to use it by modifying C2WTS’es configuration file. You will find this file in “C:\Program Files\Windows Identity Foundation\v3.5\c2wtshost.exe.config”. Open the file in Notepad, and uncomment the following line:
Save the file, and then set the C2WTS service to Automatic and start it up.
The second thing is that you need to go back into the OWA web.config file and tell WIF to use C2WTS to turn the SAML token into a Windows token instead of giving the SAML token back to OWA directly. So go back into OWA’s web.config file, scroll all the way down near the bottom, and add the following text into the Microsoft.IdentityModel element under the Service element:
Two main things that we’re adding here are the parameters mapToWindows and useWindowsTokenService. These two things enable OWA to use C2WTS. Here’s a screen capture of the modified file after the text was added:
Step 6: Set up Relying Party Trust in ADFSThe last step is to add the Relying Party side of the trust in ADFS. You can do this using the standard Add Relying Party Trust wizard in ADFS and using OWA’s Federation Metadata file, which was created in step 4 when we ran FedUtil. In the RP trust wizard, enter the URL for OWA. The wizard will take care of finding the Federation Metadata file, so you don’t have to specify the full path to it.
You can just specify the default values for the rest of the wizard. After you are done, you may get the Claims Rules dialog for the trust. If you do, you can just close it for now.
In order for C2WTS to work, you need to pass a UPN claim in the SAML token. C2WTS uses the UPN claim to look up the user that you want to create the Windows Token for in Active Directory. So, now we need to configure a couple of claim rules to get the UPN out of Active Directory and into the SAML token passed to OWA.
First, we need to make sure that the UPN claims is coming in from Active Directory.
- In ADFS, go to your Claims Provider Trusts, select the Active Directory claims provider, and choose Edit Claim Rules.
- In the Edit Claim Rules dialog, click the Add Rule button.
- In the rule wizard, choose the “Send LDAP Attributes as Claims” template
- In the rule configuration screen, select the Active Directory attribute store and choose to send LDAP attribute User-Principle-Name in the Outgoing Claim Type labeled UPN, as shown in the following screen capture.
- In the ADFS Management Tool, go to the Relying Party Trust that you created for OWA and choose to edit the claim rules there.
- In the Issuance Transform Rules tab, click the Add Rule button.
- In the rule wizard, use the template called Pass Through or Filter an Incoming Claim
- In the Incoming Claim Type field, select the UPN claim and choose “Pass through all claim values”, as shown in the following screen capture:
Trying it OutNow that everything is configured, we can try it out. Before you do, make sure that the account you are testing has a valid mailbox in Exchange and also has the UPN attribute populated in Active Directory.
Using my client, I will browse to https://mail.contoso.com, and I am re-directed to ADFS to log in. I’ll log in with my user’s credentials:
And voila… I’m now logged into OWA via ADFS -