This document shows a step-by-step recipe on how to properly configure OpenAM to Single Sign on to O365 via SAML 2.0. OpenAM will be the IDP and O365 will be the SP. Note this procedure assumes that you have OpenAM 11.x installed and that you know how federation works and understand the core concepts of SAML 2.0. Furthermore it is assumed that you as O365 admin have already created the users. Similarly the OpenAM Admin should already have created the corresponding users in OpenAM. This means is that the users have to be pre-provisioned on both ends for this federation to work. This is a key pre-requisite.
Note that for this exercise a new realm called “O365” is added, which will be explicitly called as a query parameter to the OpenAM login servlet. If your goal is to provide O365 integration with all realms then you can implement the configuration at the root level realm and hence would not need to provide the realm name as a query parameter. It is good to understand the login flow as it will make the configuration and if needed troubleshooting easier.
The user types in the URL http://login.microsoftonline.com in their browser.
In the login form, you enter your login name which will be something like "email@example.com". You don't need to enter the password as the password is only required at the IDP.
Note @demo.example.com will indicate to O365 that this is a federated login, and in particular case we are dong SP Initiated SSO.
O365 internally looks up this user and the associated SAML metadata and then enters into SAML flow by redirecting to the registered IDP (OpenAM) with a SAML AuthN request.
The redirection takes you to OpenAM login screen, where you enter your OpenAM (IDP) credentials.
If everything goes well, OpenAM will send a SAML Response to the registered endpoint of the SP (O365). This response will contain the require name identifier as well as an attribute called IDPEmail which will be 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 Single Sign On.
In the whole flow above the user experience is not a complicated. The user will first see the O365 login page and then the OpenAM login page and then logs into O365.
The ingredients for this recipe are as follows:
Create hosted IDP using OpenAM's Wizard
Log into the console as "amadmin". On the dashboard under the "Common Tasks" tab
- Click on "Create Hosted Identity Provider"
- Choose the Realm from the drop down which in this case is /O365
- Choose the "Signing Key" which in this case is the OOTB self signed "test"
- Create a new Circle of Trust called "MSO365"
Register Remote SP
Import the SP (O365) metadata file.
- Use wget or your browser to download the federationmetadata.xml file. Ideally this file can be imported into an Identity Provider as is. However OpenAM does not like the initial <signature> tag so edit this file and remove everything within the first <signature>...</signature> tags including the tags themselves.
- Log into the console as "amadmin". On the dashboard under the "Common Tasks" click on "Register Remote Service Provider" and then complete the wizard to import the modified federationmetadata.xml file. Ensure that the SP is part of the "MSO365" circle of trust. This step completes the federation setup on OpenAM.
Provide Attribute Mapping
- When the SAML assertion is sent back to O365, we need to provide O365 with an attribute called "IDPEmail" which will essentially be used as the "foreign key" to map the OpenAM user to the O365 user. This is done by defining an "Attribute Mapper" map "IDPEmail=mail" on the SP settings.
- As emphasized in the Introduction, the federated user in OpenAM has to be pre-provisioned i.e. Auto-Federation will not work. This is because O365 requires a "persistent" nameid. An example of a typical user entry that is provisioned correctly to work O365 is pasted on the right column. The two attributes that OpenAM hold persistence information is "sun-fm-saml2-nameid-info" and "sun-fm-saml2-nameid-infokey". Key things to note is the entityID for the IDP which in this example is "http://am.demo.openrock.org:8080/openam" and the entityID for the SP which is "urn:federation:MicrosoftOnline".
- Also note the value of the "mail" attribute which will be sent in the SAML assertion to the SP (O365) as an attribute statement. See the SAML request/response at the very end.
$ opendj/bin/ldapsearch -p 8089 -D "cn=directory manager" -w password -b "dc=example,dc=com" uid=wahmed
cn: Wajih Ahmed
Export the IDP Metadata
This will be required for the configuration in the next section.
- After creating the IDP in OpenAM as outlined in the steps above, export its metadata using the exportmetadata.jsp. Note how the "realm" (if any) and "entityid" are used in the query parameters.
- Ideally this exported metadata can be imported into any Service Provider. However in this case this file is used as a reference and used to copy the "endpoints" and "certificate" and then feed them to a powershell script.
- First thing you want to do is to download and read the "Office 365 SAML 2.0 Federation Implementer's Guide". For brevity this will be called the "Guide" in this section.
- The key things to note is that you will need to use powershell from any AD machine which has the Azure AD Module for powershell installed.
|Office 365 SAML 2.0 Federation Implementer’s Guide|
Install the Azure AD Module
- As stated earlier you should have the Azure AD Module installed. See the ingredients section above for the link to the module. This module requires that the Microsoft Service Sign-in Assistant installed first. Once you have downloaded and installed both components you will get a link on your desktop to launch the powershell.
- Once this module is properly installed you will use the steps outlined in the Guide to connect and configure O365 to work with the IDP (OpenAM). For convenience the steps are outline in the next few rows as the Guide is not comprehensive.
Add your Domain to O365
- Note this is not the same as the default domain which cannot be enabled for SSO.
- You need to add a new domain which essentially represents your O365 service and will be used by your company to single sign on to O365. In my case i chose "demo.openrock.org" because i own the openrock.org domain.
- During adding the new domain you need to verify that you actually own the domain. You do so by adding a new TXT or MX record for the domain to your DNS with a special value provided by O365.
- I got this value on the "Confirm Ownership of your domain", by choosing the "General Instructions" and copying the "Destination or Point to Address" column. In my case it was "MS=ms65748521".
- Since i was using EC2 i created a DNS TXT recorded in Route 53 with the above value.
- Finally ensure that the new domains appears under the "Domains" section of O365 settings.
Create Service Provider in O365 (Step 1)
- Use "Connect-MsolService" command from the powershell to establish trust between OpenAM and O365 and subsequently create federated users. Refer to Page 7 of the Guide.
- Notice use the O365 Administrative (default) account to log in.
Create Service Provider in O365 (Step 2)
- Create a powershell script called openam.ps1 and then run it from the above powershell window in which you have already logged in using Connect-MsolService. Alternatively you can uncomment the "Connect-MsolService" line and then right click on the script to edit and run in Microsoft Powershell ISE.
- Note in order to run the powershell script i had to run "Set-ExecutionPolicy RemoteSigned" in the powershell window.
$dom = "demo.example.com"
$url = "https://am.example.com:8443/openam/SSOPOST/metaAlias/demo/idp"
$entity = "http://am.example.com:8080/openam"
$logout = "https://am.example.com:8443/openam/IDPSloRedirect/metaAlias/demo/idp"
$cert = ".......Y0Q=="
Set-MsolDomainAuthentication -DomainName $dom -FederationBrandName
$dom -Authentication Federated -PassiveLogOnUri
$url -SigningCertificate $cert -IssuerUri $entity -ActiveLogOnUri
$ecp -LogOffUri $logout -PreferredAuthenticationProtocol SAMLP
Check Service Provider in O365
- After running this script successfully run "Get-MsolDomainFederationSettings" command to ensure changes have been saved.
ActiveLogOnUri : https://am.demo.openrock.org:8443/openam/SSOSoap/metaAlias/idp
FederationBrandName : wfoo.net
IssuerUri : http://am.demo.openrock.org:8080/openam
LogOffUri : https://am.demo.openrock.org:8443/openam/IDPSloRedirect/metaAlias/idp
PassiveLogOnUri : https://am.demo.openrock.org:8443/openam/SSOPOST/metaAlias/idp
SigningCertificate : MII......W0Y0Q==
Create corresponding user in O365
- This done by running the "new-msoluser" cmdlet (in MS terminology). Once it is run check the console to see if the user exists and if needed assign a license to it. If you don't assign a license then you will not be able to log in.
new-msoluser -DisplayName Wajih -UserPrincipalName firstname.lastname@example.org -UsageLocation NO -BlockCredential $false -ImmutableId wahmed
Testing and Troubleshooting