This is a continuation of my previous article where I will configure OIF (11.1.2.2.0 or later) as an IdP with Office 365 for Federation SSO using the SAML 2.0 protocol.

Be sure to have read the article about pre-requisites.

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):
• Microsoft Blog
  
• Technical document describing how to configure Office 365

Testing Environment

For this test integration, I will use the following approach:

• User alice at OAM/OIF:
• Username (uid attribute): alice.appleton
• Email address (mail attribute): alice.appleton@acme.com
• First name (givenname attribute): Alice
• Last name (sn attribute): Appleton
• User alice at Office 365 (see the Microsoft technical document on more information on how to create a user in Azure AD):
• UserPrincipalName: alice.appleton@acme.com
• ImmutableId: alice.appleton
• DisplayName: Alice Appleton
• FirstName: Alice
• LastName: Appleton
• UsageLocation: US
• Federation agreement:
• SAML 2.0 NameID format: urn:oasis:names:tc:SAML:2.0:nameid-format:persistent
• LDAP attribute used to populate SAML 2.0 NameID value: uid (because the NameID must match the ImmutableId)
• SAML Attribute contained in the SAML Assertion
• Name: IDPEmail
• LDAP Attribute used to populate this attribute value: mail (because the attribute value must match the UserPrincipalName)
• Office 365 specifics:
• The domain name will be acme.com
• The protocol used will be SAMLP
• ActiveSync mail application will be supported OIF Configuration

Setting up Office 365 as an SP in OIF/IdP will consist in:

• Creating an SP Attribute Profile in order to send the IDPEmail attribute containing the mail attribute
• Creating an SP partner for Office 365 and bind it to the new SP Attribute Profile
• Updating the Office 365 SP Partner configuration for
• SHA-1 hashing algorithm in signatures
• Inclusion of OIF’s signing certificate in outgoing SAML messages
• HTTP Basic Auth for ActiveSync mail integration

Office 365 Configuration

Please refer to the following Microsoft information when reading this section:

• Microsoft  Blog
  
• Technical document describing how to configure Office 365
  

Windows Powershell

Ensure that the Windows Powershell tools are installed on the computer from which you will connect to Office 365 for administration purposes.

Provisioning OIF/IdP as a Partner in Office 365

Top create OIF as an IdP partner for the acme.com domain in Office 365, perform the following steps:

• Connect to Office 365 as the administrator for acme.com
  Connect-MsolService
• Set the following environment variables (the data used is the one retrieved from the pre-requisites section; note that the string for $idpSigningCert is on the same line as the $idpSigningCert =, and that it is a single line):
• $domainName = "acme.com"
• $BrandName - "ACME IdP"
• $browserSSOLoginURL = "https://acme.com/oamfed/idp/samlv20"
• $ecpSSOURL = "https://acme.com/oamfed/idp/soap"
• $logoutURL = "https://acme.com/oamfed/idp/samlv20"
• $issuerProviderID = "https://acme.com/oam/fed"
• $idpSigningCert = "MIIB+DCCAWGgAwIBAgIBCjANB......oInVUbGTBDMfqmW5iZ/wjpzItg=="
• $ssoProtocol = "SAMLP"
• Execute the following command using the above variables:
  Set-MsolDomainAuthentication -DomainName $domainName -FederationBrandName $BrandName -Authentication Federated -PassiveLogOnUri $browserSSOLoginURL -ActiveLogOnUri $ecpSSOURL -SigningCertificate $idpSigningCert -IssuerUri $issuerProviderID -LogOffUri $logoutURL -PreferredAuthenticationProtocol $ssoProtocol

OIF Configuration

SP Attribute Profile

To create a new SP Attribute Profile that will be set up to send the SAML IDPEmail Attribute containing the user’s UPN value, perform the following operations:

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

• Navigate to Identity Federation -> Identity Provider Administration
• Click on the “Service Provider Attribute Profiles” tab
• Click on the “Create SP Attribute Profile” button
• Enter a name for the new profile (for example Office365-attr-profile)
• In the Attribute Mapping section, click Add
• Enter the following information:
• Message Attribute Name: IDPEmail
• Value: enter the LDAP user attribute containing the user’s UPN in the directory used by OAM (in this example: user -> attr -> mail)
• Always send: checked
• Click OK

The Attribute Profile will be shown:

• Click Save

Office 365 SP Partner

To add Office 365 as an SP partner in OIF, execute the following steps:

• Go to the OAM Administration Console: http(s)://oam-admin-host:oam-admin-port/oamconsole
• Navigate to Identity Federation -> Identity Provider Administration
• Click on the “Create Service Provider Partner” button
• In the Create screen:
• Enter a name for the partner (for example Office365)
• Select SAML 2.0 as the Protocol
• Click Load Metadata and upload the SAML 2.0 Metadata file for the Office 365
• Select Persistent as the NameID format
• Enter the LDAP user attribute that contains the user’s ImmutableId value (in this example, uid)
• Select the SP Attribute Profile that was previously created (in this example Office365-attr-profile)
• Click Save

