Integrating Office 365 with OAM and Id Pre-Requisites

This article shows how to integrate OAM (11.1.2.2.0 or later) as an IdP with Office 365 for Federation SSO using the SAML 2.0 protocol.

The integration covers:

It is important to note that integration with Office 365 for non SAML 2.0 components will not work, such as:

This article is based on

Overview

In order to integrate with Office 365 using the SAML 2.0 protocol, OAM must be configured to use HTTPS/SSL as their endpoints with SSL certificates issued by well known CAs (if ActiveSync mail integration is required). Failure to do so might result in Office 365 not accepting the OAM SAML 2.0 Metadata when establishing Federation Trust.

Office 365 expects that all SAML messages is signed using the SHA-1 digest algorithm. As such, IdP must be configured to use SHA-1, otherwise Office 365 SP returns an error if SHA-256 is used. Also, Office 365 requires the IdP’s signing certificate to be included in the signed SAML Assertion; So OAM needs to be configured to include it in all outgoing signed message for Office 365.

If HTTP Basic Authentication is used at the IdP (as it is required for the ActiveSync mail integration), the WebLogic domain where OAM is running needs to be configured to not validate the HTTP Basic Authentication for unsecured resources.

In order to establish trust between the two Federation servers, the following data must be retrieved:

Finally in order to be able to establish Federation trust, the following needs to occur:

Enabling SSL

Important note: The SSL certificate used to enable SSL for OAM must have been issued by well known CAs, since the Office 365 server attempts to make a direct connection to the OAM server for the ActiveSync use case.

There are several ways to enable SSL on the public endpoints for OAM:

Once the component (Load balancer, OHS or WLS) has been configured for SSL, the OAM configuration needs to be updated to reference the new endpoint as its public URL:

  1. Go to the OAM Administration Console: http(s)://oam-admin- host:oam-admin-port/oamconsole

  2. Navigate to Configuration , Access Manager Settings

  3. Set the OAM Server Host to the hostname of the public endpoint

  4. Set the OAM Server Post to the SSL port of the public endpoint

  5. Set the OAM Server Protocol to https

  6. Click Apply

Description of the illustration Access_Manager_Settings.jpg

Note: After making those changes, retrieving the OAM SAML 2.0 Metadata contains the new https URLs

HTTP Basic Authentication

By default, if a browser sends HTTP Basic Authentication credentials to OAM, the WLS server attempts to validate those before letting OAM process the request: this can result in authentication failures, particularly if the WLS domain was not configured with WLS LDAP Authenticators for each Identity Store created in OAM.

Note: Even if the WLS domain was configured correctly to have a WLS LDAP Authenticator for each Identity Store created in OAM, this results in two authentication operations, one by WLS, and the other one required by OAM to create an OAM session.

It is possible to disable the automatic validation of HTTP Basic Authentication credentials sent to unsecured applications in the WLS domain where OAM is running. See section “Understanding BASIC Authentication with Unsecured Resources” of the Oracle Fusion Middleware Programming Security for Oracle WebLogic Server guide for more information.

To disable the automatic validation of HTTP Basic Authentication credentials sent to unsecured applications in the WLS domain, execute the following steps:

  1. Enter the WLST environment by executing: $IAM_ORACLE_HOME/common/bin/wlst.sh

  2. Connect to the WLS Admin server: connect()

  3. Start an edit session:

    edit()

    startEdit()

  4. Navigate to the SecurityConfiguration node: cd('SecurityConfiguration')

  5. Navigate to the domain (replace DOMAIN_NAME with the name of the WLS domain where OAM is installed): cd('DOMAIN_NAME')

  6. Set the EnforceValidBasicAuthCredentials setting to false to disable automatic validation of HTTP Basic Authentication credentials sent to unsecured applications: set('EnforceValidBasicAuthCredentials','false')

  7. Save and activate the changes:

    save()

    activate()

  8. Restart the servers in the WLS domain for the changes to take effect

SAML 2.0 Metadata, Certificate and Issuer

To download the SAML 2.0 Metadata from the Office 365 SP server:

  1. Open a browser

  2. Go to the Azure / Office 365 Metadata publishing service: https://nexus.microsoftonline-p.com/federationmetadata/saml20/federationmetadata.xml

  3. Save the Metadata locally using the Save As button in the browser

The OAM IdP Signing Certificate must be provided as a Base64 encoded string to the Windows Powershell commands, as a single string with no spaces/line-breaks. To retrieve the OAM IdP Signing Certificate, perform the following operations to determine which keyID entry is used to sign outgoing SAML messages:

  1. Go to the OAM Administration Console: http(s)://oam-adminhost:oam-admin-port/oamconsole

  2. Navigate to Configuration , Federation Settings

  3. Note the keyID of the Signing Key for SAML signature operations, in the Signing Key field

Description of the illustration Federation_Settings.jpg

