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:

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

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

Overview of the steps

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. Using PowerShell to configure Office365 to use an external identity provider.
5. Setting up OpenAM with the WS-Federation entities for Office 365.
6. 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

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).
3. Any directory service, such as OpenDJ or a Windows Active Directory domain, configured with network connectivity to the OpenAM instance.
4. A business Office 365 subscription capable of federating with third party identity providers. in this example, I used a business premium subscription.
5. An SSL certificate issued from a public trusted certificate authority such as goddaddy. Note that free “Let’s encrypt” certificates work just fine.
6. A public DNS zone which you can configure with the DNS records required for use with Office 365.
7. Windows machines and devices for testing.

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.

1. 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. 
2. 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.

3. 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

4. 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. 
5. 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. 
6. 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:

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 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]

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 or use my metadata and PowerShell generation tool 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.

If you don’t use Active Directory, you will want to configure something similar with the LDAP module.

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.

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:

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

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

Set-CsOAuthConfiguration -ClientAdalAuthOverride Allowed

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
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.