SHA-1 Hash Algorithm for Digital Signatures

To configure OIF to use SHA-1 for signatures for the Office 365 SP partner, execute the following steps:

• Enter the WLST environment by executing:
  $IAM_ORACLE_HOME/common/bin/wlst.sh
• Connect to the WLS Admin server:
  connect()
• Navigate to the Domain Runtime branch:
  domainRuntime()
• Execute the configureFedDigitalSignature() command:
  configureFedDigitalSignature(partner="PARTNER_NAME", partnerType="sp", algorithm="SHA-256/SHA-1")
• Replace PARTNER_NAME with the name of the added partner
• An example would be:
  configureFedDigitalSignature(partner="Office365", partnerType="sp”, algorithm="SHA-1")
• Exit the WLST environment:
  exit()

OIF’s Signing Certificate in XML Digital Signatures

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, execute the following steps:

• Enter the WLST environment by executing:
  $IAM_ORACLE_HOME/common/bin/wlst.sh
• Connect to the WLS Admin server:
  connect()
• Navigate to the Domain Runtime branch:
  domainRuntime()
• Execute the updatePartnerProperty() command:
  updatePartnerProperty("PARTNER_NAME", "sp", "includecertinsignature", "true", "boolean")
• Replace PARTNER_NAME with the name of the added partner
• An example would be:
  updatePartnerProperty("Office365", "sp", "includecertinsignature", "true", "boolean")
• Exit the WLST environment:
  exit()

HTTP Basic Auth for ActiveSync Mail Integration

In the SAML 2.0 ECP flow, the Office 365 server will make a direct connection to OIF/IdP over SOAP over HTTPS and will post a SAML AuthnRequest message. Alongside the SOAP request, the HTTP request will contain the user’s credentials as part of the HTTP Basic Authentication headers.

OIF/IdP must be configured to use an OAM HTTP Basic Authentication scheme to validate those credentials. Also this operation must not result in an OAM session to be created, since this is rather a credential validation operation initiated by the Office 365 server, and not the user involved with OAM/OIF. For those reasons, OIF/IdP must be configured to use a scheme based on:

• BASIC mode
• With the challenge parameters containing the CookieLessMode=true entry

The BasicSessionlessScheme can be used for this flow.

Also, OIF must be configured to send "urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport" as a SAML 2.0 Authentication Method when the client is authenticated via the BasicSessionlessScheme.

To configure OIF to use HTTP Basic Authentication in the SAML 2.0 ECP flow, execute the following steps:

• Enter the WLST environment by executing:
  $IAM_ORACLE_HOME/common/bin/wlst.sh
• Connect to the WLS Admin server:
  connect()
• Navigate to the Domain Runtime branch:
  domainRuntime()
• Execute the setSPPartnerAlternateScheme() command to instruct OIF to use BasicSessionlessScheme :
  setSPPartnerAlternateScheme(PARTNER_NAME, "true", httpHeaderName="X-MS-Client-Application", httpHeaderExpression=".*Microsoft.Exchange..*", authnScheme="BasicSessionlessScheme")
• Replace PARTNER_NAME with the name of the added partner
• An example would be:
  setSPPartnerAlternateScheme("Office365", "true", httpHeaderName="X-MS-Client-Application", httpHeaderExpression=".*Microsoft.Exchange..*", authnScheme="BasicSessionlessScheme")
• Retrieve the OIF Fed partner profile used by the Office 365 SP partner in OIF (see next article for more information on Partner Profiles):
  getFedPartnerProfile(PARTNER_NAME "sp")
• Replace PARTNER_NAME with the name of the added partner
• An example would be:
  getFedPartnerProfile("Office365", "sp")
• Write down the returned value
• Execute the addSPPartnerProfileAuthnMethod() command to instruct OIF to send "urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport"  as the SAML 2.0 Authentication Method when the client is authenticated via BasicSessionlessScheme:
  addSPPartnerProfileAuthnMethod(PARTNER_PROFILE, "urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport", "BasicSessionlessScheme")
• Replace PARTNER_PROFILE with the value retrieved in the earlier step
• An example would be:
  addSPPartnerProfileAuthnMethod("saml20-sp-partner-profile", "urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport", "BasicSessionlessScheme")
• Exit the WLST environment:
  exit()

Testing

Browser SSO

To test the Browser SSO flows:

• Open a browser
• Go to http://office365.com
• Click Sign In
• Enter the user’s email address

Execute the following steps:

• Click Next
• Office 365 will attempt to locate your Office 365 domain based on the suffix of the email address
• Once the domain has been located, Office 365 will trigger a Federation SSO flow to redirect you to OIF / IdP for authentication

Execute the following steps:

• At OIF / IdP enter username/password (depending on the Authentication scheme used to authenticate Federated users, LDAPScheme in this example)
• Click login

OIF/IdP will validate the credentials, create a SAML 2.0 Assertion and redirects the user back to Office 365 where the user will be granted access:

A sample SAML 2.0 Assertion sent by OIF / IdP to Office 365 would look like:

<samlp:Response ... Destination="https://login.microsoftonline.com/login.srf" ID="id--eBpq-cnpGfrWXMpBIjxN7QPQKa6WTVtnuZZr0Qe" InResponseTo="_d111d2a7-3475-4bc2-928f-34b83a4a0f64" IssueInstant="2014-01-18T16:58:05Z" Version="2.0">
  <saml:Issuer Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity">https://acme.com/oam/fed</saml:Issuer>
  <samlp:Status><samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"/></samlp:Status>
  <saml:Assertion ID="id-nTZcRuTaECKj2X9wzUTn7e-CknyECbGljTSo1T70" IssueInstant="2014-01-18T16:58:05Z" Version="2.0">
    <saml:Issuer Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity">https://acme.com/oam/fed</saml:Issuer>
    <dsig:Signature>
      <dsig:SignedInfo>
        <dsig:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
        <dsig:SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/>
        <dsig:Reference URI="#id-nTZcRuTaECKj2X9wzUTn7e-CknyECbGljTSo1T70">
          <dsig:Transforms>
            <dsig:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
            <dsig:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
          </dsig:Transforms>
          <dsig:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
          <dsig:DigestValue>6iKaxdO74Xi5eRnv0X7nsmN/y10=</dsig:DigestValue>
        </dsig:Reference>
      </dsig:SignedInfo>
      <dsig:SignatureValue>WYCBhIgPLafDeXroMSME80/QM...K/sNsI=</dsig:SignatureValue>
      <dsig:KeyInfo>
        <dsig:X509Data>
          <dsig:X509Certificate>MIIB+DCCAWGgA...plaoMZLcRoInVUbGTBDMfqmW5iZ/wjpzItg==</dsig:X509Certificate>
        </dsig:X509Data>
      </dsig:KeyInfo>
    </dsig:Signature>
    <saml:Subject>
      <saml:NameID Format="urn:oasis:names:tc:SAML:2.0:nameid-format:persistent" NameQualifier="https://acme.com/oam/fed" SPNameQualifier="urn:federation:MicrosoftOnline">alice.appleton</saml:NameID>
      <saml:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer"><saml:SubjectConfirmationData InResponseTo="_d111d2a7-3475-4bc2-928f-34b83a4a0f64" NotOnOrAfter="2014-01-18T17:03:05Z" Recipient="https://login.microsoftonline.com/login.srf"/></saml:SubjectConfirmation>
    </saml:Subject>
    <saml:Conditions NotBefore="2014-01-18T16:58:05Z" NotOnOrAfter="2014-01-18T17:03:05Z">
      <saml:AudienceRestriction>
        <saml:Audience>urn:federation:MicrosoftOnline</saml:Audience>
      </saml:AudienceRestriction>
    </saml:Conditions>
    <saml:AuthnStatement AuthnInstant="2014-01-18T16:58:05Z" SessionIndex="id-IM-SvfoQa8uVVtSmN-lrdOfgEVKFJHF8AhmIDzj-" SessionNotOnOrAfter="2014-01-18T17:58:05Z">
      <saml:AuthnContext>
        <saml:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport</saml:AuthnContextClassRef>
      </saml:AuthnContext>
    </saml:AuthnStatement>
    <saml:AttributeStatement>
      <saml:Attribute Name="IDPEmail" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
        <saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xsi:type="xs:string">alice.appleton@acme.com</saml:AttributeValue>
      </saml:Attribute>
    </saml:AttributeStatement>
  </saml:Assertion>
</samlp:Response>

ActiveSync Mail Application

For this test, I will add an Exchange email account on an iPhone. During the setup, the iPhone mail application will send the email address and password to Office 365 mail server, which will extract the user identifier from the email address and perform the SAML 2.0 ECP protocol with HTTP Basic Authentication.

Note: a similar flow would be exercised if the setup involved an Outlook Desktop application instead of the iPhone mail native application.

Perform the following steps to set up the iPhone with Office 365:

• Go to Settings
• Go to Mail
• Add Account
• Select Exchange

Perform the following steps:

• Enter the email address (alice.appleton@acme.com in this example)
• Password at OAM/OIF for the user (password for alice.appleton user; remember that the identifier will be used as the HTTP Basic Authentication username, alice.appleton in this example)

Perform the following steps:

• Click Next
• The mail application will send the user account information to Office 365 mail server
• Office 365 mail server will interact with OIF / IdP via the SAML 2.0 ECP protocol to validate the data, with the user identifier and password sent via HTTP Basic Authentication to OIF / IdP

Upon successful validation, the iPhone will show:

After showing the successful validation, the iPhone will display a screen allowing the user to select which feature to enable. After selecting the features, save: the account will have been set up.

In the next article, I will discuss about an OIF configuration item called Partner Profiles.
Cheers,
Damien Carru