Perform the following steps to retrieve the certificate for that keyID entry:

  1. Open a browser

  2. Go to the following URL (replace KEYENTRY_ID by the keyID name retrieved in the previous step):

    3. http://oam-runtime-host:oam-runtime-port/oamfed/idp/cert?id=<KEYENTRY_ID>

  3. Save the certificate in a text file.

  4. Open the file with your favorite text editor

  5. The content of the file looks like:

    -----BEGIN CERTIFICATE-----
	MIIB+DCCAWGgAwIBAgIBCjANBgkqhkiG9w0BAQQFADAhMR8wHQYDVQQDExZhZGMMHBjYy51cy5vcmFjbGUuY29tMB4XDTE0MDMwNDE5MjAzMloXDTI0MDMwMTE5MjAzMlowITEfMB0GA1UEAxMWYWRjMDBwY2MudXMub3JhY2xlLmNvbTCBnzANBgkqhkiG9w0BAQEFAAOBjQAwgYkCgYEAkQOdZCmoOQRuxSvI/74bjnUPq7u7qiGbmaN1D5TB JaM+j5XRixEUI3pidaxlbykaraqVBMJpXJ6ua0QWectv6SdzuqcvH8C5el06NxTs fB6pcvxHGXVAbAvtGr2tOPSL+5HaFQoATpiY3HugTnJfjmHRfOqIo8nUMek6zCtv rKUCAwEAAaNAMD4wDAYDVR0TAQH/BAIwADAPBgNVHQ8BAf8EBQMDB9gAMB0GA DgQWBBQ/7yJbGCbbAnaLEi4ReLwLlvSxJTANBgkqhkiG9w0BAQQFAAOBgQBrMb2i6zcChhVM7a9VVgBr8xljBsPxVWCAYNUYaoyUj9VkD4CpFF9hVX0CpceoSBTiyMQp 3sg0FAYz1PGfjrq7uFEq9iTCwa5J/7k/VSOLKd3IDqzz7w0ZERksgp3OOqOct/wB/wQplaoMZLcRoInVUbGTBDMfqmW5iZ/wjpzItg==
—–END CERTIFICATE—–

  6. Remove the first line (-----BEGIN CERTIFICATE-----), remove the last line (-----END CERTIFICATE-----), and modify the rest of the file to remove the line breaks. The result should be a single line file (the content was shortened):

    7. MIIB+DCCAWGgAwIBAgIBCjANBg....InVUbGTBDMfqmW5iZ/wjpzItg==

  7. Save the file. This line is provided as an input to the Windows Powershell command.

Perform the following steps to retrieve the IdP’s Issuer / Provider ID:

  1. Go to the OAM Administration Console: http(s)://oam-admin-host:oam-admin-port/oamconsole

  2. Navigate to Configuration , Federation Settings

  3. Note the OAM Issuer/Provider ID value in the Provider Id field

Description of the illustration Retrieve_IDP.jpg

The OAM IdP SSO and Logout URLs are (Note: Be sure to have the public endpoints, which are the URLs that the end-user uses):

If you have any doubts, you can retrieve those URLs from the IdP metadata:

  1. Open a browser

  2. Go to http(s)://oam-public-host:oam-public-port/oamfed/idp/metadata

  3. The Browser SSO URL will be the Location attribute of the XML

    
	 Element EntityDescriptor , IDPSSODescriptor , SingleSignOnService for which the Binding attribute is set to urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect:
           <md:EntityDescriptor ...>
				...
				<md:IDPSSODescriptor ...>
					...
					<md:SingleSignOnService>
						Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTPRedirect" Location="https://acme.com/oamfed/idp/samlv20"/>
					...
				</md:IDPSSODescriptor>
				...
			</md:EntityDescriptor>

SHA-256 vs SHA-1

After having setting up Federation between OAM and Office 365, you must configure OAM to use SHA-1 for signatures for the Office 365 SP partner.

OAM’s Signing Certificate in Signe Messages

After having setting up Federation between OAM and Office 365, you must configure OAM so that the Federation server includes its X.509 signing certificate in all outgoing signed SAML messages for the Office 365 SP partner.

User Account

The user accounts in Office 365 and in the OAM directory must be synchronized to support the various Federation flows (Browser SSO and ActiveSync):

ImmutableId

The ImmutableId is an attribute used by Office 365 to uniquely reference a user. Even if the user record is to be deleted later on, no other user created subsequently should be able to have the same ImmutableId value.

An ImmutableId is typically

UserPrincipalName

The UserPrincipalName (or UPN) is an identifier that has the format of an email address. The domain name of the email address needs to map to the name used in the Office 365 domain.

For example, if Office 365 was configured for the acme.com domain for Federation SSO, then all users with an email address similar to identiSer@acme.com will be able to do Federation SSO with the IdP configured for that Office 365 domain.

ActiveSync Requirements

In an ActiveSync mail flow:

In such a flow, the user will:

Username Requirements

Based on the above, the requirements for the user authentication at the IdP are:

Browser

Authentication Username

 HTTP Basic Auth Username at IdP
Browser based Federation SSO Anything N/A

Browser based Federation SSO

+

ActiveSync ECP

 Anything Identifier in the email address

More Learning Resources

Explore other labs on docs.oracle.com/learn or access more free learning content on the Oracle Learning YouTube channel. Additionally, visit education.oracle.com/learning-explorer to become an Oracle Learning Explorer.

For product documentation, visit Oracle Help Center.