How To

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

Last updated Jul 9, 2018

The purpose of this article is to provide information on configuring AM/OpenAM to integrate with Microsoft® Office 365® using SAML2 federation. This article assumes you already have a working AM/OpenAM and Office 365 setup.


Overview

Note

If you want to use WS-Federation instead of SAML2 federation, you should refer to: How do I configure AM (All versions) or OpenAM 13.5.x as an Identity Provider for Microsoft Office 365 and Azure using WS-Federation? for further information. WS-Federation provides support for older products such as Office 2010 and federation in conjunction with Azure®.

When integrating Office 365 (O365) with AM/OpenAM using SAML2 federation, O365 acts as the service provider (SP) and AM/OpenAM as the identity provider (IdP).

The expected access flow for O365 in a federated environment is as follows: 

  1. The user navigates to http://login.microsoftonline.com and enters their login name (their password is not required at this stage). Their login name will be in the following format: username@example.com, where the @example.com part tells O365 that this is a federated login. 
  2. O365 looks the user up internally (along with the associated SAML metadata) and starts the SAML flow by redirecting to the AM/OpenAM login page with a SAML AuthN request.
  3. The user enters their AM/OpenAM credentials.
  4. AM/OpenAM authenticates the user and sends a SAML response back to O365. This response includes the required name identifier as well as an attribute called IDPEmail, which is used by O365 to look for the user in its internal repository.
  5. O365 verifies the SAML response, maps the user and then allows the user to SSO.

For the user, it is a simple flow: they will see the O365 login page, the AM/OpenAM login page and finally be logged in to O365. 

Key requirement (persistent NameID)

O365 requires a persistent NameID for federation to work. This means AM/OpenAM must support the following NameID format: urn:oasis:names:tc:SAML:2.0:nameid-format:persistent.

By default, AM/OpenAM writes two attributes to the user's entry in the user repository to establish persistent federation: sun-fm-saml2-nameid-infokey and sun-fm-saml2-nameid-info. The sun-fm-saml2-nameid-infokey contains a unique Identifier used to link the two accounts; by default this is a randomly generated key that is common between the IdP and SP. When a user federates for the first time, they will need to log in to both the IdP and SP to establish the common NameID value. For that reason, the user data store cannot be read-only. After the initial Federation link is established, only a single login (on the IdP) will be required.

Integrating O365 does not follow the rules above. The NameID cannot be generated by the IdP, but instead must be the Azure Active Directory (AD) user's ImmutableID. From the Office 365 SAML 2.0 Federation Implementers Guide:

NameID - The value of this assertion must be the same as the Azure AD user’s ImmutableID. It can be up to 64 alpha numeric characters. Any non HTML safe characters must be encoded, for example a “+” character is shown as “.2B”

To achieve federation, you must pre-populate these SAML attributes. These attributes must be in the following format, where ImmutableID is replaced with an appropriate value:

sun-fm-saml2-nameid-info: http://office365.example.com:8080/openam|urn:federation:MicrosoftOnline|ImmutableID|http://office365.example.com:8080/openam|urn:oasis:names:tc:SAML:2.0:nameid-format:persistent|ImmutableID|urn:federation:MicrosoftOnline|IDPRole|false

sun-fm-saml2-nameid-infokey: http://office365.example.com:8080/openam|urn:federation:MicrosoftOnline|ImmutableID

Where:

  • http://office365.example.com:8080/openam is the IdP entity provider.
  • urn:federation:MicrosoftOnline is the SP entity provider.
Note

These changes must be made directly in your directory server.

As of OpenAM 13.5, it is possible to configure federation with O365 without needing write access to your user store. This means you can configure federation where persistent NameID is required (urn:oasis:names:tc:SAML:2.0:nameid-format:persistent), without writing these user attributes to the user profile. You should ensure you use a linkage attribute that is visible to both AM/OpenAM and O365, such as uid or objectGUID. See OpenAM 13.5 Release Notes › Changes and Deprecated Functionality › Important Changes to Existing Functionality (SAML 2.0 NameID Persistence Extended) for further information.

