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:
- 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: email@example.com, where the @example.com part tells O365 that this is a federated login.
- 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.
- The user enters their AM/OpenAM credentials.
- 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.
- 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)
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
- http://office365.example.com:8080/openam is the IdP entity provider.
- urn:federation:MicrosoftOnline is the SP entity provider.
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 › 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:
- Ensure the attributes you want to use exist in the schema for the applicable user store.
- 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.
- Pre-AM 6 console: navigate to: Realms > [Realm Name] > Data Stores > [Data Store Name] and add the attributes to the LDAP User Attributes list.
- 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.
- OpenAM 13 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.
These changes are global, so will affect all federation setups.
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:
- 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.
- Create a new circle of trust (COT) with the entity providers:
AM 7 and later:
- Navigate to Realms > [Realm Name] > Applications > Federation > Circles of Trust, click Add Circle of Trust and enter a name for the new COT, for example, O365.
- Navigate to Realms > [Realm Name] > Applications > Federation > Entity Providers, click Add Entity Provider, select Hosted and enter the required details including the new COT.
- Update any other details necessary for the IdP such as Signing and Encryption details.
- Navigate to Realms > [Realm Name] > Applications > Federation > Entity Providers, click Add Entity Provider, select Remote, upload the modified federationmetadata.xml file and select the new COT.
- Log into the console for the IdP by navigating 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.
- 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.
- AM 7 and later:
Your COT and entity providers setup should now look like this:
- 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).
- OpenAM 13.x 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).
- Click the Assertion Processing tab and add a new IDPEmail=mail value to the Attribute Map.
- 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 › Linking Identities in Bulk.
- 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.
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:
- Navigate to http://login.microsoftonline.com and enter your user name in the format firstname.lastname@example.org (no password is required at this stage).
- You should then be redirected to AM/OpenAM where you can log in with your AM/OpenAM credentials.
- If successful, you should then be logged into O365 automatically.
The following table shows some common errors you may see in the Federation debug log on the AM/OpenAM side and their meanings:
<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.
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:
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.