OpenAM as an identity provider for Office 365 and Azure (WSFed)

ForgeRock now have an official procedure for setting up OpenAM/AM to be an IDP for Office 365. Please see the following knowledge base article on ForgeRock backstage:

How do I configure OpenAM 13.5.x or AM (All versions) as an Identity Provider for Microsoft Office 365 and Azure?

This blog post is out of date. Refer to the blog post on ForgeRock.com for more information:

https://forum.forgerock.com/2016/09/openam-identity-provider-office-365-wsfed/

This post will run through the step necessary to configure OpenAM 13.5 to be an identity provider for Office 365 and Azure using WS-Federation.

One of the new features in OpenAM 13.5 is support for WS-Federation Active Requestor Profile.  This will enable OpenAM to support a greater range of Office 365 rich clients and Azure authentication scenarios when acting as an IDP.

Why WS-Federation?

Office 365 and Azure support WS-Federation, SAML2 and in some cases OpenID Connect for integration with third party identity providers. While SAML2 (specifically SAML2 ECP) can be used for federation, it is only supported in newer Microsoft rich clients. WS-Federation must be used to support slightly older products such as Lync, Outlook 2011 (Mac) and Office 2010 (Windows). In particular, to support Lync and support adding an email account in Outlook 2010/2011, WS-Federation active requestor profile must be enabled.

 

What Works

Using my completely informal testing procedure on my two laptops, an iPad and a Nexus tablet - I’ve managed to get the following results with the configuration below.

platform	test	result
MacOS 10.11.5	Office 2011 Office setup from Word	ok
	Lync for Mac 2011 SignIn	ok
	Outlook 2011 E-Mail account setup & sign in	ok
	Office 2011 Document Connection	ok
	Office 2016 Sign In	ok
	Chrome web Sign In	ok
	Safari Web Sign In	ok
Windows 8.1	Office 2013 CTR Setup	ok
	Skype For Business Sign In	ok
	Outlook 2013 E-Mail account setup	ok
	OneDrive SignIn	ok
	IE web Sign In	ok
	FireFox web Sign In	ok
	Chrome web Sign In	ok
Apple iPad IOS 9.3.5	Microsoft Word Sign In	ok
	Skype For Business Sign In	ok
	Outlook E-Mail account setup	ok
	OneDrive for business Sign In	ok
	Safari Web Sign In	ok
	Apple Mail, contacts, calendar Account setup & sign in	ok
Nexus Tablet Android 5.3	Microsoft Word Sign In	ok
	Outlook E-Mail account setup	ok
	OneDrive for business Sign In	ok
	Chrome web Sign In	ok
	Gmail, calendar, contacts, device management	ok
	Skype For Business Sign In	ok

Overview of the steps

I’ll go through everything that is needed to configure OpenAM 13.5 to work with Office 365.

1. Configuring a DNS zone for Office 365.
2. Setting up the required DNS records for that zone.
3. Making sure that the active directory domain is properly configured with the right UPN suffixes for the user accounts.
4. Setting up Windows Desktop SSO (Integrated Windows Authentication) to work with OpenAM.
5. Using powershell to configure Office365 to use an external identity provider.
6. Setting up OpenAM with the WS-Federation entities for Office 365.
7. Setting up an account in Office365 and setting it to “federated” mode.

Configuration Overview

In this configuration, our public DNS zone is test365.forgepoc.com and we’ll have users with the email address something@test365.forgepoc.com. They’ll have accounts in an internal Active Directory domain. In common with best practice for Active Directory, the DNS zone of the AD domain in this exercise uses a subdomain of the public DNS zone, test365corp.test365.forgepoc.com.

You don't need Active Directory to make this work, you could use any database such as OpenDJ. But as Office 365 is typically used on Windows desktops in an Active Directory domain, I'm using it here.

The reverse proxy will be configured with a public trusted SSL certificate (required for WS-Federation active requestor profile to work with Office 365) and act as an SSL termination point for OpenAM. The host will be called login.test365.forgepoc.com.

You don't need a proxy in order to use OpenAM as an IDP for Office 365, but it is highly recommended.

Requirements

