How do I configure AM (All versions) as an Identity Provider for Microsoft Office 365 and Azure using WS-Federation?

Introduction

This article details the officially supported method for setting up AM to be an IdP for Azure and/or Office 365 (O365). This uses the WS-Federation standard to achieve federation as Microsoft no longer certify third-party IdPs using SAML2 in conjunction with their cloud platform. Although WS-Federation is not as widely used as SAML2, it has the added benefit of supporting older Office applications, such as Outlook 2013 as well as third-party mail and calendar clients.

Authentication scenarios

The authentication scenarios available are dependent on the client application and the features that are enabled in O365 and AM. All the authentication features of AM are supported when the client can support authentication through a web browser, WsFederation Passive Flow:

• Sign on through a web browser (for example to access SharePoint® online) allows the user to authenticate with all the supported authentication methods in AM, such as Windows Desktop SSO (Integrated Windows Authentication), push authentication and multi-factor authentication (MFA).
• As Word, Excel and PowerPoint 2013 (Windows) and 2016 (Windows and Mac OS) authenticate through a web browser, these also support all the authentication methods available in AM.
• Outlook® 2016 and Skype for business 2016 support web browser authentication (passive flow) when modern authentication is enabled in O365. Once enabled, these applications can support all the authentication methods available in AM.
• Older Office applications such as Outlook 2013 only support username/password authentication using WsFederation Active Profile. For this to work correctly, the default chain in the realm must only prompt for a username and password. The procedure below describes a workaround that can allow a chain with MFA or WDSSO to be used for passive flow scenarios, while still having a default chain in a realm that only uses username/password for Outlook 2013.
• The Android Native Mail client and the Mac Office 365 client only support the WsFederation Active Profile flow, which requires UPN (User Principal Name) instead of a mapped user name. The syntax for UPN is username@domain.

The following table illustrates this in more detail:

Prerequisites

1. A business O365 subscription or Azure subscription, capable of federating with third-party IdPs.
2. A public DNS zone which has been configured with the DNS records required for use with O365/Azure.
3. An AM deployment running on SSL. See Installation, How do I enable SSL in AM (All versions) post-install? and How do I enable SSL in AM (All versions) for an existing installation? for further information.
4. If you require authentication from mail clients or messaging clients like Skype for business or Lync, then your AM deployment must be available publicly on the internet, protected by a publicly trusted SSL certificate.
5. Users in a directory service such as DS or Active Directory (AD), provisioned with:
   • A unique identifier such as employeeNumber or ObjectGUID.
   • A unique email address style identifier, such as an email address in the mail attribute, or userPrincipalName. The domain in this identifier must match the domain that is set up in your O365/Azure subscription.
6. A data store configured in a given realm in AM that has been configured to load profiles from your directory service. See Identity stores and How do I create a user data store in AM (All versions) using ssoadm? for further information.
7. An LDAP or AD authentication module that has been configured to authenticate users against your directory service. This module should be part of the chain that is set as the organizational chain to use in the realm. See Authentication modules and chains for further information.
8. Accounts provisioned in Azure AD/O365 with attributes matching the accounts in your directory service. For example:
   • For a DS data store:
     • The mail attribute on a DS user could map to the userPrincripalName attribute on the equivalent O365/Azure user.
     • The employeeNumber on a DS user could map to the ImmutableID attribute on the equivalent O365/Azure user.
   • For an AD data store (or an environment where you have, or are migrating from DirSync or ADFS):
     • The userPrincipalName on an AD user could map to the userPrincripalName attribute on the equivalent O365/Azure user.
     • The ObjectGUID on an AD user, converted to base64 (that is, ObjectGUID;binary), could map to the ImmutableID attribute on the equivalent O365/Azure user.
9. A client machine with Java® installed to run the metadata generation tool.
10. A Windows VM (Windows 8.1 onwards) to configure O365 using PowerShell if you are responsible for the configuration.
11. A token signing certificate, installed in AM, for signing the assertion that is sent to O365/Azure.
12. If you plan to use Windows Desktop SSO (WDSSO, also known as Integrated Windows Authentication or Kerberos), you will need a WDSSO module configured in your realm with appropriate keytab files configured. See How do I set up Kerberos authentication in AM (All versions)? and How do I set up the WDSSO authentication module in AM (All versions) in a load balanced environment? for further information.

Configuring AM

You can configure AM as follows:

1. In your LDAP or AD authentication module, locate the Attribute Used to Search for a User to Be Authenticated. If you haven't done so already, add the attribute containing your email address style identifier here, so that a user can log on with this identifier (this is typically mail or userPrincipalName). Navigate to: Realms > [Realm Name] > Authentication > Modules > [Module Name] > Attributes Used to Search for a User to be Authenticated and add the attribute:

2. Add your AD or LDAP module to a chain that is the organizational default chain in the realm by navigating to: Realms > [Realm Name] > Authentication > Chains > [Chain Name] and add your module.
3. Test that a user can now authenticate with your email address style identifier.
4. If you are using WDSSO, navigate to: Realms > [Realm Name] > Authentication > Chains > [Chain Name] and add your WDSSO module to another chain as SUFFICIENT, followed by your AD or LDAP module as REQUIRED. For example, if you are using the LDAP module: WDSSO -> SUFFICIENT LDAP -> REQUIRED
5. If a circle of trust does not exist for your realm, navigate to Realms > [Realm Name] > Applications > Federation, click Add Circle of Trust and enter details for your new COT.
6. Download and run the O365 Metadata generation tool from the Bitbucket® Server. This tool generates the necessary metadata to create a pre-configured WS-Federation IdP and SP entry for O365/Azure.

