Integrating Office 365 with OIF/IdP Pre-Requisites

In the next two articles, I will describe how to integrate OIF (11.1.2.2.0 or later) as an IdP with Office 365 for Federation SSO using the SAML 2.0 protocol.

The integration will cover:

  • Browser Federation SSO integration: this is the flow the user will exercise when accessing the www.office365.com resources via a browser:
    • The www.office365.com will prompt the user to enter its email address
    • The server will detect that Federation SSO should be used for that domain and will start a Federation SSO flow the OIF/IdP
    • OIF/IdP will challenge the user, create a SAML Assertion and redirect the user to www.office365.com
    • www.office365.com will grant access to the user
  • ActiveSync mail integration: in this flow, the user will use a mail application configured for Office 365
    • When the mail application is started, it will send the user’s credentials (email address and IdP password) to Office 365
    • www.office365.com will make a direct connection over SSL to the IdP and will use the SAML 2.0 ECP protocol to send a SAML AuthnRequest and the user’s credentials via HTTP Basic Authentication
    • The OIF/IdP will validate those credentials and return a SAML Assertion via the ECP protocol
    • Office 365 will grant access to the mail application

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

  • Lync clients
  • OWA Mobile Apps

This article is based on:

  • The testing performed by Thomas Guo from Oracle and myself
  • The Microsoft article regarding SAML 2.0 support for Office 365 and more specifically the technical document listing steps required to configure Office 365 (user management and Federation trust establishment):

Overview


In order to integrate with Office 365 using the SAML 2.0 protocol, OAM/OIF 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 OIF SAML 2.0 Metadata when establishing Federation Trust.

Office 365 expects that all SAML messages will be signed using the SHA-1 digest algorithm. As such, OIF/IdP must be configured to use SHA-1, otherwise Office 365 SP will return 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 OIF will need to be configured to include it in all outgoing signed message for Office 365.

If HTTP Basic Authentication will be used at the IdP (as it is required for the ActiveSync mail integration), the WebLogic domain where OAM/OIF are 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:

  • The Office 365 SP SAML 2.0 Metadata.
  • Since Office 365 does not support yet SAML 2.0 Metadata consumption, the following information must be collected:
    • The OIF IdP signing certificate in Base64 encoded format
    • The OIF IdP Issuer value
    • The OIF IdP SSO and Logout URLs

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

  • For a given user, both Office 365 and the directory used by OAM/OIF must have an account for that user
  • The user global unique ID (or ImmutableId) and the email address (or UserPrincipalName) used in the Office 365 account must be set in the user account at OAM/OIF
  • For the ActiveSync mail integration, the identifier in the email address (or UserPrincipalName) used by Office 365 must be the username used for HTTP Basic Authentication at OAM/OIF

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 will attempt to make a direct connection to the OAM/OIF server for the ActiveSync use case.

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

  • If a load balancer is fronting OAM/OIF, SSL/HTTPS can be enabled/configured on the load balancer
  • If OHS is fronting OAM/OIF, OHS will be configured for SSL
  • If no component is fronting OAM/OIF, then the WLS server where OAM is running can be configured for SSL/HTTPS

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:

  • Go to the OAM Administration Console: http(s)://oam-admin-host:oam-admin-port/oamconsole
  • Navigate to Configuration -> Access Manager Settings
  • Set the OAM Server Host to the hostname of the public endpoint
  • Set the OAM Server Post to the SSL port of the public endpoint
  • Set the OAM Server Protocol to https
  • Apply

Note: after making those changes, retrieving the OIF SAML 2.0 Metadata will contain the new https URLs

HTTP Basic Authentication


By default, if a browser sends HTTP Basic Authentication credentials to OAM, the WLS server will attempt 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 will result 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:

  • Enter the WLST environment by executing:
    $IAM_ORACLE_HOME/common/bin/wlst.sh
  • Connect to the WLS Admin server:
    connect()
  • Start an edit session:
    edit()
    startEdit()
  • Navigate to the SecurityConfiguration node:
    cd('SecurityConfiguration')
  • Navigate to the domain (replace DOMAIN_NAME with the name of the WLS domain where OAM is installed):
    cd('DOMAIN_NAME') 
  • Set the EnforceValidBasicAuthCredentials setting to false to disable tomatic validation of HTTP Basic Authentication credentials sent to unsecured applications:
    set('EnforceValidBasicAuthCredentials','false')
  • Save and activate the changes:
    save()
    activate()
  • 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:

  • Open a browser
  • Go to the Azure / Office 365 Metadata publishing service:
    https://nexus.microsoftonline-p.com/federationmetadata/saml20/federationmetadata.xml
  • Save the Metadata locally using the Save As button in the browser