Different user attributes / user store

If you use a different user store, for example AD, and/or you use attributes other than sun-fm-saml2-nameid-infokey and sun-fm-saml2-nameid-info for persistent federation, you must make the following changes:

  1. Ensure the attributes you want to use exist in the schema for the applicable user store.
  2. Add the attributes you want to use to the data store configuration: 
    • AM 6 and later console: navigate to: Realms > [Realm Name] > Data Stores > [Data Store Name] > User Configuration and add the attributes to the LDAP User Attributes list.
    • AM 5.x / OpenAM 13.x console: navigate to: Realms > [Realm Name] > Data Stores > [Data Store Name] and add the attributes to the LDAP User Attributes list.
    • Pre-OpenAM 13 console: navigate to: Access Control > [Realm Name] > Data Stores > [Data Store Name] and add the attributes to the LDAP User Attributes list.
  3. Specify the name of the attributes you are using for persistent federation:
    • AM / OpenAM 13.5 console: navigate to: Configure > Global Services > SAMLv2 Service Configuration and enter the names of the actual attributes being used in the Attribute name for Name ID information and Attribute name for Name ID information key fields. 
    • Pre-OpenAM 13.5 console: navigate to: Configuration > Global > SAMLv2 Service Configuration and enter the names of the actual attributes being used in the Attribute name for Name ID information and Attribute name for Name ID information key fields.
Caution

These changes are global, so will affect all federation setups.

Configuring AM/OpenAM

Caution

Before you start integrating, you must ensure that the same users exist in both O365 and AM/OpenAM for this federation to work.

This example process assumes the following:

  • You are using DS/OpenDJ for your user store.
  • The AM/OpenAM server (IdP) has the AM/OpenAM schema installed.
  • You are using the default sun-fm-saml2-nameid-infokey and sun-fm-saml2-nameid-info attributes.
  • The URL for the IdP is http://office365.example.com:8080/openam - this is also used as the name of the IdP entity provider.
  • The SP entity provider is called urn:federation:MicrosoftOnline (this is the default).

You can configure AM/OpenAM for integration with O365 as follows:

  1. Download the federationmetadata.xml file from O365 and prepare it for import. You do this by removing the content contained within the first set of <signature>...</signature> tags (and the tags themselves) as this section is not compliant and will cause the upload to fail if left in. 
  2. Log into the console for the IdP:
    • AM / OpenAM 13.x console: navigate to Realms > [Realm Name] > Common Tasks > Configure SAMLv2 Provider > Create Hosted Identity Provider, select a signing key to use and enter a name for the new circle of trust (COT), for example, O365.
    • Pre-OpenAM 13 console: navigate to Common Tasks > Create Hosted Identity Provider, select a signing key to use and enter a name for the new circle of trust (COT), for example, O365.
  3. Click the register a service provider link under the Register a Remote Service Provider section.
  4. Select the File option to indicate where the metadata resides and upload the modified federationmetadata.xml file. This should create the SP in the same COT;  your COT and entity providers setup should now look like this:

  1. Select the remote SP entity provider:
    • AM 6 and later console: navigate to: Realms > [Realm Name] > Applications > Federation > Entity Providers and click the name of the Remote SP entity provider
    • AM 5.x console: navigate to: Realms > [Realm Name] > Applications > SAML > Circle of Trust Configuration > Entity Providers and click the name of the Remote SP entity provider (urn:federation:MicrosoftOnline in this example).
    • Pre-AM 5 console: navigate to: Federation > Circle of Trust Configuration > Entity Providers and click the name of the Remote SP entity provider (urn:federation:MicrosoftOnline in this example).
  2. Click the Assertion Processing tab and add a new IDPEmail=mail value to the Attribute Map.
  3. Update your user entries to include the correctly populated sun-fm-saml2-nameid-infokey and sun-fm-saml2-nameid-info attributes. You can do this manually for a single user for testing purposes. For pre-populating all your other users, you could use the ssoadm do-bulk-federation command as detailed in SAML v2.0 Guide › Implementing SAML v2.0 Using the AM Console › Linking Federated Accounts in Bulk.
  4. Export the IdP metadata as described in How do I export and import SAML2 metadata in AM/OpenAM (All versions)? and give this to the O365 administrator so they can import it into the SP to complete the setup.