7. Follow the prompts in the tool:
   • domain This is the DNS domain that has been configured in O365/Azure and should match the domain of the email address style identifier on your user accounts.
   • realm name The path to the realm when your users are authenticating in AM. The top level realm is /, a realm called "myrealm" is /myrealm, a subrealm of that realm would be /myrealm/mysubrealm.
   • OpenAM service URL The https URL of AM that your users use to reach AM (usually your load balancer URL), for example https://idp.example.com:8443/openam
   • name of circle of trust The name of the circle of trust that you configured in step 5.
   • choose a URI name for your OpenAM IDP This is the unique identifier of your IdP in O365/Azure. This can be anything you want, but to ensure it is unique, it is typically set to the same value as the OpenAM service URL. Just use the default value if you don't already have an IdP configured.
   • choose a meta alias for your IDP A metaAlias is a means of uniquely identifying a given entity provider within AM by using an alias that is suffixed to each AM endpoint. Use the default value if you don't know what to do here.
   • name of signing certificate in OpenAM The alias of your token signing certificate in AM's truststore. It is possible to use the test certificate, but this is not recommended. Using the test certificate here will allow anyone to impersonate AM and gain access to your O365/Azure subscription.
   • name of attribute to map to UPN The attribute that holds the email address style identifier in your AM data store. This attribute will map to the userPrincipalName attribute of your user accounts in O365/Azure.
   • name of attribute to map to ImmutableID The attribute that holds a unique identifier, such as employeenumber or objectGUID.
   • Do you wish to define an Authentication URL If you are using a chain with more than one module (or WDSSO and/or MFA) and you need to support older clients such as Outlook 2013, set the authentication URL to the following: https://<OpenAM service URL>/XUI/?service=<wdssoChainName>#login where <OpenAM service URL> is the URL you defined earlier in the tool, and wdssoChainName is the chain containing your Windows Desktop SSO module that you created in step 4.
   • enter file name prefix This is a prefix that you can optionally give to the files that the tool generates.

8. Import the metadata and extended metadata for your IdP. These files end with the names o365-idp-metadata.xml and o365-idp-metadata-extended.xml respectively. Make sure you select the correct realm when importing the files. See How do I export and import SAML2 metadata in AM (All versions)? for further information.
9. Import the metadata and extended metadata for your SP (files ending in o365-sp-metadata.xml and o365-sp-metadata-extended.xml), ensuring you select the correct realm. See How do I export and import SAML2 metadata in AM (All versions)? for further information. For example, your configuration would now look similar to:

10. Obtain the base64 encoded x.509 public certificate of your token signing key. Remove any line breaks from the encoded certificate and paste it into the PowerShell script that the tool generated (ends in o365-powershell-cfg.ps1) between the double quotes on the line saying $SigningCert = "X", replacing the X character. The value to paste here can be obtained by examining the AM metadata located in the URL displayed at the end of the tool, or by running keytool like so (depending on your keystore format):
    • JCEKS format: $ keytool -list -rfc -keystore /path/to/am/am/keystore.jceks -storetype JCEKS -alias <certificate alias name>
    • JKS format: $ keytool -list -rfc -keystore /path/to/am/am/keystore.jks -alias <certificate alias name>

Configuring O365/Azure

The remainder of the configuration steps are carried out in the O365/Azure PowerShell management console. This may be handled by someone else in your organization. If that is the case, it would be appropriate to provide that person with the PowerShell script that was generated by the tool (which you altered to include your token signing certificate) and the steps below:

1. Connect to O365/Azure on a Windows machine that has been set up for administering Azure with PowerShell. Instructions for setting up a machine like this are located in the comments at the top of the PowerShell script that was generated by the tool in the previous section.
2. Execute the script generated by the tool once connected. Note that it can take some time for the settings in O365/Azure to take effect. Users should now be able to access O365/Azure web-based services (such as SharePoint online) by signing on at https://login.microsoftonline.com
3. Use your PowerShell console to enable modern authentication in the Skype for business and Exchange online tenants:
   • Enabling in Skype: https://aka.ms/SkypeModernAuth
   • Enabling in Exchange: http://social.technet.microsoft.com/wiki/contents/articles/32711.exchange-online-how-to-enable-your-tenant-for-modern-authentication.aspx

Limitations

You should be aware of the following limitations:

• WS-Federation Active Requestor profile (the mode that is used by Outlook 2013 to retrieve mail) only supports authentication using the default chain in the realm, and only supports username and password authentication. A default chain in the realm with other modules present will cause authentication via Active Requestor profile to fail.
• The approach used to support WDSSO (Integrated Windows Authentication) enables this form of authentication when IdP or SP initiated SSO is used in combination with the O365/SP only. It does not generally enable WDSSO for authentication in the realm, as this would prevent Active Requestor profile authentication from working correctly.

SSO URLs

SP initiated SSO

SP initiated SSO can be achieved by visiting the following URL on O365/Azure. The username in the URL parameter does not have to exist, but the domain suffix needs to be accurate for redirection to occur correctly:

IdP initiated SSO

IdP initiated SSO can be achieved using a URL like the following for the top level realm and an IdP with the metaAlias "wsidp":

Another IdP initiated SSO example, for a realm called mySubRealm, which is a sub realm of myRealm, and an IdP with the metaAlias "myidp":

See Also

What federation standards does AM support?

How do I configure AM (All versions) to integrate with Microsoft Office 365 using SAML2?

Configuring and troubleshooting Kerberos and WDSSO in AM

OpenAM as an identity provider for Office 365 (WSFed)

Related Training

N/A

Related Issue Tracker IDs

N/A