The OIF 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 OIF IdP Signing Certificate, perform the following operations to determine which keyID entry is used to sign outgoing SAML messages:

  • Go to the OAM Administration Console: http(s)://oam-admin-host:oam-admin-port/oamconsole
  • Navigate to Configuration  -> Federation Settings
  • Note the keyID of the Signing Key for SAML signature operations, in the Signing Key field

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

  • Open a browser
  • Go to the following URL (replace KEYENTRY_ID by the keyID name retrieved in the previous step):
    http://oam-runtime-host:oam-runtime-port/oamfed/idp/cert?id=<KEYENTRY_ID>
  • Save the certificate in a text file.
  • Open the file with your favorite text editor
  • The content of the file will look like:
    -----BEGIN CERTIFICATE-----
    MIIB+DCCAWGgAwIBAgIBCjANBgkqhkiG9w0BAQQFADAhMR8wHQYDVQQDExZhZGMw
    MHBjYy51cy5vcmFjbGUuY29tMB4XDTE0MDMwNDE5MjAzMloXDTI0MDMwMTE5MjAz
    MlowITEfMB0GA1UEAxMWYWRjMDBwY2MudXMub3JhY2xlLmNvbTCBnzANBgkqhkiG
    9w0BAQEFAAOBjQAwgYkCgYEAkQOdZCmoOQRuxSvI/74bjnUPq7u7qiGbmaN1D5TB
    JaM+j5XRixEUI3pidaxlbykaraqVBMJpXJ6ua0QWectv6SdzuqcvH8C5el06NxTs
    fB6pcvxHGXVAbAvtGr2tOPSL+5HaFQoATpiY3HugTnJfjmHRfOqIo8nUMek6zCtv
    rKUCAwEAAaNAMD4wDAYDVR0TAQH/BAIwADAPBgNVHQ8BAf8EBQMDB9gAMB0GA1Ud
    DgQWBBQ/7yJbGCbbAnaLEi4ReLwLlvSxJTANBgkqhkiG9w0BAQQFAAOBgQBrMb2i
    6zcChhVM7a9VVgBr8xljBsPxVWCAYNUYaoyUj9VkD4CpFF9hVX0CpceoSBTiyMQp
    3sg0FAYz1PGfjrq7uFEq9iTCwa5J/7k/VSOLKd3IDqzz7w0ZERksgp3OOqOct/wB
    /wQplaoMZLcRoInVUbGTBDMfqmW5iZ/wjpzItg==
    -----END CERTIFICATE-----
  • 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):
    MIIB+DCCAWGgAwIBAgIBCjANBg....InVUbGTBDMfqmW5iZ/wjpzItg==
  • Save the file. This line will be provided as an input to the Windows Powershell command.

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

  • Go to the OAM Administration Console: http(s)://oam-admin-host:oam-admin-port/oamconsole
  • Navigate to Configuration  -> Federation Settings
  • Note the OIF Issuer/Provider ID value in the Provider Id field

