Azure AD Federated Identity With Office 365

Introduction

Azure Active Directory federated identity with Office 365 currently supports 2 modes of authentication:

  • Managed Domain Authentication: Authentication of users in managed domains where identity information including passwords are managed by the Office 365 Authentication platform and authentication is performed by the Office 365 Authentication platform
  • Federated Domain Authentication: Authentication of users in federated domains where authentication requests are handed off to a security token service (STS) located within the premises of an organization via standardized protocols (WS-Fed and WS-Trust)

Office 365 uses Azure Active Directory for identity federation and Azure Active Directory supports WSFederation, WS-Trust, and SAML-P as authentication protocols. An overview of the Works with Office 365 – Identity program for Microsoft customers is here. Customers of Office 365 may use Windows Active Directory, Azure Active Directory or may use various non-Microsoft identity provider databases to store their user directories. Federation with those identity providers provides for a sign-in request at Office 365 to be validated by the selected identity provider. Office 365 acts as a relying party for the federated identity authentication operation.

This document should be reviewed by independent software vendor companies that have identity provider products that they want to offer identity federation for Office 365 customers. It describes the core scenarios and technical requirements that 3rd party STS vendors would need to meet in order to be compatible with Azure Active Directory Federation Domain Authentication.

Please note: it is responsibility of independent software vendors to validate compatibility of their implementation for the purpose of federating with Microsoft AAD. These independent software vendors are further responsible for providing customer support to their customers who run into problems after deploying their federated solutions with Microsoft AAD. Microsoft cannot provide claims of compatibility or customers support for these federated solutions.

Glossary OF Terms

This table shows specific terms used in this document.

Term

Description

Security Token

Service/STS

This terms refers to the entity that issues a security token and is digitally signed by the entity

Identity Provider/IDP

This refers to the STS that performs the originating authentication by asking the user to provide a credentials that it validates and then issues a security token. For the purposes of this document, it refers to the on-premises STS.

Scenario MATRIX

There are numerous scenarios that Office 365 supports each involving different authentication patterns and protocols and a matching set of technical requirements. The section identifies the scenarios and also states which scenarios are mandatory for a 3rd party STS vendor to meet.

In addition, links to the matching technical requirements are also listed with a scenario for viewing convenience.

Web Client Applications like OWA/SPO/Portal

Scenario

Support Requirement

1a

Authentication of users INSIDE the corp network on a domain joined machine using Username/Pwd

REQUIRED

1b

Authentication of users INSIDE the corp network on a non-domain joined machine using Username/Pwd

REQUIRED

2

Authentication of users INSIDE the corp network on a domain joined machine using Windows Integrated Authentication

OPTIONAL

3a

Authentication of users OUTSIDE the corp network on a non-domain joined machine using Username/Pwd

REQUIRED

3b

Authentication of users OUTSIDE the corp network on a domain joined machine using Username/Pwd

REQUIRED

Rich Client Applications like Skype for Business, Office Subscription, CRM

Scenario

Support Requirement

1a

Authentication of users INSIDE the corp network on a domain joined machine using Username/Pwd

REQUIRED

1b

Authentication of users INSIDE the corp network on a non-domain joined machine using Username/Pwd

REQUIRED

2

Authentication of users INSIDE the corp network on a domain joined machine using Windows Integrated Authentication

OPTIONAL

3a

Authentication of users OUTSIDE the corp network on a non-domain joined machine using Username/Pwd

REQUIRED

3b

Authentication of users OUTSIDE the corp network on a domain joined machine using Username/Pwd

REQUIRED

Email Clients like Outlook and ActiveSync

Scenario

Support Requirement

1a

Authentication of users INSIDE the corp network on a domain joined machine using Username/Pwd

REQUIRED

1b

Authentication of users INSIDE the corp network on a non-domain joined machine using Username/Pwd

REQUIRED

2a

Authentication of users OUTSIDE the corp network on a non-domain joined machine using Username/Pwd

REQUIRED

2b

Authentication of users OUTSIDE the corp network on a domain joined machine using Username/Pwd

REQUIRED

Modern Applications like Office 2016 (2013 using ADAL)

Scenario

Support Requirement