Testing federation

To test your federation setup, you can attempt to log in per the flow detailed in the Overview section at the start of this article: 

  1. Navigate to http://login.microsoftonline.com and enter your user name in the format username@example.com (no password is required at this stage).
  2. You should then be redirected to AM/OpenAM where you can log in with your AM/OpenAM credentials.
  3. If successful, you should then be logged into O365 automatically.

Troubleshooting

The following table shows some common errors you may see in the Federation debug log on the AM/OpenAM side and their meanings:

Error Meaning
<samlp:StatusMessage xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"> Creation of NameID is not allowed per AuthnRequest. </samlp:StatusMessage>

This means the user is not correctly pre-provisioned in AM/OpenAM.

You must pre-populate the sun-fm-saml2-nameid-infokey and sun-fm-saml2-nameid-info attributes (or equivalents) with the correct information. See the Key requirement (persistent NameID) section for further information.

ERROR: IDPSSOFederate.doSSOFederate: Unable to do sso or federation.com.sun.identity.saml2.common.SAML2Exception: Identity provider does not support name identifier format urn:oasis:names:tc:SAML:2.0:nameid-format:persistent.

This means the AM/OpenAM configuration has been changed to remove support for the urn:oasis:names:tc:SAML:2.0:nameid-format:persistent NameID format (it is supported by default). 

You need to ensure the AM/OpenAM instance being used as the IdP has urn:oasis:names:tc:SAML:2.0:nameid-format:persistent listed as a supported NameID format:

  • AM 5 and later console: navigate to Realms > [Realm Name] > Applications > SAML > Circle of Trust Configuration > Entity Providers > [IdP Name] > Assertion Content > NameID Format and add urn:oasis:names:tc:SAML:2.0:nameid-format:persistent to the NameID Format List.
  • Pre-AM 5 console: navigate to Federation > Circle of Trust Configuration > Entity Providers > [IdP Name] > Assertion Content > NameID Format and add urn:oasis:names:tc:SAML:2.0:nameid-format:persistent to the NameID Format List.

It is also worth exporting your metadata (standard and extended) to check if a configuration issue is contributing to your issues. You can export this as described in How do I export and import SAML2 metadata in AM/OpenAM (All versions)? Additionally, you should capture a SAML trace while reproducing the issue. You should follow this process:

  • Start a SAML trace in your browser. There are free third-party tools you can use, for example, in Firefox®, you can use SAML Tracer.
  • Reproduce the issue using your browser.
  • Stop the SAML trace.

On the O365 side, you can try using the Remote Connectivity Analyzer tool to troubleshoot any issues you are experiencing.

See Also

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

How do I export and import SAML2 metadata in AM/OpenAM (All versions)?

How do I create persistent SAML federation between two AM/OpenAM servers where user attributes match?

FAQ: SAML federation in AM/OpenAM

SAML Federation in AM/OpenAM

SAML v2.0 Guide

Office 365 SAML 2.0 Federation Implementers Guide

OpenAM as an identity provider for Office 365 (WSFed)

OpenAM / Office365 SSO

Related Training

N/A

Related Issue Tracker IDs

OPENAM-8578 (The default WS-Fed and SAML2 IDP attribute mapper should provide a way to Base64 binary encoding of NameID)

OPENAM-8580 (OpenAM should allow to use objectGUID value from AD when working with persistent NameID)

OPENAM-7428 (OpenAM IdP should support SOAP 1.2 when using the SAML ECP profile)

OPENAM-3470 (The SAML2 nameid should not be persisted if the nameid-format is not persistent)

OPENAM-3095 (When a SP sends an unsigned Authn Request using SAML ECP OpenAM sees it as a wrong message)



Copyright and TrademarksCopyright © 2018 ForgeRock, all rights reserved.

Recommended Books

Loading...