The OIF IdP SSO and Logout URLs are (note: be sure to have the public endpoints, which are the URLs that the end-user will use):

  • Browser SSO URL: http(s)://oam-public-host:oam-public-port/oamfed/idp/samlv20
  • ECP SSO URL: http(s)://oam-public-host:oam-public-port/oamfed/idp/soap
  • Logout URL: http(s)://oam-public-host:oam-public-port/oamfed/idp/samlv20

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

  • Open a browser
  • Go to http(s)://oam-public-host:oam-public-port/oamfed/idp/metadata
  • 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:HTTP-Redirect" Location="https://acme.com/oamfed/idp/samlv20"/>
        ...
      </md:IDPSSODescriptor>
      ...
    </md:EntityDescriptor>
  • The ECP 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:SOAP:
    <md:EntityDescriptor ...>
      ...
      <md:IDPSSODescriptor ...>
        ...
        <md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:SOAP" Location="https://acme.com/oamfed/idp/soap"/>
        ...
      </md:IDPSSODescriptor>
      ...
    </md:EntityDescriptor>
  • The Logout URL will be the Location attribute of the XML Element EntityDescriptor -> IDPSSODescriptor -> SingleLogoutService for which the Binding attribute is set to urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect:
    <md:EntityDescriptor ...>  ...
      <md:IDPSSODescriptor ...>
        ...
        <md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://acme.com/oamfed/idp/samlv20" ResponseLocation="https://acme.com/oamfed/idp/samlv20"/>
        ...
      </md:IDPSSODescriptor>
      ...
    </md:EntityDescriptor>

SHA-256 vs SHA-1


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

OIF’s Signing Certificate in Signed Messages


After having setting up Federation between OIF and Office 365, you will need to configure OIF so that the Federation server will include 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/OIF directory must be synchronized to support the various Federation flows (Browser SSO and ActiveSync):

  • For a given user, both Office 365 and the directory used by OAM/OIF must have an account for that user
  • The user global unique ID (or ImmutableId) and the email address (or UserPrincipalName) used in the Office 365 account must be set in the user account at OAM/OIF
  • For the ActiveSync mail integration, the userID (or ImmutableId) used by Office 365 must be the username used for HTTP Basic Authentication at OAM/OIF:
    • The identifier in the email address (or UserPrincipalName) is the part of the email address before the ‘@’ character. For example if the UserPrincipalName is alice.appleton@acme.com, then the identifier would be alice.appleton
    • That identifier will be the HTTP Basic Authentication username. For example alice.appleton
    • The User ID Attribute used in the OAM Identity Store configuration for the OAM HTTP Basic Authentication Scheme must match the incoming HTTP HTTP Basic Authentication username. For example the User ID Attribute used in the OAM Identity Store for user alice must be alice.appleton.

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

  • A random unique identifier (like 2848cfc7f6914af2a550c024bcbf0c6e)
  • Or a username that will be deemed unique: no other user will have the same username even if the original user has been deleted from the system.

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 identifier@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:

  • The Office 365 mail server will make a direct connection over SSL to the IdP and will use the SAML 2.0 ECP protocol to send a SAML AuthnRequest and the user’s credentials via HTTP Basic Authentication
  • The OIF/IdP will validate those credentials and return a SAML Assertion via the ECP protocol
  • Office 365 will grant access to the mail application

In such a flow, the user will:

  • Provide its email address to Office 365 (alice.appleton@acme.com for example)
  • Office 365 will use the identifier before the ‘@’ character as the HTTP Basic Authentication username (alice.appleton for example)
  • IdP will need to be able to validate the credentials with the username being the identifier in the email address (alice.appleton for example)

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


In the next article, I will configure Office 365 and OIF/IdP and perform some tests.
Cheers,
Damien Carru

Comments:

Why must it be SHA-1? Will it really not work with SHA-256?

Posted by Linnea on May 09, 2014 at 12:15 PM EDT #

Office 365 requires the use of SHA-1

Posted by Damien on May 09, 2014 at 12:34 PM EDT #

Hi Damien.
thanks for the post...what this line exactly means "Since Office 365 does not support yet SAML 2.0 consumption, the following information must be collected"

Confusion is as I can see the MS blog "Announcing support for SAML 2.0 federation with Office 365"

Posted by guest on September 17, 2014 at 03:42 AM EDT #

Thanks for the catch: I meant to say "Since Office 365 does not support yet SAML 2.0 ***Metadata*** consumption, the following information must be collected"

I updated the entry with the correction.

Damien

Posted by Damien on September 17, 2014 at 11:21 AM EDT #

Post a Comment:
  • HTML Syntax: NOT allowed
About

Damien Carru is a member of the Oracle Identity Management organization, focusing on Federation and SSO. This blog will cover Federation use cases involving Oracle Access Manager, Oracle Identity Federation and Oracle Security Token Service

Search

Categories
Archives
« March 2015
SunMonTueWedThuFriSat
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
    
       
Today