UPDATE
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:
The information below remains for reference only.
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?
What Works
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 & signin | ok | |
Office 2011 Document Connection | ok | |
Office 2016 SignIn | 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 SignIn | 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 & signin | ok | |
Nexus Tablet Android 5.3 | Microsoft Word SignIn | 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
- Configuring a DNS zone for Office 365.
- Setting up the required DNS records for that zone.
- Making sure that the active directory domain is properly configured with the right UPN suffixes for the user accounts.
- Using PowerShell to configure Office365 to use an external identity provider.
- Setting up OpenAM with the WS-Federation entities for Office 365.
- 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 [email protected] 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.
Note: If using a proxy or load balancer in front of OpenAM, make sure you forward the host header. Also ensure that you either set your container (for example tomcat) scheme and secure directives set (as they are by default for an SSL connector), OR set up OpenAM in the first place with SSL.
In this method, I’m going to be setting up the attribute mapping in OpenAM to map the ImmutableID attribute to a base64 encoded version of the ObjectGUID in Active Directory. I have done this to maintain compatibility with how ADFS and DirSync are configured by default. However, you don’t have to do this. You have to map some form of unique identifier to the ImmutableID, but this can be anything you want, and it doesn’t have to be base64 encoded. For example, you could map the employeenumber attribute in OpenDJ to ImmutableID.
Requirements
- A Windows Active Directory domain (see my blog post on setting up one of these).
- 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).
- Any directory service, such as OpenDJ or a Windows Active Directory domain, configured with network connectivity to the OpenAM instance.
- A business Office 365 subscription capable of federating with third party identity providers. in this example, I used a business premium subscription.
- An SSL certificate issued from a public trusted certificate authority such as goddaddy. Note that free “Let’s encrypt” certificates work just fine.
- A public DNS zone which you can configure with the DNS records required for use with Office 365.
- Windows machines and devices for testing.
Bugs that existed with this process can be found here, but all of them have been fixed with the release of AM5 (aka OpenAM 14).
Note: If using a proxy or load balancer in front of OpenAM, make sure you forward the host header. Also ensure that you either set your container (for example tomcat) scheme and secure directives set (as they are by default for an SSL connector), OR set up OpenAM in the first place with SSL.
Federation and Attribute Mapping Requirements
This section goes into detail on how the federation actually works. You may not need to know any of this, especially if you use my metadata generation tool. Microsoft also provide a detailed description on how this works in these documents.
With an office 365 subscription, you get a tenant. A tenant is your slice of the office 365 services such as SharePoint Online (the back end for OneDrive) and Skype for Business Online. The services in your tenant rely on AAD and within AAD you can configure any number of domains. These are purely about DNS, they are not related to on-premises Active Directory, Kerberos, NTLM etc. When you setup your Office 365 tenant, you are automatically given your first domain – somedomain.onmicrosoft.com.
- To use an external IDP with Office 365, you have to set up at least one other domain and you have to prove ownership of it.
- The users that you want to sign on to Office 365 using your IDP must have an email address/UPN with a suffix that matches a domain that you have configured in your tenant.
Once you have set up your domain in Office 365 you have to configure an IDP for it using PowerShell. Unlike normal SAML2 or WSFed federation, you can not import metadata into the PowerShell console for AAD, you have to define your IDP using specific PowerShell commands.
- When setting up the IDP in the AAD PowerShell console, you should define four endpoints. When setting up OpenAM as a WSFed IDP, these endpoints have the following format:
Required: The passive URI endpoint (PassiveLogOnUri):
<OpenAM URI>/WSFederationServlet/metaAlias/<realm-path>/<meta-alias>
Required: The log off URI endpoint (LogOffURI), usually the same as passive URI:
<OpenAM URI>/WSFederationServlet/metaAlias/<realm-path>/<meta-alias>
Optional: The active URI endpoint (ActiveLogOnUri), required for mail clients:
<OpenAM URI>//WSFederationServlet/sts/metaAlias/<realm-path>/<meta-alias>
Optional: The metadata exchange URI, required for Skype for business (aka lync):
WSFederationServlet/ws-trust/mex/metaAlias/<realm-path>/<meta-alias>
A meta alias is a way of referencing a SAML2 or WSFed entity by a URL on OpenAM. For example, on an OpenAM server called http://am.example.com:8080/openam, an IDP with the meta alias myidp in the realm myrealm would have the following URL: http://am.example.com:8080/openam/WSFederationServlet/metaAlias/myrealm/myidp
- Assertions send from the WSFed IDP (OpenAM) to Office 365 must be signed. The certificate used to sign these must also be defined in the AAD PowerShell configuration, but this certificate does not need to be signed by a third party certificate authority.
- You must configure an Issuer URI in the PowerShell AAD console. This must match the federation ID name defined in your IDP entry in OpenAM.
- The assertion sent from OpenAM to Office 365 Requires two attributes with particular namespaces:
UPN
namespace: http://schemas.xmlsoap.org/claims
ImmutableID
Namespace: http://schemas.microsoft.com/LiveID/Federation/2008/05
The UPN and ImmutableID attributes in your provisioned O365 user must match the attributes they are mapped to in your directory service. The ImmutableID attribute would typically map to something unique, such as employee number or the objectGUID attribute in Active Directory. In the example configuration below, we will map to ObjectGUID as that is what ADFS does by default.
Defining namespaces in the WS-Federation attribute mapper is a new feature in OpenAM 13.5. To define namespaces when attribute mapping, you can use the following format:
<namespace>|<assertion attribute>=<OpenAM attribute>
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:
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; }
<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 don’t have active directory, you can skip this section.
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: [email protected]
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, [email protected] 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:
Quickstart OpenAM configuration using ssoadm batch commands
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
Configuring OpenAM authentication services
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:
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.
I have made a tool that generates the metadata and the PowerShell for Office 365 which can be found here. This will hopefully take some of the complexities out of configuring the WSFed IDP in OpenAM.
If you choose to manually create your WSFed configuration in OpenAM, make sure you follow the Federation and Attribute Mapping Requirements above.
My sample metadata, which I am using in this example, maps the ImmutableID attribute to a base64 encoded version of the Active Directory ObjectGUID attribute. This uses a new feature in OpenAM 13.5, the ability to convert binary attributes into a base64 string. I’ve done this to maintain compatibility with how Microsoft set up their equivalent products. If you are replacing ADFS with OpenAM and/or you are using DirSync, you will also want to do this.
I have also defined the namespaces required in my attribute mapper as described above.
Go to the Federation section in OpenAM and create a circle of trust called cot:
Set up your Azure tenant using PowerShell
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
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:
$user = Get-ADUser charlie.brown MSOnlineExtendedNew-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.
The PowerShell above will only work if your are setting up Office 365 in combination with on premises Active Directory. For examples of more simple PowerShell commands for setting up users against OpenDJ for example, see here.
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.
Comments are closed.
Excellent needed information Simon!