1a

Authentication of users INSIDE the corp network on a domain joined machine using Username/Pwd

REQUIRED

1b

Authentication of users INSIDE the corp network on a non-domain joined machine using Username/Pwd

REQUIRED

2

Authentication of users INSIDE the corp network on a domain joined machine using Windows Integrated Authentication

OPTIONAL

3a

Authentication of users OUTSIDE the corp network on a non-domain joined machine using Username/Pwd

REQUIRED

3b

Authentication of users OUTSIDE the corp network on a domain joined machine using Username/Pwd

REQUIRED

Technical Requirements

An IDP must meet the criteria in the following table. Click on any of the technical requirements for more details.

Technical Requirement Criteria

Criteria

Receive and process WS-Federation sign-in request

REQUIRED

SAML token requirements in WS-Federation sign-in response

REQUIRED

Receive and process WS-Federation sign-out request

REQUIRED

Technical Requirement Details

RECEIVE AND PROCESS WS-FEDERATION SIGN-IN REQUEST

  1. The IDP MUST implement the requestor profile as defined by the WS-Federation spec (link) section 13.1.1.
  2. The IDP MUST process the 'wa' parameter as defined in section 13.2.1 in the WS-Federation spec
  3. The IDP MUST process the 'wctx' parameter as defined in section 13.2.1 in the WS-Federation spec
  4. The IDP MUST present a web page, gather user credentials (the credentials may be of multiple form) validate the credentials

SAML TOKEN REQUIREMENTS IN WS-FEDERATION SIGN-IN RESPONSE

  1. The token issued MUST be a SAML 1.1 token and be conformant with the SAML 1.1 token format specification
  2. The token MUST contain the UserPrincipalName of the form user@contoso.com. The suffix of the userPrincipalName MUST be a 'federated' domain previously provisioned in the Office 365 authentication platform
  3. The token MUST contain the ImmutableID that matches
  4. The issuerID in the SAML token MUST match the 'sourceAnchor' attribute that was synchronized to the Office 365 Authentication platform.

RECEIVE AND PROCESS WS-FEDERATION SIGN-OUT REQUEST

The IDP MUST implement the requestor profile as defined by the WS-Federation spec (link) section 13.1.2.

Validation Requirements

  1. Setup the following test configuration for validation:
    1. Domain joined client machine running within the corporate network.
    2. Domain joined client machine running on the Internet outside the corporate network.
    3. Workgroup client machine running within the corporate network.
    4. Workgroup client machine running on the Internet outside the corporate network. If the partner supports Integrated Windows Authentication then they must show all four HTML reports, however if the partner does not support Integrated Windows Authentication then only scenario (d) is required.
  2. Validate the following scenarios in each of the above configurations if you support Integrated Windows Authentication. Otherwise you only need to validate these scenarios for configuration (d) above.
    1. Sign-in using federated credentials to the Office 365 administration portal using an administrator account.
    2. Download Office 365 Pro Plus from the Office 365 portal and sign-in from the Office client.
    3. Sign-in to the Outlook client from the downloaded Office 365 Pro Plus software using the federated identity.
    4. Sign-in to the Skype for Business client from the downloaded Office 365 Pro Plus software using the federated identity.
    5. Sign-out from the Office 365 administration portal.
  3. Provide a soft copy of customer facing documentation on your identity provider solution, including documentation on how to configure for successful federation with Office 365.

Resources

Documentation for configuring federation with Office 365 is available on TechNet in the article Office 365 integration with on-premises environments. There is also troubleshooting documentation for federation which has some ADFS focused aspects and some generic federation aspects which may be of help in knowledge base article 2530569.

Technical documentation specifically for implementing federation as an STS with Office 365 is available on the download STS Integration Paper using WS-* Protocols.

These documents are included in the download.

  • STS Integration Interoperability Scenario Requirements – This document outlines identity interoperability test requirements to be passed.
  • STS Integration Paper using WS Protocols – This document describes WS-* messages in detail with examples as used for Azure AD federation.

Additional technical documentation is available for federation with SAML 2.0 using the SP-Lite profile is available in Office 365 SAML 2.0 Federation Implementer's Guide.