1. A Windows Active Directory domain (see my blog post on setting up one of these). 
2. An OpenAM instance on any supported operating system, configured to use Active Directory for authentication and profile attributes (see my blog post here on setting up and active directory dataStore). OpenAM should be setup with SSL internally.
3. A reverse proxy in between OpenAM and the internet, capable of supporting SSL termination (I'm using NginX). 
4. A Windows Active Directory domain configured with network connectivity to the OpenAM instance. 
5. A business Office 365 subscription capable of federating with third party identity providers. in this example, I used a business premium subscription. 
6. An SSL certificate issued from a public trusted certificate authority such as goddaddy. 
7. A public DNS zone which you can configure with the DNS records required for use with Office 365. 
8. Windows machines and devices for testing.

Note: Currently WSFed Active Requestor profile is only supported in the top level realm in OpenAM. There is an open issue for this here. Alternatively you can set up OpenAM to federate with office 365 using SAML2 ECP, but this only works with newer MS rich clients. 

Configuring a DNS zone for Office 365

Microsoft make this extremely easy using the admin section of the Office 365 dashboard. Here I’m choosing to set this up myself because I already own the domain forgepoc.com and I have other stuff on it. However, it is much easier to allow Office 365 to act as your DNS service. Doing so automatically configures the required DNS records.

To do it the manual way, log in to your Office 365 subscription and select the admin center:

From the left hand menu select settings > Domains.

Click "add a domain" and enter your domain name.

In common with obtaining SSL certificates, you have to verify ownership of your DNS domain by adding a specific TXT record to it.

Now add the required DNS records. It’s important that these are accurate, but luckily Microsoft provide a test tool to verify they are set correctly. Here is a screenshot of the records for my DNS Zone test365.forgepoc.com from my DNS provider:

CNAME Records
Host Name               Points To    
lyncdiscover            webdir.online.lync.com    
msoid                   clientconfig.microsoftonline-p.net    
sip                     sipdir.online.lync.com    
enterpriseregistration  enterpriseregistration.windows.net    
enterpriseenrollment    enterpriseenrollment.manage.microsoft.com    
autodiscover            autodiscover.outlook.com    
                             
MX Records                
Host Name               Points To                                           Priority    
@                       test365-forgepoc-com.mail.protection.outlook.com    0    
                              
SRV Records
Host Name               Points To                                           Port    Weight    Priority    
_sip._tls               sipdir.online.lync.com                              443     1        100    
_sipfederationtls._tcp  sipfed.online.lync.com                              5061    1        100    
                               
TXT Records
Host Name               Value    
@                       v=spf1 include:spf.protection.outlook.com -all

Configuring your proxy

A proxy is not required to get Office 365 up and running with OpenAM, but it is recommended. You'll need some sort of proxy configuration if you plan to use multiple OpenAM servers in a HA deployment behind a load balancer.

For WSFED to work correctly behind a proxy, we need to set the host header on the proxy. Here is my NginX site configuration:

location / {
    proxy_set_header X-Forwarded-Server $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Host $host:$server_port;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header Host $host;
    proxy_pass https://login.test365corp.o365.forgepoc.com:8443;
    proxy_redirect default;
}

In the apache web server, you can achieve the same thing by setting the proxy_pass, proxy_pass reverse and ProxyPreserveHost directives.

<VirtualHost *:443>
    ServerName login.test365.forgepoc.com:443
 ProxyRequests off
 ProxyPass / https://login.test365corp.test365.forgepoc.com:8443/
 ProxyPassReverse / https://login.test365corp.test365.forgepoc.com:8443/
 ProxyPreserveHost On

    ...

</VirtualHost>

Configuring Active Directory UPN suffixes - optional, but recommended

If you have an existing Active Directory domain then it is likely that this will be configured already and you can skip this section. However, if you’ve set up an AD domain to do some basic tests and integration work, then read on.

Let's say I make a user in active directory for Charlie Brown. I use the wizard in Active Directory users and computers and give him first name Charlie, last name Brown, username charlie.brown. Charlie will then be able to put in any of the following into the username prompt when logging on to a domain joined machine:

samAccountName: charlie.brown

cn: charlie brown

dn: CN=charlie brown,OU=user accounts,OU=test365corp,DC=test365corp,DC=o365,DC=forgepoc,DC=com
UPN: charlie.brown@test365corp.test365.forgepoc.com

Active Directory has a concept of user principal names (UPN) - a means of allowing a user account to be referenced by an email address style username that can have a different domain part to the DNS domain of the active directory domain. A UPN consists of the samAccountName and a DNS domain specified by an administrator. 

Now let's say mike wants to log on to his laptop with his email address, charlie.brown@test365.forgepoc.com. To do that, the Windows sysadmin needs to define an additional UPN suffix in the domain.

In office 365, if users authenticate to services directly with office 365 (WSFed active profile) then the user has to authenticate with their UPN. Therefore it makes sense to set the user's active directory UPN to be the same as their office 365 UPN, which would normally be their email address. That way, users only need to remember one username.

In this example, we’ll configure a UPN suffix for the external DNS domain test365.forgepoc.com. Open Active Directory Domains and Trusts (domain.msc) and right click on the root node in the left pane:

Add the UPN suffix:

Quickstart OpenAM configuration using ssoadm batch commands

If you know OpenAM well, here are some ssoadm batch commands that will get you setup quickly. Use the metadata files from below and skip the remaining sections on configuring OpenAM.

create-datastore -e / -m ActiveDirectory -t LDAPv3ForAD -a "sun-idrepo-ldapv3-config-ldap-server=svr1.test365corp.test365.forgepoc.com:636" "sun-idrepo-ldapv3-config-authid=CN=ldapUser,CN=Users,DC=test365corp,DC=test365,DC=forgepoc,DC=com" "sun-idrepo-ldapv3-config-authpw=SOMEPASSWORD" "sun-idrepo-ldapv3-config-connection-mode=LDAPS" "sun-idrepo-ldapv3-config-organization_name=DC=test365corp,DC=test365,DC=forgepoc,DC=com" "sun-idrepo-ldapv3-config-people-container-name=ou" "sun-idrepo-ldapv3-config-people-container-value=test365corp" "sun-idrepo-ldapv3-config-psearchbase=CDC=test365corp,DC=test365,DC=forgepoc,DC=com"
create-auth-instance -e / -t AD -m ActiveDirectoryModule
update-auth-instance -e / -m ActiveDirectoryModule -a "iplanet-am-auth-ldap-bind-dn=cn=ldapAuth,cn=users,DC=test365corp,DC=test365,DC=forgepoc,DC=com" "iplanet-am-auth-ldap-bind-passwd=SOMEPASSSWORD" "iplanet-am-auth-ldap-server=svr1.test365corp.test365.forgepoc.com:636" "openam-auth-ldap-connection-mode=LDAPS" "iplanet-am-auth-ldap-user-naming-attribute=cn" "iplanet-am-auth-ldap-base-dn=DC=test365corp,DC=test365,DC=forgepoc,DC=com" "iplanet-am-auth-ldap-user-search-attributes=mail" "iplanet-am-auth-ldap-user-search-attributes=cn" "iplanet-am-auth-ldap-return-user-dn=true"
create-auth-cfg -e / -m employeeChain
update-auth-cfg-entr -e / -m employeeChain -a "ActiveDirectoryModule|REQUIRED"
set-realm-svc-attrs -e / -s iPlanetAMAuthService -a "iplanet-am-auth-org-config=employeeChain"
import-entity -e / -c wsfed -m /home/centos/idpMeta.xml -x /home/centos/idpMetaExtended.xml
import-entity -e / -c wsfed -m /home/centos/spMeta.xml -x /home/centos/spMetaExtended.xml
create-site -s site1 -i https://login.test365.forgepoc.com:443/openam
add-site-members -s site1 -e https://login.test365corp.test365.forgepoc.com:8443/openam

Configure OpenAM to work behind a proxy

Use the deployment menu in OpenAM 13.5 to add a site to the deployment. Make the site URL the URL of your proxy. Once done, add your OpenAM server(s) to that site.

Configuring OpenAM authentication services

I'm assuming here that you've already got an Active Directory dataStore setup in the top level realm. 

Head over to authentication and create an Active Directory authentication module. Make sure to configure this as described here, it is required for WS-Federation active requestor profile to work later on.

Set up the module as described below. Below, I've allowed users to log on with mail as well as their usual login method, assuming that the mail attribute in the user account matches the UPN of the account setup in office 365.

However, if you have UPN sufixes setup in your AD domain (as described in my instructions above) you'll probably want to use userPrincipalName instead of mail:

Add this module to a chain and set it to be the default organisation login chain for your realm:

Create your WS-Federation hosted IDP and Remote SP

Manually creating WSFED entities in OpenAM is a bit tedious so I’ve provided some ready made entities for you to use here. I am assuming these will be added to the top level realm - you’ll need to adjust your endpoints to match your realm if you’ve used something different. I am also assuming that we’ll use the default OpenAM test certificate for token signing. You should use something different in production.

Go to the Federation section in OpenAM and create a circle of trust called cot:

Import these entities using the import entity button, making sure to add them to the correct realm:

You should now have a list of entities that looks something like this:

Set up your Azure tenant using PowerShell

If you haven’t done it already, install the Azure Powershell cmdlets on a Windows machine that you have access to.

Authenticate using Connect-MsolService:

Then use the Set-MsolDomainAuthentication cmdlet to setup your domain and make sure to set the signing certificate to the cert you are signing your assertions with:

$BrandName   = "ForgeRock test365"
$dom         = "test365.forgepoc.com"

$IssuerUri   = "urn:uri:test365forgepocemployeestlr"
$PassiveUri  = "https://login.test365.forgepoc.com:443/openam/WSFederationServlet/metaAlias/wsidp"
$ActiveUri   = "https://login.test365.forgepoc.com:443/openam/WSFederationServlet/sts/metaAlias/wsidp"
$MexUri      = "https://login.test365.forgepoc.com:443/openam/WSFederationServlet/ws-trust/mex/metaAlias/wsidp"

$Protocol    = "WsFed"

$SigningCert = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

Set-MsolDomainAuthentication `
-Authentication Managed `
-DomainName $dom

Set-MsolDomainAuthentication `
-Authentication Federated `
-DomainName $dom `
-FederationBrandName $BrandName `
-PassiveLogOnUri $PassiveUri `
-ActiveLogOnUri $ActiveUri `
-MetadataExchangeUri $MexUri `
-SigningCertificate $SigningCert `
-IssuerUri $IssuerUri `
-LogOffUri $PassiveUri `
-PreferredAuthenticationProtocol $Protocol

Enabling "modern authentication" on the Azure Exchange and Skype services

Until recently, I had all Windows, MacOS, IOS and Android rich clients working, apart from one: Skype for business for Android. I was about to start analysing the network traffic, when my colleague Peter Major directed my to a community forum question from the user Steven Van Geel.

Even though Steven's question was related to using Android Skype for business with OpenAM as a an Office 365 IDP using SAML2 ECP, the fix he describes also corrects the behaviour with the android app with a WsFed Active profile IDP. Turning on Microsoft "modern authentication" on the Skype for business online tenant allows the Skype client to authenticate.

I have not had a chance to had a look at why this is and why it only affects the Android Skype client. I will update this blog post when I find out. It is highly possible that this may be required for other clients in future as Microsoft gradually move services onto their "Modern Authentication" standard. Note that modern authentication can be turned on for Skype and for Exchange (Outlook).

For now, here are some brief instructions for enabling this. These are pretty similar to the steps for setting up the Azure online domain. First you need to install the Skype for Business PowerShell management cmdlets.

Then run the following to authenticate to your Skype Online (aka Lync Online) tenant:

$credential = Get-Credential
$session = New-CsOnlineSession -Credential $credential
Import-PSSession $session
Get-Module

Then turn on Modern Authentication as described in this article:

Set-CsOAuthConfiguration -ClientAdalAuthOverride Allowed

Setting up your first user

All that is left to do now is to configure a user to sign on to Office 365. Office 365 requires that accounts which federate with Office 365 also have an account entry set up in Office 365 itself. Certain properties have to be set on that account, such as the UPN and what licenses are assigned to the user.

Microsoft provide the tools DirSync and Azure AD Connect that automatically synchronise on-prem Active Directory with Office 365. These are cut down versions of their identity Management Solution, "ForeFront Identity Manager" (FFIM - now EOL). ForgeRock have an Identity Management product, OpenIDM which has a powerful PowerShell connector. This can be configured to automatically provision accounts to Office 365 (see example scripts here and the IDM trunk docs here), but this is outside the scope of this post.

Here, I’ll show how to manually set up an account.

Assuming you have the following user in Active Directory:

The following PowerShell will set up that user in office 365 by copying the attributes from the same user in Active Directory. 

$user = Get-ADUser charlie.brown
MSOnlineExtended\New-MsolUser `
-DisplayName $user.Name `
-FirstName $user.GivenName `
-ImmutableId ([System.Convert]::ToBase64String(($user.ObjectGUID).ToByteArray())) `
-LastName $user.Surname `
-LicenseAssignment (Get-MsolAccountSku | select -ExpandProperty AccountSkuId) `
-UsageLocation GB `
-UserPrincipalName $user.UserPrincipalName 

So how does this PowerShell work? We get the charlie.brown user from AD then pass the properties from it to the New-MsolUser method. We use the Get-MsolAccountSku method to find the SKU of the license we need to assign to the user. We also convert the Active Directory ObjectGUID property into the base64 format expected in Office 365.

Note: If the UPN of your user doesn't match the name that they may fill in on something like the email account setup in Outlook, then you may want to change the userPrincipalName to use the mail attribute instead.

Conclusion

You should now be able to log on to Office 365 using all of the methods described above. There are some issues that you may encounter with this approach which you can track our progress on here.

What next? You may want to look at integrating this with with Integrated Windows Authentication (aka Kerberos, Windows Desktop SSO). I've done a blog post on that.

In a future blog post, I'll look at doing the same thing with SAML2 ECP and the pros/cons of using that instead.