Azure AD/Office 365 seamless sign-in – Understand single sign-on (SSO) with AD FS in Windows Server 2012 R2

Introduction

Through the (cross-domain) single sign-on feature, a.k.a. identity federation, as one of its seamless sign-in capabilities, Azure AD provides organizations with the ability to authenticate against the organization's Active Directory (or other identity repositories), allowing their users to use their corporate credentials to access Azure AD/Office 365 and their services that they have been provisioned for.

Thus, users that are on the internal corporate network or connected through a VPN will have seamless access to Azure AD/Office 365. If users are accessing Azure AD/Office 365 from home or from any computer not connected to the corporate network, they will also still have access to Azure AD/Office 365 using their corporate credentials. Such a user sign-in experience is awaited by many organizations:

  • Work computer on a corporate network. When users are at work and signed in to the corporate network, single sign-on enables them to access Azure AD/Office 365 without signing in again;
  • Roaming with a work computer. For users who are logged on to domain-joined computers with their corporate credentials, but who are not connected to the corporate network (for example, a work computer at home or at a hotel), single sign-on enables them to access Azure AD/Office 365 without signing in again as well;
  • Home or public computer. When the user is using a computer that is not joined to the corporate domain, the user must sign in with corporate credentials to access Azure AD/Office 365. This is still an advantage since they will only have to remember one set of credentials for their corporate and Azure AD/Office 365 accesses.
  • Mobile device. On a mobile device (phone or tablet), in order notably to access Microsoft Exchange Online using Microsoft Exchange ActiveSync (EAS), the users must sign in with their corporate credentials. This is still an advantage since they will only have to remember one set of credentials for their corporate and Office 365 accesses.

Note    Not all type of mobile devices are using EAS, some are using Exchange Web Services (EWS) instead. For more information, see the web site Office for Mobile Devices and the wiki article OWA for iPhone and OWA for iPad.

  • Microsoft outlook or other e-mail clients. The users must sign in with their corporate credentials to access their e-mail messages if they are using Outlook or an e-mail client that is not part of Office such as an IMAP or a POP client.

Such an authentication with the single sign-on feature of Azure AD can be provided among other solutions through Active Directory Federation Services (AD FS) as a preferred Security Token Service (STS).

Note    A Microsoft program named Works with Office 365 – Identity enables to conduct interoperability testing against other third party identity provider solutions. Thanks to this program, a list of third-party identity provider solutions is also supported beyond AD FS. For example, the Shibboleth 2 identity provider can be used in lieu of AD FS as described in the white paper Azure AD/Office 365 Single Sign-On with Shibboleth 2.

Beginning with the Windows 2000 (Server) platform, the Kerberos-based user identity provided by Active Directory has facilitated secure authorization and single sign-on to Active Directory-aware (Microsoft and non-Microsoft) resources located inside its own and other trusted Active Directory domains/forests.

AD FS enables identity federation, extending the notion of above centralized authentication, authorization, and single sign-on to Web applications and services located virtually anywhere, and notably in the cloud.

Wikipedia defines identity federation as follows:

"Federated identity, or the 'federation' of identity, describes the technologies, standards and use-cases which serve to enable the portability of identity information across otherwise autonomous security domains. The ultimate goal of identity federation is to enable users of one domain to securely access data or systems of another domain seamlessly, and without the need for completely redundant user administration."

Identity federation relies on standards-based protocols to establish federation trusts between claims providers and relying parties, facilitating secure access to Web applications and services across security boundaries.

For an organization, AD FS provides corporate users with a rich federated experience and seamless access to resources located:

  • Inside the corporate intranet;
  • On partner's organizations network (or within their perimeter network) that have made resources available to the considered organization's users;
  • Outside the corporate network in a corporate perimeter network, extranet and/or in the Cloud, for example in Microsoft Azure, the Microsoft's Infrastructure-as-a-Service (IaaS) and Platform-as-a-Service (PaaS) offering;
  • In the Cloud with Software as a Service (SaaS) vendors that support federated identity, for example, Microsoft Office 365.

Note    Azure AD can act as a federation hub for the last two bullets.

Objectives of this paper

Built on existing Microsoft documentation and knowledge base articles, this paper further presents the single sign-on feature (a.k.a. identity federation) of Azure AD/Office 365 with AD FS in Windows Server 2012 R2.

For that purpose, this document:

  • Describes the various AD FS implementation scenarios for federated authentication,
  • Describes how federated authentication works with AD FS,
  • Covers additional information you be aware of regarding AD FS,

, so that Azure AD/Office 365 projects involving AD FS in this context can be more easily completed, and consequently enabling customers to realize the full potential of the Microsoft offerings in the cloud.

AD FS is a component of the Windows (Server) platform and, as such, the right to use it is included in the associated license costs.

Non-objectives of this paper

This document doesn't provide a full description of AD FS. It rather focuses on key aspects that aims at providing the readers an understanding on how to leverage and deploy the AD FS service to achieve single sign-on with Azure AD/Office 365.

Note    For more information on AD FS in addition to the content of this paper, please refer to the the product documentation, and the dedicated AD FS Q&A forum.

It doesn't provide neither guidance for setting up and configuring AD FS in a production environment – beyond highlighting key scenarios - nor a complete technical reference for AD FS.

Finally, this document doesn't provide a complete end-to-end walkthrough to rollout a working Azure AD/Office 365 (cross-domain) single sign-on configuration with AD FS. This is the purpose of the previous Part 2 to establish a base configuration of a test lab environment, and the subsequent Parts 4 (bis) and 4bis respectively Part 5 to complete the configuration of the AD FS environment with Windows Server 2012 R2 respectively Windows Server 2016.

Organization of this paper

To cover the aforementioned objectives, this document adopts an organization according to the following themes, each of them being addressed in the following sections:

  • Understanding the Office 365 federated identity model.
  • Understanding the single sign-on (SSO) configuration.
  • Understanding how single sign-on (SSO) works in Azure AD/Office 365.
  • Leveraging the AD FS enhancements for Office 365 and other considerations.

About the audience

(cross-domain) single sign-on, a.k.a. identity federation, is in general a broad topic, with many facets, depths of understanding, protocols, standards, tokens, etc. This paper addresses the single sign-on topic only from the Azure AD/Office 365 perspective and from both conceptual and technical levels.

This document is thus intended for system architects and IT professionals who are interested in understanding this capability of Azure AD/Office 365.

Terminology used in this paper

Throughout the rest of this document, the following terms detailed in Table 1 are used regarding AD FS.

Table 1 AD FS Terminology

Term

Description

AD FS configuration database

A database used to store all configuration data that represents a single AD FS instance or federation service. This configuration data can be stored either using the Windows Internal Database (WID) feature included with Windows Server 2012 R2 or using a Microsoft SQL Server database. Following versions of SQL Server are supported as of this writing: SQL Server 2008 and higher, including SQL Server 2008 R2, SQL Server 2012 and SQL Server 2014.

Claim

A statement that one entity makes about itself or another subject. For example, the statement can be about a name, email, group, privilege, or capability. Claims have a provider that issues them (in this context, an Office 365 customer) and they are given one or more values. They are also defined by a claim value type and, possibly, associated metadata.

Federation service

A logical instance of AD FS. A federation service can be deployed as a standalone federation server (FS) or as a load-balanced federation server farm. The name of the Federation Service defaults to the subject name of the SSL/TLS certificate. The DNS name of the Federation Service must be used in the Subject name of the SSL/TLS certificate.

Federation server

A computer running Windows Server 2012 R2 that has been configured to act in the federation server (FS) role for AD FS. A federation server serves as part of a Federation Service that can issue, manage, and validate requests for security tokens and identity management. Security tokens consist of a collection of claims, such as a user's name or role.

Federation server farm

Two or more federation servers in the same network that are configured to act as one Federation Service instance.

Web application proxy

A computer running Windows Server 2012 R2 that has the web application proxy (WAP) role installed and that has been configured to act as an intermediary proxy service between a client on the Internet and a federation service that is located behind a firewall on a corporate network. In order to allow remote access to the services in Office 365, such as from a smart phone, home computer, or Internet kiosk, you need to deploy a web application proxy (WAP).

Relying party

An AD FS server, a third-party federation solution, an application or a service that consumes claims in a particular transaction.

Relying party trust

In the AD FS Management snap-in, a relying party trust is a trust object that is created to maintain the relationship with another Federation Service, application, or service (in this case Office 365) that consumes claims from your organization's Federation Service.

Network load balancer    
Hardware load balancer

A dedicated application (such as Network Load Balancing) or hardware device (such as a multilayer switch) used to provide fault tolerance, high availability, and load balancing across multiple nodes. For AD FS, the cluster DNS name that you create using this NLB must match the Federation Service name that you specified when you deployed your first federation server in your farm.

Understanding the Office 365 federated identity model

Requirements for federated identities

Active Directory requirements

For an organization to leverage the single sign-on feature of Azure AD/Office 365, the domain controllers must run at least Windows Server 2008 or higher with a functional level of mixed or native mode.

Windows device requirements

The Windows devices must be on the latest service packs of Windows 7, Windows 8/8.1, or Windows 10.

Microsoft Office requirements

As far as the Microsoft Office requirements are concerned, this document covers Microsoft Office 365 ProPlus, Microsoft Office Professional Plus 2013, and Microsoft Office Professional Plus 2016.

Note    Office 365 is designed to work with any version of Microsoft Office that is in mainstream support. This means that, unlike to Microsoft Office Professional Plus 2016 and Microsoft Office Professional Plus 2013, Microsoft Office Professional Plus 2010 is no longer supported since October 2015.

The rest of this paper doesn't make the distinction between Office 365 ProPlus, Office 2013, and Office 2016 from a behavior perspective. In other words, any mention to Excel 2013/2016, Lync 2013/Skype for Business 2016, Outlook 2013/Outlook 2016, PowerPoint 2013/PowerPoint 2016, and Word 2013/Word 2016 will indifferently refer to Excel, Lync, Outlook, PowerPoint and Word in Office 365 ProPlus, Microsoft Office Professional Plus 2013, or Microsoft Office Professional Plus 2016.

AD FS server requirements (and any other machines used for administration purpose)

The configuration of the single sign-on leverages the Azure AD Connect tool that allows to quickly onboard to Azure AD and Office 365.

In addition, it should be noted that the Azure AD PowerShell V1 module - and its requirements like the Microsoft Online Services sign-in assistant (SIA) (See article MSOnline Module) - should be installed on all machines that will connect to Azure AD/ Office 365 including the servers hosting the AD FS role.

The Azure AD PowerShell V1 tool (e.g. version 1.1.166.0 as of this writing), a.k.a. the Microsoft Online (MSOL) library, basically provides a set of cmdlets to the Azure AD/Office 365 environment and a PowerShell interface so you can administer your Azure AD/Office 365 tenant using Windows PowerShell and you can complete common configuration tasks like the management of the single sign-on feature.

Important note    The MSOL library is going to be progressively replaced by the Active Directory V2 PowerShell module currently in public preview. For more information, see blog post In case you missed it: #AzureAD PowerShell v2.0 is now in public preview! and eponym article Azure Active Directory V2 PowerShell module.

Sign-in experiences for federated identities

The sign-in experience changes depending on the type of Azure AD/Office 365 identity in use. The end-user sign-in experience varies depending on the client types, the access methods, i.e. inside or outside the corporate network, and whether the machine has joined the domain or not.

Table 3 discusses the key combinations for domain joined machine and helps explaining the resulting experiences when the modern authentication isn't being used (see later in this document).

Table 3 Federated identity sign-in experience with Azure AD/Office 365 with a domain joined Windows devices without modern authentication (see later)

Application

Inside the corporate network

Outside the corporate network

Outlook 2013/2016, Exchange ActiveSync, POP, IMAP

Prompted for credentials on first connection (and at each password change) with checkbox to remember them.

Office 365 portal, SharePoint Online, Office Web Apps1

Pop up offers click to sign in with no credentials required1

Pop up offers click to sign in and prompted for credentials1

Outlook Web Apps1

Seamless sign on with no prompts

Prompted for credentials (using form-based authentication form from the Web Application Proxy servers farm)

Lync 2013/Skype for Business 2016 with Skype for Business, Office 2013/2016 Windows client applications (Excel, PowerPoint, and Word) with SharePoint Online

Seamless sign on with no prompts

 

1 All apps require you to enter your username or click to sign in. This can be bypassed by using Smart Links (see section § Smart links).

As per the table above, when using federated identities, end-users will not be prompted to enter their passwords on domain-joined Windows devices in many cases:

  • When accessing the Office 365 portal, SharePoint Online, or Outlook Web Apps (OWA) through a browser, inside the corporate network;
  • When using Office 2013/2016 Windows client applications (Excel, PowerPoint, and Word) to access SharePoint Online resources;
  • When using Lync 2013/Skype for Business 2016 to access Skype for Business (formerly Lync Online).

Outlook users will be prompted to enter their corporate credentials on first use, at which time they can choose to save their password for future use. In this case, end-users will not be prompted again until they change their password, which depends on the organization's password policies.

The following Table 4 discusses the key combinations for non-domain joined machine and helps explaining the resulting experiences.

Table 4 Federated identity sign-in experience with Azure AD/Office 365 for non-domain joined device (applies also to any workplace-joined device) with modern authentication (see later in this document)

Application

Inside the corporate network

Outside the corporate network

Outlook 2013/2016, Exchange ActiveSync, POP, IMAP

Prompted for credentials on first connection (and at each password change) with checkbox to remember them.

Office 365 portal, SharePoint Online, Office Web Apps1

Pop up offers click to sign in and prompted for credentials1

Outlook Web Apps1

Prompted for credentials

Lync 2013/Skype for Business 2016 with Skype for Business, Office 2013/2016 Windows client applications (Excel, PowerPoint, and Word) with SharePoint Online

Prompted for credentials

 

1 All apps require you to enter your username or click to sign in. This can be bypassed by using Smart Links (see section § Smart links).

Type of authentication for federated identities

This section discusses the types of user authentication that work with Office 365 for a Federated Identity.

Authenticating from a web browser

As previously mentioned, Office 365 offers several services that you can access using a web browser, including the Office 365 portal, SharePoint Online, and Outlook Web App (OWA). When you access these services, just after typing your username, your browser is redirected to a sign-in page where you provide your sign-in credentials (redirection is based-on the domain part of your user identity).

The sign-in experience is as follows for a Federated Identity:

  1. The web browser is redirected to Azure AD, where you type your corporate ID in the form a User Principal Name (UPN) formatted per IETF standard RFC 822 Standard for ARPA Internet Text Messages, for example johndoe@litware369.com. The sign-in service determines that you are part of a federated domain and offers to redirect you to the on-premises AD FS service for authentication.
  2. If you are logged on to the computer (domain joined), you are already authenticated using Integrated Windows Authentication (Kerberos or NTLMv2) and AD FS generates a SAML 1.1 logon token, which the web browser posts to Azure AD. Using the logon token, the sign-in service generates an authentication token that the Web browser posts to the requested service and logs you in.

If your computers have Extended Authentication Protection (EAP), and you use Firefox, Chrome, or Safari, you may not be able to sign in to Azure AD/Office 365 using Windows Integrated Authentication (WIA) from within the corporate network. If this situation occurs, your users might receive logon prompts on a regular basis as described in the article A federated user is repeatedly prompted for credentials during sign-in to Office 365, Azure, or Intune. This is due to the default configuration on Windows 7 and above and client operating systems for AD FS and EAP.

Until Firefox, Chrome, and Safari support the EAP feature, the recommended option is for all Windows clients accessing services in Office 365 (especially for domain-joined machines) to install and use Internet Explorer 10 and above.

For non-Windows computers, if you want to use single sign-on for Office 365 with Firefox, Chrome, or Safari, you should consider the following approaches which may imply additional security concerns:

  • Uninstalling the Extended Protection for Authentication patches from the computers.
  • Changing the Extended Protection for Authentication setting on the AD FS server through the ExtendedProtectionTokenCheck switch of the Set-ADFSProperties cmdlet:
PS C:\> Add-PSSnapin Microsoft.Adfs.Powershell 
PS C:\> Set-ADFSProperties –ExtendedProtectionTokenCheck:None

Note    For more information, see the AD FS Administration with Windows PowerShell section of the AD FS Operations Guide and the AD FS Cmdlets in Windows PowerShell.

Furthermore, since WIA (Windows Integrated Authentication) is enabled by default in AD FS for authentication requests that occur from within the corporate network for any application that uses a browser for its authentication, authentication requests from browsers not capable of supporting WIA will as a result fail. The recommended approach is to fallback to forms-based authentication for such browsers.

AD FS provides IT professionals with the ability to configure the list of user agents that support the fallback to forms-based authentication through the WIASupportedUserAgentStrings switch of the Set-ADFSProperties cmdlet:

PS C:\> Add-PSSnapin Microsoft.Adfs.Powershell 
PS C:\> Set-AdfsProperties -WIASupportedUserAgents @("MSIE 6.0", "MSIE 7.0; Windows NT", "MSIE 8.0", "MSIE 9.0", "MSIE 10.0; Windows NT 6", "Windows NT 6.3; Trident/7.0", "Windows NT 6.3; Win64; x64; Trident/7.0", "Windows NT 6.3; WOW64; Trident/7.0", "Windows NT 6.2; Trident/7.0", "Windows NT 6.2; Win64; x64; Trident/7.0", "Windows NT 6.2; WOW64; Trident/7.0", "Windows NT 6.1; Trident/7.0", "Windows NT 6.1; Win64; x64; Trident/7.0", "Windows NT 6.1; WOW64; Trident/7.0", "MSIPC", "Windows Rights Management Client")

AD FS analyzes the user agent string when performing logins in a browser or browser control. If the component of the user agent string does not match any of the components of the user agent strings that are configured, AD FS will fall back to providing forms-based authentication.

Note    For more information, see article Configuring intranet forms-based authentication for devices that do not support WIA.

For Windows 10 domain-joined devices, and in addition to the above list provided in the code snippet, you need to add the following strings, each line representing an entry:

Mozilla/5.0 (Windows NT 10.0; Win64; x64; WebView/3.0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/42.0.2311.135 Safari/537.36 Edge/12
Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/42.0.2311.135 Safari/537.36 Edge/12
In-Domain
Mozilla/5.0 (Windows NT 10.0; WebView/3.0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/42.0.2311.135 Safari/537.36 Edge/12

Note    For more information, see blog post Desktop SSO on Win10 Domain Joined machines using EDGE browser.

Generally speaking, you should ensure that you have an operational plan to maintain the WIASupportedUserAgents setting in AD FS to keep up with new browsers.

Authenticating from rich client applications

Rich clients include Office Windows client applications that are typically installed on a device. Authentication from these types of applications can occur in three possible ways:

  1. Microsoft Online Services Sign-In Assistant (SIA). The Microsoft Online Services Sign-In Assistant (SIA) – notably in Office 2013/2016 as the auto-shipped SIA Lite DLL - contains the Windows service MSOIDSVC.exe that obtains an authentication token from Azure AD and returns it to the rich client.

Note    In the context of this paper, the SIA is used to authenticate users to these services through a set of dynamic link library files (DLLs) and a Windows service: MSOIDSVC.

With a Federated Identity, and as later depicted in this paper (see section § MEX/Rich client profile authentication flow), the MSOIDSVC service first contacts the AD FS server to authenticate the credentials (using Kerberos or NTLMv2) and obtain a logon token that is sent to Azure AD (using metadata information (as per WS-Federation (WS-Fed)) and WS-Trust).

  1. Basic/proxy authentication over SSL/TLS. The Outlook 2013/2016 client transfers basic authentication credentials over SSL/TLS to Exchange Online. Exchange Online proxies the authentication request to Azure AD, and then to on-premises AD FS (for single sign-on). The authentication flow is described later in this document (see section § EAS basic auth/active profile authentication flow).

Note    This authentication requires deployment of a proxy server or a web application proxy (WAP) in your perimeter network (a.k.a. demilitarized zone, DMZ, or screened subnet).

  1. Modern authentication for Office 365. This stack now allows Office client applications to engage in browser-based authentication with AD FS (or other supported STSs) to sign in to the Azure AD/Office 365 service to gain access to Exchange Online email, SharePoint Online, Skype for Business Online (formerly Lync Online), and to activate the Office client license.

The following Table 5 details the authentication mechanisms with a Federated identity for different combinations of applications and operating systems.

Table 5 Authentication mechanisms for a federated identity in Azure AD/Office 365

Application

Authentication Mechanism

Outlook 2013/Outlook 2016 without modern authentication, Exchange ActiveSync, POP/IMAP/SMTP client

Basic authentication over SSL/TLS, authenticated via the web application proxy (fully-implemented AD FS scenario)

Web browser

Web sign in, WS-Federation (AD FS)

Lync 2013/Skype for Business 2016 without modern authentication, Office 2013/2016 Windows client applications (Excel, Powerpoint, and Word) without modern authentication

WS-Federation (metadata) and WS-Trust (sign-in assistant and AD FS)

Lync 2013/Skype for Business 2016 with modern authentication, Office 2013/2016 Windows client applications (Excel, Powerpoint, Outlook, and Word) with modern authentication

Web sign in, WS-Federation (AD FS)

Modern authentication allows authentication flows where users can sign in to Office 2013/2016 client applications using WS-Federation (see section § Modern authentication flows).

This notably homogenizes the authentication flows among the Office 2013/2016 client applications.

Modern authentication provides single sign-on (SSO) between all applications (Word, Excel, PowerPoint, Outlook, OneNote, etc.) but does not provide SSO between client apps and web sites or across devices (or platforms). As far as the latter is concerned, a solution like AD FS greatly contributes to enhance the user experience avoiding users to sign-in again in some situations.

From a technical standpoint, modern authentication is an OAuth-based authentication stack used by Office 2013/2016 client applications against Office 365 where the Active Directory Authentication Library (ADAL) replaces for Windows clients the Microsoft Online Sign-in Assistant (SIA).

In addition, modern authentication allows you to configure new security scenarios for sign in with Office 365. Some examples are:

  • Outlook no longer requiring the basic authentication over SSL/TLS protocol where the username and password are required to be provided anytime a connection to Exchange Online is made. Instead, Outlook 2013 communicates directly with your Claims Provider, AD FS in the context of this document, and will no longer needs to share the user's password with Exchange Online for user authentication.
  • Multi-factor authentication (MFA) in the cloud with Azure MFA or on-premises with the configuration of a Microsoft MFA server and third-party external authentication provider in AD FS.

Note     The App passwords in Azure MFA - see article Managing your Azure Multi-Factor Authentication User Settings - were a way to exercise MFA before modern authentication. In other words, with modern authentication, you no longer need them. All Office apps using modern authentication can do "true MFA" (phone call, text etc).

  • Smart card and certificate-based authentication.
  • Conditional access.

Interestingly, modern authentication is not just devoted to Windows clients but provides a cross platform support (Windows, Mac OS X, iOS, and Android).

The following Table 6 offers a synthesis of the modern availability as of this writing.

Table 6 Modern authentication availability

 

Windows

Mac OS X

iOS

Android

Office 2013/2016 (Word, Excel, PowerPoint, OneNote, Publisher, Visio, Access, Project)

Available now

In Preview (Office 2016 Mac Preview supports ADAL including Word, Excel, PowerPoint and OneNote. OneNote was released with ADAL in 2014)

Available now (Excel, OneNote, PowerPoint, and Word)

Available now (Excel, OneNote, PowerPoint, and Word)

Lync 2013/Skype for Business 2015

Available now

In Preview

Available now

Available now

Outlook 2013/2016

Available now

Available now*

Available now

Available now

OneDrive for Business

Available now (app included in Office suite)

TBD

Available now

Available now

Note    For more information, see blog post Office 2013 modern authentication public preview announced. And article Updated Office 365 modern authentication.

Enabling the modern authentication for Office 365

Modern authentication is available to any customer running Office 2013 and the March 2015 or later update for Office 2013, Office 2016 and Office 365 ProPlus. You MUST request to have your Skype for Business Online service to be enabled for modern authentication.

Important note    The Office 2013 March 2015 update or later update are fully production ready and supported.

Note    Updates are automatically available for Office 365 ProPlus applications - users will see a pop-up screen in the product prompting them to apply the new updates. Office 2013 and Office 2016 Windows client applications are updated using Windows update.

Note     For more information on feature updates, see the Office blog.

Enabling the modern authentication for Skype for Business

Use the
Microsoft Connect form
to request for your Skype for Business Online service to be enabled for modern authentication.

Enabling the new authentication features on the Windows devices

The new authentication features must also be enabled on each Windows client device. iOS, Mac OS and Android clients that support modern authentication are enabled by default.

As far as Windows devices are concerned, these new authentication features are available to you on Windows devices running:

  • Office 365 ProPlus, but is disabled by default.
  • The March 2015 or later update for Office 2013 but is disabled by default.
  • Office 2016 and later is enabled by default.

Note     With Windows 10, you may experience the issues described in the articles "Invalid provider specified" error when you use an Office 2016 application to access Office 365 resources
and "Background task activation is spurious" error when you use an Office 2016 application to access Office 365 resources.

To enable modern authentication for any Windows devices that have Office 365ProPlus or Office 2013 installed, you need to set specific registry keys on the above Windows devices:

Registry key

Type

Value

HKCU\SOFTWARE\Microsoft\Office\15.0\Common\Identity\EnableADAL

REG_DWORD

1

HKCU\SOFTWARE\Microsoft\Office\15.0\Common\Identity\Version

REG_DWORD

1

Note     For information on how to enable the feature on Windows client, see articles How modern authentication works for Office 2013 and Office 2016 client apps and Enable Modern Authentication for Office 2013 on Windows devices.

To ease the configuration of the Windows devices with the above registry keys, create a modernauth.reg text file with the following content:

Windows Registry Editor Version 5.00

[HKEY_CURRENT_USER\SOFTWARE\Microsoft\Office\15.0\Common\Identity]
"EnableADAL"=dword:00000001
"Version"=dword:00000001

One should note in addition to the above that Office client applications have an optimized path for their first accounts to work against the WS-Trust Kerberos authentication endpoints of AD FS. If this fails, then the Office client applications fall back to an interactive login session through a web browser dialog.

Unfortunately, as of this writing, Office and ADAL clients target the WS-Trust 1.3 version of the endpoint for windows integrated authentication which is not enabled by default. This can be fixed easily by enabling it on AD FS.

PS C:\> Add-PSSnapin Microsoft.Adfs.Powershell 
PS C:\> Enable-AdfsEndpoint -TargetAddressPath "/adfs/services/trust/13/windowstransport"

The office and ADAL teams are working towards using the standard WS-Trust 2005 endpoint that is enabled by default in AD FS. However, this probably won't show up until a future cumulative update for the Office client applications. In the meantime, it's better to enable the endpoint and there is no difference in behaviors between the 2 versions of the endpoints.

Note     For more information, see the blog post Office Modern Auth & ADFS: Making it work.

Understanding the single sign-on (SSO) configuration

Reviewing the configuration steps and the related documentation

All steps required to setup single sign-on are fully documented on the Office 365 portal at https://portal.office.com. You can in particular use for that purpose the available Azure AD advisors: Azure AD Connect advisor and the AD FS deployment advisor for customized setup guidance.

They both feature the Azure AD Connect tool that is the best way to connect your on-premises directory with Azure AD and Office 365, and setup single sign-on with AD FS.

Note    Azure AD Connect is replacing DirSync and Azure AD Sync and these two older sync engines are deprecated from April 13, 2016 reaching end of support April 13,2017.
For more information, see articles

Upgrade Windows Azure Active Directory Sync ("DirSync") and Azure Active Directory Sync ("Azure AD Sync").

Important note    Customers using DirSync or Azure AD Sync will continue to synchronize after April 13, 2017 but they not be able to receive support for their synchronization tool. They must upgrade to the latest version of Azure AD Connect in order to receive support.

Important note    Customers running Azure AD Connect 1.0.x.0 also received the message to upgrade to the latest version of Azure AD Connect in order to receive support. Microsoft recommends customers to stay current with Azure AD Connect releases. For a full list of fixes and improvements over the time of Azure AD Connect, see article Azure AD Connect: Version Release History.

Key related information to setup single sign-on is summarized in the next section.

Preparing for the single sign-on (SSO)

The aforementioned advisors cover all the operations to prepare the on-premises organization's IT environment for single sign-on. The organization's on-premises AD must indeed have certain settings configured in terms of both the structure and the use of the AD domain name in order to work properly with single sign-on.

To prepare the Active Directory environment, we highly recommend running the IdFix tool. This tool is used to perform discovery and remediation of identity objects and their attributes in the on-premises Active Directory environment in preparation for the directory synchronization with single sign-on scenario to Azure AD/Office 365.

Note    As of the writing of this whitepaper, the current version of IdFix (version 1.08) is only working against a single Active Directory forest and do not check against multiple forests.

A relevant assessment should cover the following topics:

  1. UPNs.
    Federated identities require corporate users to have a User Principal Name (UPN) set-up, though Active Directory does not. UPNs associate user's identities in Azure AD/Office 365 for enterprises with the identity in the cloud. Without this value, users may not be able to sign into Office 365 with their corporate credentials. (The "Alternate login ID" capability of AD FS enables to specify a different attribute, See section § Using an alternate login ID)

    UPNs that are used for federated identities can contain in the left-end part (before the "at" sign (@)) letters, numbers, periods, dashes, and underscores; no other types of characters are permitted. In addition, the left-hand part of the UPN cannot end in a period. The right-hand part separated by the "at" sign must be an internet routable domain. In order to address UPN issues, there are a few options for modifying users' attributes in bulk. A few tools can be used for this operation such as ADModify for example.

  2. Matching domains. When Azure AD/Office 365 domain names match the domain names for the local Active Directory, no special considerations regarding the name space are required.
  3. Sub domains. Configure top-level domains first, and then configure sub-domains. When you register your top-level domain such as litware369.com, there is no need to register the subdomains such as legal.litware369.com or ny.litware369.com. Sub domains are automatically registered for you.
  4. Non-Internet routable domains.
    Non-Internet routable domains such as .local, .intranet, or any non-internet routable ones (for example litware369.local or litware369.intranet) cannot be used for federation because they cannot be accessed from the Internet (that is, they are not publicly routable or identifiable in DNS).

Understanding the AD FS implementation scenarios for Azure AD/Office 365

As already covered, you must have an on-premises AD FS infrastructure in place in order to leverage the (cross-domain) single sign-on feature of Azure AD/Office 365 and to authenticate the corporate users to Azure AD/Office 365 using the Federated Identities.

This section explores the various AD FS implementation scenarios for Office 365 so that you can select the one that best fits your end users' scenarios, requirements, etc.

As with most enterprise-level services, an AD FS infrastructure can be indeed implemented in various ways, based-on business needs. More specifically for the single sign-on feature of Office 365, and as described in the article Supported scenarios for using AD FS to set up single sign-on in Office 365, Azure, or Intune, the on-premises AD FS infrastructure can be published to the Internet using different supported scenarios. Depending on the scenario selected and implemented the underlying result, dependencies and limitations are highlighted in the article.

Each outlined scenario can also be implemented using a standalone AD FS server instead of a server farm. However, it is always a Microsoft best-practice recommendation for all critical infrastructure services to be implemented by using high-availability technology to avoid loss of access.

On-premises AD FS server availability directly affects Azure AD/Office 365 service availability for federated identities. For example, with a standalone AD FS server infrastructure a single-server outage (the AD FS server) will prevent the associated all federated users to authenticate, hence it will prevent all users from accessing any Office 365 services.

Deployment types notes for the scenarios

Federation service

Federation servers must be domain-joined to Active Directory. Federation servers can be co-located on AD domain controllers since AD FS is no longer dependent on Internet Information Services (IIS). Starting with Windows Server 2012 R2, AD FS is implemented on top of HTTP.SYS instead.

Note    Although you can collocate AD FS with domain controllers, and as it's also a good practice to have load-balanced AD FS server farms, we would recommend using hardware load-balancer so that you won't use Network Load Balancing (NLB)/Windows Load Balancing (WLB) on domain controllers and their required specific NLB/WLB configuration if you were to use co-located services and NLB at the same time.

As suggested by the above terminology, there are two deployment types for AD FS servers: stand-alone and farm.

A stand-alone federation server is a single instance of the federation service. You typically create a stand-alone federation server when your production environment is small or if you are evaluating the AD FS technology.

Note    Remember that using a standalone AF FS server is not providing the recommended fault-tolerance. You should be planning for when using federated identities with Office 365.

A (load-balanced) federation server farm contains multiple federation servers, which host the same instance of a federation service. Conversely, you typically create a farm when you require high availability and load balancing. When creating a new federation service for a farm scenario the first computer in the farm will be automatically configured as being the "primary" federation server for the farm.

Note    For more information, see article Configure a Federation Server.

Web application proxy (WAP)

The web application proxy (WAP) Server role can be deployed in the perimeter network to enhance the security and performance of the AD FS installation by providing the following benefits:

  • Security. The web application proxy provides an additional layer of defense by isolating front-end requests from the corresponding back-end requests to the protected federation service, whether it is a stand-alone federation server or a (load-balanced) federation server farm. The web application proxy processes only the requests that are sent to known HTTP prefixes. It can also provide additional value by validating data in requests (for example, validating certificates) on behalf of AD FS.
  • Key protection. The private token-signing key and service identity key for AD FS are not stored on the web application proxy.
  • Corporate resources. The web application proxy can service AD FS client requests without requiring access to corporate resources, such as Active Directory.
  • Caching. The web application proxy can potentially offload the federation server by caching static HTTP content.

Like the federation server role, the web application proxy role can also be deployed as a stand-alone web application proxy or as a (load-balanced) web application proxy farm. Web application proxy does NOT have to be member of an Active Directory domain. The web application proxy role is implemented on top of HTTP.SYS.

Note    For more information, see article Web Application Proxy.

Fully-implemented AD FS scenario

An AD FS server (farm) services Active Directory client requests through single sign-on authentication. A (load balanced) web application proxy exposes those core authentication services to the Internet by relaying requests and responses back and forth between Internet clients and the internal AD FS environment.

Figure 6 Fully-implemented AD FS implementation scenario

From the above figure, you can see that corporate users would be directed to the AD FS load-balanced federation server farm internal endpoint but external users will have to use the load-balanced web application proxy to access the federation service.

It should be noted that, from an Azure AD/Office 365 perspective, a proxy is not only something useful for external users in order to redirect client authentication requests coming from outside the corporate network to the federation server farm. Such a proxy is indeed required in order for Outlook/EAS (but also EWS, POP3 and IMAP4 clients) to connect to Exchange Online using a federated identity. Without a proxy in place, Outlook profile creation will continually prompt for credentials (or you'll get a 401 HTTP response instead).

To sum up, a proxy enables for instance the following user scenarios:

  1. Work computer, roaming. Users who are logged on to domain joined computers with their corporate credentials, but who are not connected to the corporate network (for example, a work computer at home or at a hotel), can access the services in Office 365.
  2. Home or public computer. When the user is using a computer that is not joined to the corporate domain, the user must sign in with their corporate credentials to access the services in Office 365.
  3. Mobile device. On a mobile device, to access the services in Office 365 such as Microsoft Exchange Online using EAS, the user must sign in with his corporate credentials.
  4. Microsoft Outlook or other email clients. The user must sign in with their corporate credentials to access their Office 365 email if they are using Outlook or an email client that is not part of Office; for example, an IMAP or POP client.

This implementation scenario, as illustrated in the figure above, is fully supported by Azure AD/Office 365 Support Services and corresponds to a Microsoft best practice. This scenario is the optimal configuration for most medium to large enterprise organizations. Depending on the load, more servers may also be required for authentication. Considering the above, the AD FS deployment should be scaled to service all of the requests to online service and not only for the Office 365 portal, the SharePoint Online portals, and Outlook Web Apps (OWA) traffics.

The above infrastructure can be deployed either on-premises or in a hybrid model with some roles hosted on virtual machines in Microsoft Azure.

Note    For more information, see articles Deploy AD DS or AD FS and Office 365 with single sign-on and Azure Virtual Machines and Guidelines for Deploying Windows Server Active Directory on Azure Virtual Machines.

From an implementation perspective, one should note the followings.

Traditionally, a SSL/TLS certificate was bound to an IP address / port combination and thus a separate IP address was required to bind additional SSL/TLS certificates to the same port number.

Both AD FS and WAP are configured to use the Server Name Identification (SNI) method as per RFC 6066 Transport Layer Security (TLS) Extensions: Extension Definitions where SSL/TLS certificates can now be bound to host name / port combinations. You can view the certificate binding by running the following netsh command:

PS C:\> netsh http show sslcert

This implies to enable the SNI capability on the hardware load balancers, HTTP health probes, older browsers, etc.

If a non-SNI capable client has to be supported, you will have to create a fall-back certificate binding in HTTP.SYS that will consist in binding the SSL/TLS certificate on the IP wildcard and 443: 0.0.0.0:443

This applies to both the AD FS and the WAP servers.

The following Table 6 discusses the impact of SSL/TLS bridging. SSL/TLS bridging or termination is where the SSL/TLS channel is terminated on a device other than the WAP or AD FS server.

Table 6 SSL/TLS bridging

SSL/TLS Termination between

Possible

Impact

Client and WAP

Yes/No

Breaks Workplace join and client SSL/TLS authentication

WAP and AD FS

No

Breaks proxy trust with AD FS

Finally, you should not use sticky sessions on the load balancers.

Firewall-published AD FS scenario

An AD FS server (farm) services client requests through single sign-on authentication. A reverse proxy infrastructure exposes those core authentication services to the Internet.

Important note    Extended Authentication Protection (EAP) must be disabled on the AD FS server farm for this to work, which weakens the security profile of the system as described in the article Non-browser clients can't sign in after you set up AD FS in a "firewall-published" configuration. For a security standpoint, this is not recommended.

Also note that using a third-party reverse proxy requires the reverse-proxy to comply with the configuration details described in the article Using a Third-Party Proxy as a Replacement to an AD FS 2.0 Federation Server Proxy.

For this scenario to be supported by Office 365 Support Services, the following conditions must be true:

  • The reverse proxy of HTTPS (port TCP/443) traffic between the Internet client and the federation server must be transparent;
  • The federation server must receive a faithful copy of SAML requests from the Internet client;
  • Internet clients must receive faithful copies of SAML responses as though directly attached to the on-premises federation server.
Non-published AD FS scenario

An AD FS server (farm) services client requests through single sign-on authentication, and the server farm is not exposed to the Internet by any method.

An important limitation of this scenario would be that an Outlook rich clients cannot connect to Exchange Online resources as described in the article Federated users cannot connect to Exchange Online mailbox section § EAS basic auth/active profile authentication flow provides additional explanations on this.

Furthermore, Internet clients (including mobile devices) cannot use Office 365 resources. Consequently, one can understand that, for service level reasons, this is not a recommended scenario as it does not provide the fully-advertised suite of services that are supported by the single sign-on feature of Azure AD/Office 365. Under these circumstances, this scenario is however supported by Azure AD/Office 365 Support Services.

On-premises administrators must periodically refresh federation trust data manually by using the
Update-MSOLFederatedDomain
cmdlet of the Azure AD PowerShell V1 module (see section § Installing Azure AD PowerShell).

Note    This is applicable to ALL AD FS scenarios not only the non-published ones.

Note    For more information, please refer to the section entitled Update trust properties of the article Verify and manage single sign-on.

VPN-published AD FS Scenario

An AD FS server (farm) services client requests through single sign-on authentication, and the server or server farm is not exposed to the Internet by any method. Internet clients connect to and use AD FS server only through a virtual private network (VPN) connection to the on-premises network environment.

Unless Internet clients including mobile devices are VPN-capable, they cannot use the services in Office 365. For service level reasons, this is not recommended.

For this scenario to be supported by Azure AD/Office 365 Support Services, the following conditions must be true:

  • The client can connect to the AD FS service by DNS name through HTTPS (port TCP/443).
  • The client can connect to the Azure AD/Office 365 endpoints by DNS name using appropriate ports/protocols.
  • Single sign-on for VPN/Internet users is possible with this scenario, but it is not supported.

Likewise compared to the previous scenario, on-premises administrators must periodically refresh federation trust data manually by using the
Update-MSOLFederatedDomain
cmdlet of the Azure AD PowerShell V1 module (see section § Installing Azure AD PowerShell).

Building the AD FS infrastructure

Due to the number of planning options available and related settings to consider, providing a step-by-step guide for building the AD FS infrastructure or adapting an existing one is outside the scope of this paper. Nevertheless, we provide in the Part 2 (for the setup of the base configuration), Part 4 (bis), and Part 5 of this whitepaper complete step-by-step guides for a specific configuration to further illustrate some key elements.

We recommend a careful and parallel reading of the article Checklist: Use AD FS to implement and manage single sign-on that guides through complementary considerations.

Note    In addition to the above article, you can refer to the Active Directory Federation Services documentation for detailed information on AD FS.

Fulfilling the AD FS feature requirements

Active Directory Federation Services (AD FS) in Windows Server 2012 R2 is a Server Role. A fully integrated deployment with Server Manager is provided.

This paper takes into account the capabilities of AD FS as available with Windows Server 2012 R2 Update and discusses the associated requirements.

In addition, we also recommend you apply the update rollup 2955164 for Windows Server 2012 R2 or the hotfix 2948086.

Note    For additional detail, see the articles 2955164 and 2948086.

Group Managed Service Account (gMSA)

Introduced with Windows Server 2012 as an extension to standalone Managed Service Accounts, group Managed Service Account (gMSA) account have been made available to provide managed domain accounts that provide automatic password management and simplified SPN management, including delegation of management to other administrators. When building an AD FS Server Farm we recommend you to use a gMSA as the AD FS service account. The benefit of using a gMSA is its auto-negotiated password update feature. gMSA accounts require that at least one domain controller running Windows Server 2012 or greater.

Note    For more information, see the blog post New features in Active Directory Domain Services in Windows Server 2012, Part 8: Group MSAs (gMSAs).

The creation of this gMSA account can be handled during the AD FS install process.

Conversely, you can still leverage a standard service account that you create. In this latter case, you will need to set the required Service Principal Names (SPN) on the account for federation service (HOST/adfs.litware369.com), and ensure that private keys for the AD FS certificates allow read for this service account. You'd also need to handle the password lifecycle for such service account yourself manually.

Choosing the database model

In AD FS, configuration information is stored in a database. A stand-alone federation server stores its configuration information locally in the Windows Internal Database (WID).

Windows Internal Database (WID)

WID does not need to be installed manually; It is installed by the first application or service that requires it. WID runs on its own as a Windows service and is included with Windows Server 2012 and Windows Server 2012 R2. WID is a variant of SQL Server Express and is meant for on-box applications or services which need a SQL backend.

WID is read/write in a stand-alone federation server whereas in (load-balanced) federation server farm scenarios, the database is read/write on the primary federation server and read-only on all secondary federation servers in the farm. Secondary federation servers connect to and synchronize the data with the primary federation server in the farm by polling it at regular intervals to check whether data has changed. The secondary federation servers exist to provide fault tolerance for the primary federation server while acting to load-balance access requests.

Generally speaking, you will choose the WID database if your organization:

  • Has 100 or fewer configured trust relationships planned.
  • Do not require SAML token replay detection (or artifact resolution).
  • Do not have an existing SQL footprint.
  • Do not wish to use their existing SQL infrastructure.

Note    You can convert from WID to SQL Server later if necessary. For more detail, see article Windows Server 2012 R2 - AD FS: Migrate Your AD FS Configuration Database from WID to SQL Server.

SQL Server

Configuration information can alternatively be stored in a SQL Server database, which provides additional capabilities, like additional performance enhancements (including the ability to scale out using more than 10 federation servers, which is the limit for WID per farm), SAML token replay detection and SAML artifact resolution. AD FS in Windows Server 2012 R2 can be configured with SQL Server via the UI

Generally speaking, you will choose a SQL Server database if your organization:

  • Has existing licensing and servers for SQL Server. SQL Server 2008 and higher, including SQL Server 2012 and SQL Server 2014 are supported.
  • Want to use features of SQL Server with its AD FS database.
  • Has greater than 100 trust relationships planned.
  • Require security configuration for SAML token replay detection (or artifact resolution).

Note    With AD FS server role as part of Windows Server 2012 R2 the SQL Server supported versions are SQL Server 2008, SQL Server 2008 R2, SQL Server 2012 and SQL Server 2014. For more information, see article Federation Server Farm Using SQL Server.

Database fault tolerance and load balancing

If you opt for the WID database, manual intervention will be needed in case of the AD FS primary federation server failure. More specifically, you will have to run a PowerShell cmdlet to switch the primary federation server to one of the secondary federation servers that is still online:

PS> Set-ADFSSyncProperties -Role PrimaryComputer

Once the new primary federation server is set, you will then have to run the following PowerShell cmdlet on the other secondary federation servers to sync them with the new primary server:

PS> Set-ADFSSyncProperties -Role SecondaryComputer -PrimaryComputerName fqdn_primary_server

In comparison with SQL Server, no manual intervention is needed. All ADFS servers can read/write to the AD FS database as needed. Furthermore, one should note that the SQL merge replication support is provided for the ADFS configuration.

Verifying the AD FS configuration

The AD FS Diagnostics Module contains a series of cmdlets to gather configuration information of an AD FS server, as well as cmdlets to perform health checks to detect configuration issues based on common root causes identified during support engagements such as duplicate SPN, certificates not found, DNS records, etc.

You can download the AD FS Diagnostics Module and view PowerShell cmdlets examples in the article
AD FS Diagnostics Module.

Installing the prerequisites for the single sign-on (SSO)

Once the AD FS infrastructure is planned and/or build according to the selected implementation scenarios as per previous section, we can now move on to installing the Azure AD Connect tool.

Installing the Azure AD Connect tool

The Azure AD Connect tool aims at smoothing the onboarding process for connecting your on-premises AD infrastructure to Azure AD/Office 365. Azure AD Connect is a single wizard that performs all of the steps below in order to streamline and thus simplify the overall onboarding process:

To download the latest version of Azure AD Connect (e.g. version 1.1.380.0 as of this writing), proceed with the following steps:

  • Click Save.

Installing Azure AD PowerShell

There are two versions of the Azure AD V1 PowerShell module available: a General Availability (GA) version and a Public Preview version. The Public Preview version contains cmdlets that have not yet been released for General Availability.

To install the Azure AD V1 PowerShell module, proceed with the following steps:

Note    For more information, see article Azure ActiveDirectory (MSOnline).

At this stage, and as described in MSOnline Module, the Azure AD V1 PowerShell module installs a set of cmdlets specifically designed for Azure AD tenant-based administration. More specifically, the following cmdlets perform tasks related to the domain management that pertains to the seamless sign-in capabilities of Azure AD/Office 365.

Table 7 Windows PowerShell domain management cmdlets for Azure AD

Domain management cmdlet

Description

New-MsolFederatedDomain

Adds a new single sign-on domain to Azure AD/Office 365 and configures the relying party trust settings between the on-premises AD FS service and Azure AD/Office 365. Due to domain verification requirements, you may need to run this cmdlet several times in order to complete the process of adding the new single sign-on domain.

Convert-MsolDomainToStandard

Converts the specified domain from single sign-on to standard authentication. This process also removes the relying party trust settings in the AD FS service and Azure AD/Office 365. After the conversion, this cmdlet will convert all existing users from single sign-on to standard authentication. Any existing user who was configured for single sign-on will be given a new temporary password as part of the conversion process. Each converted user name and new temporary password will be recorded in a file for reference by the administrator. The administrator can then distribute the new temporary password to each converted user to enable the user to sign in to Azure AD/Office 365.

Convert-MsolDomainToFederated

Converts the specified domain from standard authentication to single sign-on, including configuring the relying party trust settings between the AD FS service and Azure AD/Office 365. As part of converting a domain from standard authentication to single sign-on, each user must also be converted. This conversion happens automatically the next time a user signs in; no action is required by the administrator.

Get-MsolFederationProperty

Gets key settings from both the AD FS service and Azure AD/Office 365. You can use this information to troubleshoot authentication problems caused by mismatched settings between the AD FS server and Azure AD/Office 365.

Get-MsolDomainFederationSettings

Gets key settings from Azure AD/Office 365. Use the Get-MsolFederationProperty cmdlet to get settings for both Azure AD/Office 365 and the AD FS service.

Remove-MsolFederatedDomain

Removes the specified single sign-on domain from Azure AD/Office 365 and the associated relying party trust settings in AD FS. If the domain specified has objects associated with it, you will not be able to remove the domain.

Set-MsolDomainFederationSettings

Is used to update the settings of a single sign-on domain.

Set-MsolADFSContext

Sets the credentials to connect to Azure AD/Office 365 and to the AD FS service. This cmdlet must be run before making other Single Sign-On cmdlet calls. If this cmdlet is called without parameters, the user will be prompted for credentials to connect to the different systems. When the AD FS service is used remotely, the user must specify the computer name of the primary AD FS server. Note that the specified logfile is shared by all single sign-on cmdlets for the session. A default logfile is created if one is not specified.

Update-MsolFederatedDomain

Changes settings in both the AD FS service and Azure AD/Office 365. It is necessary to run this cmdlet whenever the URLs or certificate information within AD FS change due to configuration changes or through regular maintenance of the certificates, such as when a certificate is about to expire. This cmdlet should also be run when changes occur in Azure AD/Office 365. To confirm that the information in the two systems is correct, the Get-MsolFederationProperty cmdlet can be used to retrieve the settings.

Setting up the single sign-on (SSO) with your tenant

The process consists in the following four steps:

  1. Adding the domain in the Azure AD/Office 365 tenant.
  2. Configuring the domain for single sign-on (federated).
  3. Verifying the domain status in the Office 365 portal.

Adding the domain in the Azure AD/Office 365 tenant

The first step in setting up the single sign-on feature of Azure AD/Office 365 consists in adding the on-premises Active Directory domain (e.g. litware369.com) to the Azure AD/Office 365 subscription.

Signing up for Office 365 automatically creates an Azure AD directory for the organization with a default domain (e.g. litware369.onmicrosoft.com). You can then add a verified vanity domain (e.g. litware369.com) in the subscription.

This verified vanity domain will be later federated with your on-premises Active Directory via the Azure AD Connect tool (or alternatively via the New-MsolFederatedDomain cmdlet).

As illustrated in the second part of this document, to add a domain, proceed with the following steps:

Note    For more information, see the article Add a custom domain name to Azure Active Directory.

  1. Open a browsing session and navigate to the Office 365 portal at https://portal.office.com.
  2. Sign in with your administrative credentials to your Office 365 subscription, i.e. the credentials created when you signed up for your cloud subscription.
  3. Click the Admin tile. The Office 365 admin center opens up in a new tab.
  4. In Domains, click Add a domain to start the setup wizard.
  5. Follows the three main steps:
    1. Add a domain, for example litware369.com in our illustration.
    2. Verify a domain with the public domain registrar. To verify the ownership of the vanity domain, a verification information should be created in your domain registrar. The information to add consists in a TXT record, for example in our configuration:

    Alias or host: litware369.com

    Value: MS=ms58060785

    TTL: 1 hour

    1. Update DNS settings with the domain registrar. You're invited to update the DNS settings once the above DNS record has been successfully created at your registrar (or on your external DNS zone) to confirm that you own the domain and properly propagated through the DNS environment.

Note    DNS replication can take some time as it depends on the DNS zone settings but also involve the update of DNS content cache on the DNS servers used throughout the DNS query from the service), you're invited to update the DNS settings.

After the above steps are completed, the domain is added correctly.

  1. Click Finish.

Configuring the domain for single sign-on (federated)

The configuration of the domain for single sign-on is managed by the aforementioned Azure AD Connect tool.

As mentioned before, Azure AD connect encompasses for that domain scope the directory synchronization setup, the trust relationship configuration (along with possibly the deployment of the AD FS infrastructure if needed) between the on-premises identity infrastructure and the Azure AD/Office 365. It completes with the sync of the targeted users.

Before executing Azure AD Connect for configuring the domain for single sign-on, you must know the credentials:

  • A domain account that is local administrator on the aforementioned computers.
  • Active Directory enterprise administrator credentials.
  • Azure AD tenant global administrator credentials.

To execute Azure AD Connect and configure your on-premises identity infrastructure, proceed with the following steps:

  • Run the previously downloaded AzureADConnect.msi file to launch the wizard.

  • Follow the various steps. The remaining parts, i.e. Part 4 (bis), and Part 5, of this paper guides you through the details of the configuration to complete the setup of the federated domain with the AD FS infrastructure.

As part of the above configuration for single sign-on, the domain will be converted from a managed domain to a federated domain.

This will also upload the public key for the certificate used for AD FS token signing as well as advertise the claims and domain(s) to be federated. If there are ever any changes to the AD FS configuration (including an AD FS server's certificate renewal), you will have to update the configuration again which is explained later in this paper.

When the domain is configured as a federated domain, you will no longer have the option to specify the domain name litware369.com and confirm ownership. The users will need to be created on-premises in order for them to have the federated domain name available to them. You can still create accounts directly in the cloud, for example in the default domain litware369.onmicrosoft.com, but they cannot have the federated domain name litware369.com assigned to them unless they are created on-premises.

Verifying the domain health status in the Office 365 portal

Once the domain is successfully added, its health can later be checked directly from the portal.

To verify the domain health status, proceed with the following steps:

  1. Open a browsing session if none and navigate to the Office 365 portal at https://portal.office.com.
  2. Sign in with your administrative credentials to your Office 365 subscription, i.e. the credentials created when you signed up for your cloud subscription.
  3. Click the Admin tile. The Office 365 admin center opens up in a new tab.
  4. In Domains, click Check health. A new pane opens up.
  5. Type or click the name of the domain to verify. Its health status is then displayed in a pane:

Verifying the single sign-on (SSO) with your Azure AD/Office 365 tenant

For the sake of simplicity and in order to concentrate on the aspects of the configuration that closely relates to AD FS, the verification here implicitly requires the completion of the directory synchronization with the on-premises identity infrastructure (and maybe IdFix in addition to that).

The end-to-end illustration provided in the remaining parts of this whitepaper covers the setup of the directory synchronization and the sync with the on-premises infrastructure with Azure AD Connect.

As suggested in the article Verify and manage single sign-on with AD FS, it is always best when verifying (and/or) troubleshooting the single sign-on to keep it as simple as possible. Even if an encountered issue concerns Skype for Business or Exchange Online access, it is best just accessing the Office 365 portal with the on-premises credentials to verify if the single sign-on is working. This will allow you to verify if the issue is application/service specific or if the issue is with single sign-on. If the user can log in to the Office 365 portal but cannot log into OWA with the corporate credentials then you can be sure the issue is not related to single sign-on.

To verify the single sign-on, proceed as follows:

  1. Open a browsing session from your local computer, here a Windows 10 machine, and then navigates to https://portal.office.com to access the Office 365 portal. You will see you are immediately redirected to the login.microsoftonline.com URL which is the Identity Provider for Office 365.

  1. Type your end-user's identity (UPN) in User ID.
  2. Click inside Password. This triggers a home realm discovery (HRD) process for federated identities to see if the domain part of the UPN is federated.

Note    If you turn on HTTP tracing on IE or observe the traffic via a tool like the Telerik Fiddler
HTTP trace application, you can see that the login.microsoftonline.com URL is calling GetUserRealm as part of the home realm discovery (HRD) process. You will also notice that their results show the AD FS passive endpoint information (see section § Endpoints).

Note    Fiddler can intercept HTTPS traffic (from within the calling Internet Browser session) and creates for that purpose a certificate that represents the destination website. The browser will display this certificate as invalid unless it's added to certificate store. It should be removed after testing. Furthermore, as already discussed, and depending on the client, Channel Binding Token (CBT) will be enforced to prevent Man-in-the-middle attacks and authentication will fail. You can consequently temporarily disable CBT on the AD FS server for Fiddler SSL/TLS interception with the following command:

Set-ADFSProperties –ExtendedProtectionTokenCheck:None

Fiddler can alternatively be configured to inject the user credentials into the SLL/TLS channel between fiddler and the destination server. For more information, see the article Configure Fiddler to Authenticate to CBT-Protected Server on the Telerik web site.

  1. If single sign-on is correctly set up, you will notice that the user cannot even type here password assuming this is i) a domain-joined machine and ii) connected to the corporate network. Anything else may fail (if WAP is not deployed) or you would get the form-based access web user interface instead.

If single sign-on is correctly set up, you should be automatically redirected to the AD FS farm, and then - after a successful (seamless)s authentication - redirected back to the Office portal where you're first invited to provide additional information.

At the end of the process, you should have a seamless access to the signed in user settings in the Office 365 portal.

No tiles are displayed for the online apps. This is expected for the test user as in fact you have not assigned a license to the test user.

Leveraging the password sync backup for the single sign-on (SSO)

Previous sections illustrate the basics on how to setup the federated identity model with AD FS. As noticed before, implementing this model requires in the long run not only deploy and operate but also maintain a highly available fault-tolerant AD FS infrastructure to deliver the single sign-on (SSO).

Nevertheless, if for some reasons the AD FS service becomes unavailable, you can leverage a temporally switch from single sign-on to synchronized password hash for sign-in for the duration of the incident, thanks to the Azure AD support of password as a temporary backup for the single sign-on.

This switch can be made through a "namespace conversion" via the Azure AD Connect tool where the targeted domain will be converted from the Federated to Managed state.

To convert the, proceed with the following steps:

  • Launch the Azure AD Connect wizard.

  • Click Configure.

  • The Optional features page lists the tasks that are relevant to your configuration. Select the Change user sign-in task, and then click Next.
  • Specify the credentials of an Azure AD/Office 365 global administrator

  • Select Password Synchronization and check Do not convert user accounts, optionally check Enable seamless single sign-on (see part 6 of this whitepaper For more information), and then click Next. Follow the instructions to configure password synchronization and complete the wizard.

The Convert-MsolDomainToStandard cmdlet can alternatively be used with the switch -SkipUserConversion $true.

Note    If your AD FS infrastructure is serving multiple domain namespaces you'd have to replicate this operation on a domain per domain basis.

Switching from single sign-on to use synchronized passwords hash for sign-in is not instantaneous. This will impact all users belonging to the domain and necessitate that all passwords be synchronized before the change. This change must not be initiated if you think that the AD FS service can be returned live in a relatively short delay: such a command takes as an estimated effective time 2 hours plus 1 additional hour per 2,000 users to complete.

Updating any changes to the AD FS configuration

There are a lot of instances when Azure AD should be updated with new settings from the AD FS infrastructure.

As notably discussed in the KB article 2647048, following is a list of the common issues that will require to update the information:

  • The SSL/TLS certificate expires on the AD FS server(s) and/or (load-balanced) web application proxy (typically every year).
  • A new certificate is issued to the AD FS server(s) and/or (load-balanced) web application proxy.
  • The AD FS implementation scenario has evolved.
  • The URL of an AD FS server's endpoint has changed.
  • There are any mismatches with the certificate(s) or the configuration itself. Users with a federated identity may get the following error when using corporate credentials to access Azure AD/Office 365: "There was a problem accessing the site. Try to browse to the site again."
  • Etc.

To address all of the issues the on-premises information needs to be consistent with the information in Azure AD by updating the current configuration information. If any part of the metadata of AD FS changes on-premises, the trust relationship with Azure AD may be completely broken, causing outages which could be company-wide for the tenant (which would prevent end-users for accessing any of their Office 365 services).

From a configuration perspective, federation metadata from the AD FS infrastructure, such as token-signing certificate, federation service name, and federation service identifier, are synchronized with Azure AD once during initial conversion of the tenant domain to a federated type. (See section § Setting up the single sign-on (SSO) with your tenant)

In addition, if the AD FS federation metadata are reachable from the Internet – this is the default configuration when the web application proxy is deployed -, Azure AD will periodically scan and update the trust information automatically from the AD FS infrastructure in its configuration. However, this Azure AD pulling mechanism is only handling the certificates. This is especially relevant when token signing certificate changes occur.

Consequently:

  • If the AD FS federation metadata endpoint is not reachable from the Internet,

- and/or -

  • If the changes cover other metadata items, such as the URL of the AD FS server's endpoint to something else, or change the federation brand name,

You need to manually update the configuration by proceeding as follows:

  1. Connect Windows PowerShell to Windows Azure AD.
  2. Run the command Update-MsolFederatedDomain –DomainName <domain name>.

You would need a script in order to push the configuration information update(s) to Azure AD on a regular basis. The Microsoft Office 365 Federation Metadata Update Automation Installation Tool can be used instead to automate the update of the Azure AD/Office 365 federation metadata regularly to ensure that any changes configured in the AD FS server are replicated to Azure AD automatically.

This tool runs as a scheduled task, securely storing Azure AD credentials in Credential Manager on an AD FS server, and it periodically pushes new metadata to Azure AD to avoid or minimize outages due to production metadata changes. Run the above command

To automatically update the configuration, proceed as follows:

  1. Log in to an AD FS server as an administrator.
  2. Download the text file O365-Fed-MetaData-Update-Task-Installation.ps1 from the online gallery, and save the file on the Desktop of the AD FS server.
  3. Right-click the newly downloaded file O365-Fed-MetaData-Update-Task-Installation.ps1, click Properties, click Unblock in the General tab, and click OK.
  4. From the Start menu, launch an administrative Windows PowerShell window.
  1. Run the following command and press Y so you are able to execute scripts on the server:
PS C:\> Set-ExecutionPolicy Unrestricted

  1. Execute the .ps1 file you saved in step 2.
PS C:\>.\O365-Fed-MetaData-Update-Task-Installation.ps1

  1. Type your global administrator account and password such as:

    Username: admin@litware369.onmicrosoft.com

    Password: ****************

    If you successfully enter your online credential, you will see the following message:

    Success

    Added MSOL credentials to the local Credential Manager

  2. Type the password for the currently logged on administrator.
  3. The tool will proceed through to the finish.

The specified Azure AD credentials are securely stored on the AD FS server so that the Azure Active Directory Module for Windows PowerShell cmdlets can be executed as a scheduled task in order to keep the metadata between the on-premises AD FS server and Azure AD/Office 365 fresh.

To see the MSOL credentials, proceed as follows:

  1. Open the Credential Manager from the Control Panel.
  2. Select Windows Credentials, and see the new generic credential named Microsoft-Office365-Update-MSOLFederatedDomain.

  1. Close Credential Manager.

To see the created scheduled task, proceed as follows:

  1. Launch the Task Scheduler from the Tools menu in Server Manager.
  2. Select the Task Scheduler Library and view the task in the list named Microsoft-Office365-Update-MSOLFederatedDomain

  1. Notice that this task runs every day at midnight.
  2. The task runs as your administrator account you specified in the tool.
  1. The action that it performs is:
C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe –command C:\Office365-Scripts\Microsoft-Office365-Update-MSOLFederatedDomain.ps1
  1. Minimize Task Scheduler.
    1. Explore to C:\Office365-Scripts.
    2. Notice the .ps1 file named Microsoft-Office365-Update-MSOLFederatedDomain.ps1 and the log file named History.log.
    3. Open History.log, and you will see where the tool was installed.

Understanding how single sign-on (SSO) works in Azure AD/Office 365

This section aims at providing additional information on the configuration established via Azure AD Connect in order to setup single sign-on. It focuses on an explanation of the resulting settings on AD FS as well as the several types of interaction between the key components involved in the transaction, i.e. the client, the on-premises AD FS infrastructure, the Office 365 Identity Platform (i.e. Azure AD and its sign-in service), and the services in Office 365.

A quick recap on the AD FS claims pipeline and engine

As previously described, an AD FS server is a Security Token Service (STS) that relies on a claims-based model. In this model, the claims pipeline represents the path that claims must follow through the federation service before they can be issued as part of a SAML token.

Note    For additional detail on the claims pipeline, see article
The Role of the Claims Pipeline
.

The federation service manages the entire end-to-end process of flowing claims through the various stages of the claims pipeline, which also includes the processing of different claim rule sets by the claim rule-based engine.

Note    For additional detail on the claim rule-based engine, see article
The Role of the Claims Engine
.

The claim engine handles three primary tasks that relate to a specific stage of the claims pipeline:

  1. Accepting incoming claims from a claim provider if any (Acceptance Rules),
  2. Authorizing claims requesters (Authorization Rules),
  3. Issuing outgoing claims to a relying party (Transform Rules).

Figure 9 AD FS server Claims pipeline

Besides the claim engine, which processes the claim rules as part of the claims pipeline, the AD FS configuration has 3 main relationships to control this entire function:

  1. Attribute Store. This is where the AD FS server queries attributes in order to source claims. If Active Directory Domain Services (AD DS) is declared by default, the AD FS server can also use attributes coming from several other attribute stores, such as Active Directory Lightweight Directory Services (AD LDS), Microsoft SQL Server databases, and other data sources.
  2. Claim Provider Trust. This is where the federation trust between the AD FS server and the Claim provider is configured. Based on a set of rules called the Acceptance Transform Rules, the claims from the claims provider will be filtered or pass-through to the Relying Party Trust in the context of the transaction. The on-premises Active Directory is the claims provider about single sign-on with Azure AD/Office 365.
  3. Relying Party Trust. This is where the federation trust between the AD FS server and the relying party is configured. Here, the federation service controls which users have access to the relying party based on the Issuance Authorization Rules, and then it issues claims to the relying party based on Issuance Transform Rules. The Office 365 Identity Platform (i.e. Azure AD) is the relying party about single sign-on with Office 365. Conversely, you can say that, in Office 365, Exchange Online, SharePoint Online, etc. are the relying parties of the Office 365 Identity Platform.

Understanding the AD FS configuration

Claim descriptions

The SAML 1.1 logon token issued by the AD FS servers to the Microsoft Office 365 Identity Platform relying party contains claims sourced from the on-premises Active Directory claims provider (see next section) that allows Azure AD to match the user to a shadow identity in the cloud:

  • The User Principle Name (UPN) of the corporate user, which is tied to the provisioned value for the user (that the directory synchronization engine will flow from on-premises Active Directory to Azure AD/Office 365).
  • A unique, rename-safe (Immutable) identifier for the user, which must remain constant for the lifetime of the object in the cloud. This otherwise could lead to duplicate objects and unexpected synchronization errors.

With a single-forest Active Directory configuration the ImmutableID attribute is by default set to the on-premises Active Directory Object GUID (ImmutableID). The Object GUID ByteArray is converted into Base64 string.

Consequently, and for that specific purpose, you can see the following 2 claim descriptions:

  • UPN (http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn).
  • Source user ID (http://schemas.microsoft.com/LiveID/Federation/2008/08/ImmutableID).

On-premises Active Directory claims provider trust

The following rules are declared for the Acceptance Transform Rules set regarding the Active Directory attribute store.

The incoming claim types are as follows:

  • Windows account name (http://schemas.xmlsoap.org/ws/2008/06/identity/claims/windowsaccountname),
  • Name (http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name),
  • Primary SID (http://schemas.xmlsoap.org/ws/2008/06/identity/claims/primarysid),
  • Group SID (http://schemas.xmlsoap.org/ws/2008/06/identity/claims/groupsid),
  • Primary group SID (http://schemas.xmlsoap.org/ws/2008/06/identity/claims/primarygroupsid),
  • Deny only group SID (http://schemas.xmlsoap.org/ws/2005/05/identity/claims/denyonlygroupsid),
  • Deny only primary SID (http://schemas.xmlsoap.org/ws/2008/06/identity/claims/denyonlyprimarygroupsid),
  • Deny only primary group SID (http://schemas.xmlsoap.org/ws/2008/06/identity/claims/denyonlyrpimarygroupsid),
  • Enhanced Key Usage (http://schemas.microsoft.com/2012/12/certificatecontext/extension/eku).

Microsoft Office 365 identity platform relying party trust

The creation of the domain as a federated domain with the Azure Active Directory module cmdlets (see section § Setting up the single sign-on (SSO) with your tenant) results in the automated definition of a new Microsoft Office 365 Identity Platform relying party trust.

Properties

The Monitoring tab of the Microsoft Office 365 Identity Platform properties shows the URL from where the Office 365 sign-in service metadata are retrieved: https://nexus.microsoftonline-p.com/federationmetadata/2007-06/federationmetadata.xml.

Both Monitor relying party and Automatically update relying party are checked. This shows that the trust definition leverages the AD FS capability to monitor the relying party metadata and to automatically update the trust definition information to reflect the relying party current settings in its configuration. (AD FS supports auto update based on the federation metadata URL.)

"If federation is broken. It's PKI. If it is not PKI, there's a typo. If you typed it correctly (case counts!). It's PKI"

Laura E. Hunter

This seamlessly takes into account any change that occurs on the Azure AD side. Such a capability greatly lessens the administrative effort to maintain the relying party trust on the AD FS server side.

This should always be enabled as illustrated here.

Note    The only reason you may not do this is when the AD FS server does not have outbound connectivity to the Internet. This is very rare. In this state, you will be responsible to make AD FS updates if the end point URL's for Azure AD change.

In the case where the auto-update of the relying party is not selected and you want you update it manually you should consider using:

  • The Update-MsolFederatedDomain cmdlet to manually,

-or-

  • The Microsoft Office 365 Federation Metadata Update Automation Installation Tool to automatically,

Update the trust information, i.e. the federation metadata, when information changes on the AD FS infrastructure side and to reflect it on the Azure AD side (see section § Updating any changes to the AD FS configuration).

The Office 365 sign-in service metadata are as follows. The general syntax and semantics of metadata are defined in the OASIS Web Services Federation Language (WS-Federation) Version 1.2.

<?xml version="1.0" encoding="utf-8"?>
<EntityDescriptor wsu:Id="0c0d1ca7-7292-4bc6-801c-f880f6098f4e"
entityID="urn:federation:MicrosoftOnline"
xmlns="urn:oasis:names:tc:SAML:2.0:metadata"
xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
<RoleDescriptor xsi:type="fed:SecurityTokenServiceType"
protocolSupportEnumeration="http://schemas.xmlsoap.org/ws/2005/02/trust http://docs.oasis-
open.org/wsfed/federation/200706"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:fed="http://docs.oasis-open.org/wsfed/federation/200706">
<KeyDescriptor use="signing" wsu:Id="stscer">
<KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#">
<X509Data>
<X509Certificate>MIIDYDCCAkigAwIBAgIJALLJPAyvf2sjMA0GCSqGSIb3DQEBBQUAMCkxJzAlBgNV
BAMTHkxpdmUgSUQgU1RTIFNpZ25pbmcgUHVibGljIEtleTAeFw0xNDA3MTgxOTUz
NDBaFw0xOTA3MTcxOTUzNDBaMCkxJzAlBgNVBAMTHkxpdmUgSUQgU1RTIFNpZ25p
bmcgUHVibGljIEtleTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBANYD
KgByFZdqtTnnpF4IfIp4i2XLg2rLIo+mu4DmW9gRLlBJCNc7YESUxpKzuFYaANd8
fWsDigJZTXbhOQApSpw4xXFnor2vJ1zm94LtqjcVEXTjUml5gAIS4pwuOU3ZfO/0
eTG0gDYp4a0L/mzzTRsnwe/8WMPIE75Bq2zAyAZ9aePvl3QX7cXYLPfeK4QTgK3B
5lwe1wWu3y5oQidjcSok8Frf80xzuCYuOa+ZUK3JibpLLCrT4uwiqf+KREDSdc4b
PPlq0PWI4sQr1tha8yypRSvOH+/MxcfSRSnl6Uc+gm8nVEEWWIu4hhu6NIfG91mM
UqJuzkgLCi6Gov6JS8UCAwEAAaOBijCBhzAdBgNVHQ4EFgQUnQoq7sI3R8rde4sQ
s6nGEbJm3LcwWQYDVR0jBFIwUIAUnQoq7sI3R8rde4sQs6nGEbJm3LehLaQrMCkx
JzAlBgNVBAMTHkxpdmUgSUQgU1RTIFNpZ25pbmcgUHVibGljIEtleYIJALLJPAyv
f2sjMAsGA1UdDwQEAwIBxjANBgkqhkiG9w0BAQUFAAOCAQEAf4jaNhKzRG3k+52W
oM9nnISP7rlWIeWwH6EQGUlF6ozSP/03gYMAdqpdhww5zNwKzi7TQVbDC0pgq/tq
zHv6JEI0R4B6h7/TJ1pYPxdvIFQrE27RHESltH/m+5UkVnayLqRD3/fi4zf4aEpx
SDZ73MCR5LanPGqvlAMz29AL3g1ynj+eu7xMfFsM/8+qJaCXuxT5/30eeLEe+Pyi
kA/PhEwp+qkDQWPvdAwEghuUaFvtKAgDZierjpGzHZnYkXTTDTHVe1iP7tsAJH5q
K3qdcv3UGPyZrjC/lietJcAcnwVoZQ93v2ieGfcKKN+PFN9M59/BkPo62HPoGNNx
2ZDQaQ==
</X509Certificate>
</X509Data>
</KeyInfo>
</KeyDescriptor>
<KeyDescriptor use="signing" wsu:Id="stsbcer">
<KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#">
<X509Data>
<X509Certificate>MIIDYDCCAkigAwIBAgIJAKLDsqkylLefMA0GCSqGSIb3DQEBBQUAMCkxJzAlBgNV
BAMTHkxpdmUgSUQgU1RTIFNpZ25pbmcgUHVibGljIEtleTAeFw0xNDEwMTAxODE2
MTNaFw0xOTEwMDkxODE2MTNaMCkxJzAlBgNVBAMTHkxpdmUgSUQgU1RTIFNpZ25p
bmcgUHVibGljIEtleTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAM7A
3m6uvOxEsX+NlB1hnflaR8DJj597wY3qyh/FX4O6rKvU2leAfINmBWcjEFApCKi9
p5uIaZpNlDpPQ+R3BaZx+4NhHbOMpeWlpIiZHL61lwbulzurffUPhtzQNHAVzOBk
ZsOgN9BD/hOleU//d+IXz08ateUb3Ip2vyaodilYQDDi5M9yOhanv1cO1Usjo2xT
LfiK+TVygu+8bo+/8JHGPRy6pnghng970DRBDkVrKzozlrnmMesdSrtuCnsgyRbE
XckxaQ8S2nDYyFqBI0PkcBW8+0akdFWW58Os5cGbPFeHi6vtZCR5pWw5pnqtuoip
rdk9jg1axT3vwu+RVdcCAwEAAaOBijCBhzAdBgNVHQ4EFgQUBjNylGJBvkAY/4yI
IoD00R6p5hIwWQYDVR0jBFIwUIAUBjNylGJBvkAY/4yIIoD00R6p5hKhLaQrMCkx
JzAlBgNVBAMTHkxpdmUgSUQgU1RTIFNpZ25pbmcgUHVibGljIEtleYIJAKLDsqky
lLefMAsGA1UdDwQEAwIBxjANBgkqhkiG9w0BAQUFAAOCAQEAQGZUlJ3zzJvy1Old
tV3NTYHlbVHm3Fty17xqW9Ui8GE8sEWeUdHA6eURNNpNpd+gAGC6Tp+k+cU1LlPw
Xm7BAATJ/2DjY8tzRc6r6EneQWRkIa8xpbvknXvUml6iFgo2ofOWLaFk6XpQ64MA
O35wv9XEARNabJ9wJSRSevUigAx2U2GvaorV5PgqHImiKTSrL0K6j8B4OqXWUqP0
KGf7pCdGlrq2XEl95N2zj8n/scvA9JasImztsVlZ+WxeF+OAMvWQQFc54gC6lwWc
8kno8vPn3lwxVkTU0o9wcHnOhNi2hzVDV85sz7P9dOZYF73uy1uLshdjCcwlmQ2l
A9OV9w==
</X509Certificate>
</X509Data>
</KeyInfo>
</KeyDescriptor>
<fed:ClaimTypesOffered>
<auth:ClaimType Uri="http://schemas.xmlsoap.org/claims/EmailAddress"
Optional="True"
xmlns:auth="http://docs.oasis-open.org/wsfed/authorization/200706">
<auth:DisplayName>Email Address</auth:DisplayName>
</auth:ClaimType>
<auth:ClaimType Uri="http://schemas.xmlsoap.org/ws/2006/12/authorization/claims/action"
Optional="True"
xmlns:auth="http://docs.oasis-open.org/wsfed/authorization/200706">
<auth:DisplayName>Action for which the token is valid</auth:DisplayName>
</auth:ClaimType>
<auth:ClaimType Uri="http://schemas.microsoft.com/ws/2006/04/identity/claims/RequestorDomain"
Optional="True"
xmlns:auth="http://docs.oasis-open.org/wsfed/authorization/200706">
<auth:DisplayName>Domain name of the entity that requested the token on behalf of the user</auth:DisplayName>
</auth:ClaimType>
<auth:ClaimType Uri="http://schemas.microsoft.com/ws/2006/04/identity/claims/ThirdPartyRequested"
Optional="True"
xmlns:auth="http://docs.oasis-open.org/wsfed/authorization/200706">
<auth:DisplayName>Indicates this token was not requested directly by the user.</auth:DisplayName>
</auth:ClaimType>
</fed:ClaimTypesOffered>
<fed:TokenTypesOffered>
<fed:TokenType Uri="urn:oasis:names:tc:SAML:1.0"/>
</fed:TokenTypesOffered>
<fed:MexEndpoint>
<EndpointReference xmlns="http://www.w3.org/2005/08/addressing">
<Address>https://login.microsoftonline.com/login.srf</Address>
</EndpointReference>
</fed:MexEndpoint>
<fed:PassiveRequestorEndpoint>
<EndpointReference xmlns="http://www.w3.org/2005/08/addressing">
<Address>https://login.microsoftonline.com/login.srf</Address>
</EndpointReference>
</fed:PassiveRequestorEndpoint>
</RoleDescriptor>

<RoleDescriptor xsi:type="fed:ApplicationServiceType"
protocolSupportEnumeration="http://schemas.xmlsoap.org/ws/2005/02/trust http://docs.oasis-
open.org/wsfed/federation/200706"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:fed="http://docs.oasis-open.org/wsfed/federation/200706"
xmlns:mfg="urn:microsoft:live:federation">
<fed:TargetScopes>
<EndpointReference xmlns="http://www.w3.org/2005/08/addressing">
<Address>https://login.microsoftonline.com/extSTS.srf</Address>
</EndpointReference>
</fed:TargetScopes>
<fed:ApplicationServiceEndpoint>
<EndpointReference xmlns="http://www.w3.org/2005/08/addressing">
<Address>https://login.microsoftonline.com/extSTS.srf</Address>
</EndpointReference>
</fed:ApplicationServiceEndpoint>
<fed:PassiveRequestorEndpoint>
<EndpointReference xmlns="http://www.w3.org/2005/08/addressing">
<Address>https://login.microsoftonline.com/login.srf</Address>
</EndpointReference>
</fed:PassiveRequestorEndpoint>
<mfg:FederationMetadataPutEPR>
<EndpointReference xmlns="http://www.w3.org/2005/08/addressing">
<Address>https://api.login.microsoftonline.com/pksecure/ProvisionTrustPK.srf</Address>
</EndpointReference>
</mfg:FederationMetadataPutEPR>
</RoleDescriptor>

<Signature xmlns="http://www.w3.org/2000/09/xmldsig#">
<SignedInfo>
<CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
<SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/>
<Reference URI="#0c0d1ca7-7292-4bc6-801c-f880f6098f4e">
<Transforms>
<Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
<Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
</Transforms>
<DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
<DigestValue>UAyBJk7D/VsCEoOG0HsDbiGlrk8=</DigestValue>
</Reference>
</SignedInfo>
<SignatureValue>QW0N4pfVALkCbJEIzx1bKQGRUtTyDPx54tqd3xe4/vFyvgvSHb9lLueskaTar4VkYxM9z
fKKvhfhkTp3Oq9rAPKyOa4Ouvru7EK4d8mtiRlyOVVwg987x5LmjdwykH1r1lysV/xJzD
cIWb0Kt9AiDWSV+npqLbOe1WgXmiN4n4K/gl8RIc63niQhomqDFp1UgMP/CyWtQAfXRNG
dWPh28Pidp2LHNA/XWMBB+2X5604eDsL/FLqhbMXL788yTNkLufc5yq+7LPl50D57MO8h
7gvVaVKL+uWeU6zW19cogoqkCT8VdnDGlcdSVzp6iIXGRMJslvZ2ce2KtNyAi3tr2g==
</SignatureValue>
<KeyInfo>
<X509Data>
<X509Certificate>MIIDYDCCAkigAwIBAgIJALLJPAyvf2sjMA0GCSqGSIb3DQEBBQUAMCkxJzAlBgNV
BAMTHkxpdmUgSUQgU1RTIFNpZ25pbmcgUHVibGljIEtleTAeFw0xNDA3MTgxOTUz
NDBaFw0xOTA3MTcxOTUzNDBaMCkxJzAlBgNVBAMTHkxpdmUgSUQgU1RTIFNpZ25p
bmcgUHVibGljIEtleTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBANYD
KgByFZdqtTnnpF4IfIp4i2XLg2rLIo+mu4DmW9gRLlBJCNc7YESUxpKzuFYaANd8
fWsDigJZTXbhOQApSpw4xXFnor2vJ1zm94LtqjcVEXTjUml5gAIS4pwuOU3ZfO/0
eTG0gDYp4a0L/mzzTRsnwe/8WMPIE75Bq2zAyAZ9aePvl3QX7cXYLPfeK4QTgK3B
5lwe1wWu3y5oQidjcSok8Frf80xzuCYuOa+ZUK3JibpLLCrT4uwiqf+KREDSdc4b
PPlq0PWI4sQr1tha8yypRSvOH+/MxcfSRSnl6Uc+gm8nVEEWWIu4hhu6NIfG91mM
UqJuzkgLCi6Gov6JS8UCAwEAAaOBijCBhzAdBgNVHQ4EFgQUnQoq7sI3R8rde4sQ
s6nGEbJm3LcwWQYDVR0jBFIwUIAUnQoq7sI3R8rde4sQs6nGEbJm3LehLaQrMCkx
JzAlBgNVBAMTHkxpdmUgSUQgU1RTIFNpZ25pbmcgUHVibGljIEtleYIJALLJPAyv
f2sjMAsGA1UdDwQEAwIBxjANBgkqhkiG9w0BAQUFAAOCAQEAf4jaNhKzRG3k+52W
oM9nnISP7rlWIeWwH6EQGUlF6ozSP/03gYMAdqpdhww5zNwKzi7TQVbDC0pgq/tq
zHv6JEI0R4B6h7/TJ1pYPxdvIFQrE27RHESltH/m+5UkVnayLqRD3/fi4zf4aEpx
SDZ73MCR5LanPGqvlAMz29AL3g1ynj+eu7xMfFsM/8+qJaCXuxT5/30eeLEe+Pyi
kA/PhEwp+qkDQWPvdAwEghuUaFvtKAgDZierjpGzHZnYkXTTDTHVe1iP7tsAJH5q
K3qdcv3UGPyZrjC/lietJcAcnwVoZQ93v2ieGfcKKN+PFN9M59/BkPo62HPoGNNx
2ZDQaQ==
</X509Certificate>
</X509Data>
</KeyInfo>
</Signature>
</EntityDescriptor>

The second RoleDescriptor element corresponds to the relying party role of Azure AD in which we are interested.

This element defines 2 endpoints for Azure AD for the interaction with the organization's on-premises infrastructure:

  1. A passive endpoint for Web clients (browser): https://login.microsoftonline.com/login.srf.
  2. An active endpoint for smart clients: https://login.microsoftonline.com/extSTS.srf.
Issuance transform rules

The automated definition of the trust creates 2 custom rules in the Issuance Transform Rules set.

These 2 rules are defined as follows:

  1. First custom rule (Active Directory: UPN & ImmutableID). By querying Active Directory based on the user logon name, this rule retrieves:
  • The UPN claim: UPN of the user tied to the provisioned value for the user;
  • The ImmutableID claim: Unique, rename-safe (a.k.a. immutable) identifier of the user tied to provisioning of the user.

This rule enables sourcing the UPN and ImmutableID attribute elements of the attribute statement element in the issued SAML 1.1 logon token as illustrated hereafter.

c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname"]
=> issue(store = "Active Directory", types = ("http://schemas.xmlsoap.org/claims/UPN",
"http://schemas.microsoft.com/LiveID/Federation/2008/05/ImmutableID"), query = "samAccountName={0};userPrincipalName,objectGUID;{1}", param = regexreplace(c.Value, "(?<domain>[^\\]+)\\(?<user>.+)", "${user}"), param = c.Value);
  1. Second custom rule (ImmutableID to NameID). This second rule transforms the ImmutableID claim into a SourceID claim.

This rule enables sourcing the subject element of the attribute statement element in the issued SAML 1.1 logon token as illustrated hereafter.

c:[Type == "http://schemas.microsoft.com/LiveID/Federation/2008/05/ImmutableID"]
=> issue(Type = "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier",
Value = c.Value, Properties["http://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties/format"] =
"urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified");

The resulting SAML 1.1 logon token looks as follows. This XML-based signed token is a so-called "bearer" token, a short-lived bearer token (i.e. without a proof of possession) that is issued by the AD FS server to Azure AD.

Such a token includes both an attribute statement and authentication statement:

  • Attribute statement. It asserts that the subject identified here by a NameID (ImmutableID) is associated with certain claims (UPN and ImmutableID in our context). Claims are provided as a string name-value pair;
  • Authentication statement. It asserts that the security principal, i.e. the subject, has been authenticated by the AD FS server at a particular time using a particular method of authentication: AuthenticationMethod="urn:oasis:names:tc:SAML:1.0:am:password";

The general syntax and semantics of SAML 1.1 tokens are defined in the core specification of the OASIS SAML standard Assertions and Protocols for the OASIS Security Assertion Markup Language (SAML) V1.1.

<saml:Assertion MajorVersion="1" MinorVersion="1" AssertionID="_55b4b481-da5e-49fa-a8f2-af3198cbd1b3"
Issuer="http://adfs.litware369.com/adfs/services/trust"
IssueInstant="2015-06-10T15:53:38.976Z"
xmlns:saml="urn:oasis:names:tc:SAML:1.0:assertion">
<saml:Conditions NotBefore="2015-06-10T15:53:38.960Z" NotOnOrAfter="2015-06-10T16:53:38.960Z">
<saml:AudienceRestrictionCondition>
<saml:Audience>urn:federation:MicrosoftOnline</saml:Audience>
</saml:AudienceRestrictionCondition>
</saml:Conditions>
<saml:AttributeStatement>
<saml:Subject>
<saml:NameIdentifier Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified">
jQs1n5IS0EKf4byoSsOr6A==
</saml:NameIdentifier>
<saml:SubjectConfirmation>
<saml:ConfirmationMethod>urn:oasis:names:tc:SAML:1.0:cm:bearer</saml:ConfirmationMethod>
</saml:SubjectConfirmation>
</saml:Subject>
<saml:Attribute AttributeName="UPN" AttributeNamespace="http://schemas.xmlsoap.org/claims">
<saml:AttributeValue>janets@litware369.com</saml:AttributeValue>
</saml:Attribute>
<saml:Attribute AttributeName="ImmutableID"
AttributeNamespace="http://schemas.microsoft.com/LiveID/Federation/2008/05">
<saml:AttributeValue>jQs1n5IS0EKf4byoSsOr6A==</saml:AttributeValue>
</saml:Attribute>
</saml:AttributeStatement>
<saml:AuthenticationStatement AuthenticationMethod="urn:oasis:names:tc:SAML:1.0:am:password"
AuthenticationInstant="2015-06-10T15:53:38.929Z">
<saml:Subject>
<saml:NameIdentifier Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified">
jQs1n5IS0EKf4byoSsOr6A==
</saml:NameIdentifier>
<saml:SubjectConfirmation>
<saml:ConfirmationMethod>urn:oasis:names:tc:SAML:1.0:cm:bearer</saml:ConfirmationMethod>
</saml:SubjectConfirmation>
</saml:Subject>
</saml:AuthenticationStatement>
<ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
<ds:SignedInfo>
<ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" />
<ds:SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1" />
<ds:Reference URI="#_55b4b481-da5e-49fa-a8f2-af3198cbd1b3">
<ds:Transforms>
<ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature" />
     <ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" />
</ds:Transforms>
<ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1" />
<ds:DigestValue>hKJnVjG/rq/bdy1RrnztTIiBE6c=</ds:DigestValue>
</ds:Reference>
</ds:SignedInfo>    
<ds:SignatureValue>
tT4kMFkVL+l2D6fcD9QhDW+HN+rktCq7lZ9WMsPV+3ONoSq+KH/4qMrO0XncZySYlxMlhLbl7ZAJP5t0eErFbEBfH8+J3PPrsaRU+
mXQe7lfIj1ir1l+hCpbC3Hywnirm01sLaj8NUHnM3/B0KDWblOzpPkOXKvM4Rd4SVsNiKykwp2Em3f80hZWLu2mQRJxiti2n6NcOt
Md4YhOV0fNhH5LHzc0SWNUiIALqtrc7b67YaOFMM21oxQBRffxnY4ns5kRU/aTKCTTwZzamBoRdCI97j0CjT8XTv+LfLHkcWaBH+5
up0Xd+g3T8jTikGQpMDzuvbOtIlY69DUnCIz0DQ==
</ds:SignatureValue>
<KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#">
<X509Data>
<X509Certificate>
MIIC8DCCAdigAwIBAgIQF1RifzXrH59A+2Jtoe+5ADANBgkqhkiG9w0BAQsFADA0MTIwMAYDVQQDEylBREZTIFNpZ25pbmcgL
SBhZGZzLmRlbW8uaWRtZ3QuYXJjaGltcy5mcjAeFw0xMTA4MTAxOTIyNTZaFw0xMjA4MDkxOTIyNTZaMDQxMjAwBgNVBAMTKU
FERlMgU2lnbmluZyAtIGFkZnMuZGVtby5pZG1ndC5hcmNoaW1zLmZyMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQE
AwNpcxWSMJ3TbXfHEAAa4Moi7+S+k6JypSPq45FHAkyn3QkGzRsjJt9KF05/PvUsudukl+OZxXUHsb1pWMQniZAh5G7h6rUXf
k1eeJhDHgBFpwI5yrLGdUlcGrQxNNE4UCLuDwRWG9WjA6Gr7q3bD68vFom/OitsyK18RRB4kCkFWHTln98b7EDieFQQPDxoRP
o+Od6eQ/sejR6D7zJKW9LByT8H8BBOrm4CD9vpBoHiVxIgciLrARx0oCiayh/oYihZDWI8HYv1TlVd9uh+Rxsax7Qt0dWA/Me
06gOO5THo2YmxVA4wG3sdyl74MjgmPSv2qR6mP4GAGxk4sfK59iQIDAQABMA0GCSqGSIb3DQEBCwUAA4IBAQAxr2UPF+6osSL
mF0bdn+Ysj98Q69c6LVLBmTcnd9VBqoefBtcvQe/rp34f2Ok3nqLVRgQv+aWfQrCwM5/5e93saZpdY2UH/U8cvSb+X2PqBK9y
CPDejAtfjo3sCv0ET+0UkoQirK4/CTn07tg+37teZ1EVHaO3DHiI695llnW7Z7j/LH7TLaIP2l9WY2Fe5D+B0iZlYE9kCTDUq
hVR4037cTKC7RKyl/hBPc1xRtQE0ya0lhb4THZjID4fHv9KYQOGaiUHnETt+Qc12pYnZW66O7KXj1Ap47IStGvWiOMbJ6jm4Y
oGyZRa7MC5Gh2z3AQGZ2Rj1KPW3OQ/T3u3u84k
</X509Certificate>
</X509Data>
</KeyInfo>
</ds:Signature>
</saml:Assertion>

One should note that the Issuer URI, for example http://adfs.litware369.com/adfs/services/trust, in the above token is used to locate the namespace in Azure AD.

Issuance authorization rules

The automated definition of the trust creates a "Permit Access to All Users" rule in the Issuance Authorization Rules set.

This rule that authorizes everyone is defined as follows:

=> issue(Type = "http://schemas.microsoft.com/authorization/claims/permit", Value = "true");

Endpoints

AD FS endpoints are used to provide clients with access to federated solutions/applications. Endpoints will issue SAML authentication tokens to clients, after successful client authentication. These endpoints are managed on the federation server(s) (farm) of the AD FS server, and can be managed, secured and published individually through a (load-balanced) web application proxy (see section § Web application proxy (WAP)).

The web application proxy is specifically designed for that purpose to provide remote access to the internally-hosted AD FS service.

In a typical deployment (see section § Fully-implemented AD FS scenario), the web application proxy is hosted in a perimeter network, and passes data through port 443 to the FS (farm), which issues the required SAML security token.

The web application proxy can respond to token requests for accessing AD FS relying parties. One should note that, being limited to proxying only the AD FS service, the web application proxy cannot enable access to relying parties hosted inside the corporate firewall without the help of a general-purpose reverse proxy.

One should also note that, in the specific context of this paper, a web application proxy is required for Exchange Online, as well as for allowing access to SharePoint Online and Lync Online from outside the internal corporate network as previously outlined. Furthermore, both the AD FS server inside the corporate network and the web application proxy should be implemented in a highly available way, as any outage of this infrastructure will prevent access to the federation service.

Figure 10 AD FS endpoints without modern authentication

For accessing Office 365 online services, three distinct endpoints must be considered:

  1. Passive Federation (WS-Fed Passive Profile) endpoint. This endpoint is used by Web clients, when accessing the following services: the Office 365 portal, the SharePoint Online portals, Outlook Web Apps (OWA).

    Web client (internet browsers) will directly authenticate with the AD FS server, through this endpoint

The authentication flow is that relates to this endpoint is covered in section § Passive/Web profile authentication flow.

  1. Active Federation (WS-Trust Active Profile) endpoint. This endpoint is used by rich clients supporting AD FS and more specifically in the context of this paper by Lync 2013/Skype for Business 2016 without modern authentication and the Office 2013/2016 client applications (Excel, PowerPoint, and Word) without modern authentication.

These two clients listed above will negotiate to authenticate directly with the AD FS service, through this endpoint. The related authentication flow is further covered in section § MEX/Rich client profile authentication flow.

  1. EAS Basic Authentication/Active profile endpoint. This endpoint applies to all clients relying on a service to authenticate on-behalf of users, and thus authenticating with Basic Authentication (credential passed over Basic Authentication).

As far as Office 365 is concerned, this endpoint is typically used by Microsoft Exchange ActiveSync (EAS), Outlook 2013/Outlook 2016 without modern authentication, IMAP4, POP3 and SMTP, Exchange Web Services (EWS).

The client sends basic authentication credentials over SSL/TLS to Exchange Online and Exchange Online will then proxy this authentication request to the AD FS server on behalf of the client, through this endpoint. The related authentication flow is further covered in section § EAS basic auth/active profile authentication flow.

For client access restrictions purpose, these three endpoints can be controlled/filtered at the web application proxy level (if any according to the adopted implementation scenario, see section § Understanding the AD FS implementation scenarios for Azure AD/Office 365). Furthermore, filtering via AD FS issuance rules is also now supported.

The Get-MsolFederationProperty cmdlet enable to see the current AD FS endpoint information.

To view the current settings, proceed as follows:

  1. Connect Windows PowerShell to the Microsoft Online Services with the Connect-MsolService cmdlet.
  2. Run the command Get-MsolFederationProperty –DomainName <domain name>. The following is the output from the above command. This information is extremely useful and can be used to do a quick check to see any issues with the single sign-on configuration.
PS C:\Users\AzureAdmin.LITWARE369\Desktop> Get-MSOLFederationProperty -DomainName litware369.com
Source : ADFS Server
ActiveClientSignInUrl : https://adfs.litware369.com/adfs/services/trust/2005/usernamemixed
FederationServiceDisplayName : Litware369
FederationServiceIdentifier : http://adfs.litware369.com/adfs/services/trust
FederationMetadataUrl : https://adfs.litware369.com/adfs/services/trust/mex
PassiveClientSignInUrl : https://adfs.litware369.com/adfs/ls/
PassiveClientSignOutUrl : https://adfs.litware369.com/adfs/ls/
TokenSigningCertificate : [Subject]
CN=ADFS Signing - adfs.litware369.com
[Issuer]
CN=ADFS Signing - adfs.litware369.com
[Serial Number]
42551AC3F30C6BB7414444F209A3EDB4
[Not Before]
12/28/2014 10:02:28 AM
[Not After]
12/28/2015 10:02:28 AM
[Thumbprint]
44020D702E281B8704F3D8141D246541BF8C99A2
NextTokenSigningCertificate :
PreferredAuthenticationProtocol :
Source : Microsoft Office 365
ActiveClientSignInUrl : https://adfs.litware369.com/adfs/services/trust/2005/usernamemixed
FederationServiceDisplayName : Litware369
FederationServiceIdentifier : http://adfs.litware369.com/adfs/services/trust
FederationMetadataUrl : https://adfs.litware369.com/adfs/services/trust/mex
PassiveClientSignInUrl : https://adfs.litware369.com/adfs/ls/
PassiveClientSignOutUrl : https://adfs.litware369.com/adfs/ls/
TokenSigningCertificate : [Subject]
CN=ADFS Signing - adfs.litware369.com
[Issuer]
CN=ADFS Signing - adfs.litware369.com
[Serial Number]
42551AC3F30C6BB7414444F209A3EDB4
[Not Before]
12/28/2014 10:02:28 AM
[Not After]
12/28/2015 10:02:28 AM
[Thumbprint]
44020D702E281B8704F3D8141D246541BF8C99A2
NextTokenSigningCertificate :
PreferredAuthenticationProtocol : WsFed
PS C:\Users\AzureAdmin.LITWARE369\Desktop>
This shows the AD FS server endpoint information:
  • The Passive Federation (WS-Fed Passive Profile) endpoint is the adfs/ls/ endpoint, which corresponds to the PassiveClientSignInUrl entry;
  • The Active Federation (WS-Trust Active Profile) endpoint is the /adfs/services/trust/mex/ endpoint, which corresponds to the FederationMetadataUrl entry.
  • The EAS Basic Authentication/Active profile
    endpoint
    is the /adfs/services/trust/2005/usernamemixed endpoint, which corresponds to the ActiveClientSignInUrl entry.

If, for some reason, a client is hitting the wrong endpoint, this command (Get-MsolFederationProperty) can be run to assist in determining why.

Understanding the authentication flows

Works with Office 365 program

The Microsoft Works with Office 365 – Identity program outlined in the introduction provides - among other valuable information - a series of technical integration documents for the standard-based federation protocols used in Azure AD/Office 365:

  1. A first paper details the agreement for STSs such as AD FS to Interop with Azure AD using the WS-Federation and WS-Trust protocols.
  2. A second paper specifies the scenarios for STS testing that Microsoft use for qualification in the Works with Office 365 - Identity program.

These above papers are available as part of the program guide. They can be used in conjunction with the following explanations to get a deep understanding of the authentication flows and the related details in terms of implementation.

Passive/Web profile authentication flow

In the schema below, the user tries to access a Web-based Office 365 service like SharePoint Online or Outlook Web Apps (OWA) from an internet browser from its domain joined work computer connected to the corporate network.

When authenticating to Azure AD/Office 365, Internet browsers will establish a connection to the organization's AD FS infrastructure, to request a SAML 1.1 logon token.

Authentication to the AD FS service take place using Integrated Windows Authentication (Kerberos or NTLMv2), and doesn't require any user interaction or prompting. The logon token is presented to Azure AD, granting access to the Office 365 service.

Figure 11 Passive/Web profile authentication flow

The passive profile authentication flow is the following:

  1. The user hits the Web-based Office 365 service. The service tells the client that it needs an authentication token signed by Azure AD, and returns the sign-in service URL of Azure AD via a HTTP 302 redirected in order to go get a ticket from there.
  2. The client goes to Azure AD asking for an authentication token. The sign-in service takes the UPN the user types in and then knows if it is a federated domain. It then says it can't sign you in; it needs a logon token signed by your on-premises claims provider, i.e. the on-premises AD FS server. So it returns the AD FS server passive federation endpoint URL (adfs/ls/) via a HTTP 302 redirected.
  3. The client goes to the AD FS server to request a logon token. The AD FS server asks to user to authenticate (via Integrated Windows Authentication by default in this configuration) against the on-premises Active Directory, and after a successful authentication, queries the on-premises Active Directory to retrieve the user claims, and then issues a SAML 1.1 token containing the claims about the logged in user, i.e. its UPN and its Source ID (ImmutableID), which it then signs with the currently declared X.509 token signing certificate.
  4. The client presents via a HTTP POST this signed SAML 1.1 logon token to Azure AD. The sign-in service checks that the incoming token is indeed signed by the trusted claims provider for the federated domain through the public key of the X.509 signing certificate that was shared during the trust establishment via the exposed metadata. It then transforms the Source ID into an internal unique identifier (Unique ID) from Azure AD, and then issues a new token with the UPN and the Unique ID, which it signs. This forms the authentication token.
  5. The authentication token gets back to the client and the client presents the authentication token to the Web-based Office 365 relying party service. The relying party service opens the token, checking that it is signed by the trusted claims provider, i.e. Azure AD), based on a shared public key. It looks at the Unique ID claim and searches for a user in its directory with that Unique ID. (The Unique ID is set as part of provisioning/creating the user, and synchronized to the service.) Once found, the service can apply the necessary access control checks before allowing the user access to the intended Web-based Office 365 service.

The process sounds fairly complicated but when broken down you can see how the process actually works. If there had been an issue here it would be easy to determine at least were to start troubleshooting.

Note    From a protocol perspective, further details are provided in the chapter § 13 Web (Passive) Requestors of the OASIS WS-Federation (WS-Fed) specification. If you want to the capture the flow, you can use the network trace application or the Fiddler tool (with Fiddler Inspector for Federation Messages. For the latter, please refer to the article AD FS: How to Use Fiddler Web Debugger to Analyze a WS-Federation Passive Sign-In.

MEX/Rich client profile authentication flow

Figure 12 MEX/rich client profile authentication flow

In the above schema, the user tries to access Lync Online from its domain joined work computer. The active profile authentication flow is the following:

  1. The user logs on to his domain joined work computer on the corporate network. After a successful logon, the client MSOIDSVC service, i.e. the auto-shipped SIA DLL (see section § Microsoft Office requirements), kicks in and gets the logged on user's Active Directory domain by looking at the domain suffix of his UPN. The MSOIDSVC service calls a home realm discovery (HRD) service on the sign-in service of Azure AD.

    The sign-in service checks to see if that domain is a registered federated domain. If not, it returns nothing; if it is, the sign-in service returns the metadata exchange endpoint (MEX endpoint) URL of the registered federation server, i.e. the organization's on-premises AD FS server.

  2. If nothing is returned, the MSOIDSVC service is done. If a MEX endpoint URL is returned, the MSOIDSVC service contacts the MEX endpoint (/adfs/services/trust/mex/) of the federation service, which returns a list of WS-Trust endpoints exposed by the federation service.
  3. The MSOIDSVC service chooses the most appropriate authentication endpoint type (for Integrated Windows Authentication (Kerberos or NTLMv2)) in order to request a SAML 1.1 logon token. It then goes to the chosen authentication endpoint and authenticates via Kerberos or NTLMv2. Once authenticated, the federation service gets the logged on user's NTLMv2 token or Kerberos ticket, queries the on-premises Active Directory to retrieve for the user claims, and then issues a SAML 1.1 logon token containing the claims about the logged in user, i.e. its UPN and its Source ID (ImmutableID), which it then signs with the currently declared X.509 token signing certificate. The logon token is returned to the MSOIDSVC service.
  4. The MSOIDSVC service now requests an authentication token from Azure AD, providing the SAML 1.1 logon token it received from the AD FS server.

Azure AD verifies the incoming logon token, transforms the Source ID into an internal unique identifier (Unique ID) from Azure AD, and then issues a new authentication token (containing the UPN and the Unique ID claims), which is then sent back to the client. This authentication token can now be used for login. Please note that all the above happen transparently at logon and the user doesn't see it.

The MSOIDSVC service now caches this token ready for use by the client applications.

  1. The user now starts up Lync 2013/Skype for Business 2016 (without modern authentication). Lync 2013/Skype for Business 2016 attempts to connect to Skype for Business (formerly Lync Online), which requests an authentication token.
  2. Lync 2013/Skype for Business 2016 (via an in-process call to the MSOIDCLI.dll) requests an authentication ticket from the MSOIDSVC service. The service has already got one and sends it to Lync Online. Lync Online processes the token and applies the necessary access control checks before allowing the user access to the service.

EAS basic auth/active profile authentication flow

In the schema below, the user opens up Outlook from its domain joined work computer. When authenticating to Exchange Online, Outlook is using Basic Authentication credentials against Office 365, in an encrypted form. The Office 365 platform establishes in turn a connection to the organization's AD FS server to request a SAML logon token, granting user access to the Office 365 service.

Figure 13 EAS Basic Authentication/Active profile authentication flow

The Exchange ActiveSync (EAS) Basic Authentication/Active profile authentication flow is the following:

  1. The user logs on to his domain joined work computer on the corporate network (and the MSOIDSVC service do the round trip to get the SAML 1.1 authentication token and then to cache it). The user now starts up Outlook 2013/Outlook 2016 (without modern authentication).

Outlook attempts to connect to Exchange Online (via Integrated Windows Authentication and the SSPI layer using Negotiate), but Exchange Online challenges for Basic Authentication.

  1. The user will get a prompt the first time and will need to type in his corporate credentials, i.e. his username in the form of the UPN and his password. The user can save them, and will not be prompted again until his password changes. This will be sent off by Outlook to Exchange Online.
  2. Exchange Online now does a trick called "Proxy Auth" where it creates a shadow representation of the user. It then takes the domain/UPN from the Basic Authentication and sends it to Azure AD (authenticating the user with AD FS on his/her behalf based on the credentials provided through the Basic auth over SSL flow).

Azure AD returns with the active profile endpoint URL (/adfs/services/trust/2005/usernamemixed) of the organization's on-premises AD FS server.

  1. Exchange Online then takes the basic authentication credentials and sends them to the active profile endpoint of the federation service. This requires that WAP proxies the request to the federation service (or the federation service is published on the Internet using a reverse proxy.)

The federation service authenticates the user with the basic credentials against the on-premises Active Directory, query the on-premises Active Directory to retrieve for the user claims, and then issues a SAML 1.1 logon token (containing the UPN and the Source ID (ImmutableID) claims about the user), which it then signs with the currently declared X.509 token signing certificate. This comes back to Exchange Online.

  1. Exchange Online sends it to Azure AD. The sign-in service verifies the logon token and converts it to an authentication token, which contains the UPN and the internal unique identifier (Unique ID) from Azure AD). This authentication token can now be used for login.

Exchange Online can now authenticate the user with the authentication token and will delete the shadow representation of the user.

It should be noted that customer credentials aren't persisted anywhere in the above authentication legs, and customer credentials aren't stored or cached in Microsoft datacenters.

Furthermore, as mentioned below, in order to avoid being prompted for their credentials at each new Outlook 2013/Outlook 2016 session, users can choose to have their credentials cached in the Windows Credential Manager, by selecting the Save Password option in the Outlook password prompt.

The Windows Credential Manager provides a secure area (vault) for storing user credentials, allowing easier access to remote services (and a better user experience). The stored passwords can be protected at multiple levels:

  • For domain-joined machines, the user password needs to be known to get access to the Credential Manager content;
  • Concerns about stolen hard disks can be mitigated through the deployment of disk encryption technologies such as BitLocker on Windows platforms;
  • Home workstations and other unmanaged clients may pose a greater risk if passwords are cached locally. Customers can implement conditional access (see section § Conditional access) to prevent connection to their Office 365 services from outside of their network, thus mitigating the risk of employees caching corporate passwords on unmanaged clients.

Modern authentication flows

As earlier mentioned, modern authentication is a new authentication stack used by Office 2013/2016 client applications (with the March 2015 or later update for Office 2013) against Office 365. This stack allows the Office 2013/2016 client applications to engage in browser-based authentication with the organization's on-premises AD FS server.

This diagram shows how the updated Office 2013/2016 client applications enables user sign in.

Figure 14 Modern authentication flow

These Office 2013/2016 client applications use the ADAL based stack to facilitate sign in with Azure AD. When such an application makes a request to a services in Office 365 service, the considered service in Office 365 instructs the application to visit Azure AD which speaks a simple standards based protocol: OAuth 2.0 . Azure AD hosts for that purpose a web page where the user can sign in.

The Office 2013/2016 client application instructs ADAL to launch web browser control. The claims provider could be Azure AD or a federated claims provider like the AD FS server in the context of this paper or another identity provider that uses the SAML protocol.

If the user is a federated user as covered in this document, Azure AD redirects the user to the sign in web page hosted by the AD FS server of record for the tenant. As already illustrated, this AD FS server is determined based on the domain as specified in the user's sign in name.

The sign in web page is shown to the user on their device and the user signs in. In the context of this paper, the AD FS server returns a SAML token to Azure AD when the user is successfully signed in. Azure AD returns a JWT token to the Office 2013/2016 client application.

Note    JWT is a compact token format (JavaScript Object Notation (JSON) Web Token). It describes a way of representing information about the user in the token that is especially apt for REST-based software. JWT use is growing, and products supporting the format are increasingly common in the industry. For more information, see the eponym specification.

The Office 2013/2016 client application gets back this simple JWT token that it caches for future communication with its services. It can then use this token with services in Office 365 on behalf of the user by sending it to these services.

Troubleshooting the authentication flows

In terms of troubleshooting, and as described in the above sections, the authentication flow of any Azure AD/Office 365 single sign-on communication is predictable. The expected authentication flow pattern can be compared to or contrasted with a capture of the actual authentication flow that occurs during a failing single sign-on attempt to determine what might be wrong with the process.

First of all the Microsoft Remote Connectivity Analyzer can help diagnose and troubleshoot the authentication flows.

The Microsoft Remote Connectivity Analyzer (RCA) web site enables IT professionals to pinpoint connectivity issues by simulating connectivity from a location outside the customer environment.

To use the RCA web site to test the single sign-on authentication, proceed with the following steps:

  1. Open a browsing session and navigate to https://www.testconnectivity.microsoft.com/?testid=SingleSignOn.

  1. Enter your credentials, click to select the security acknowledgement check box, type the verification code, and then click Perform Test.

You can then refer to the article How to use Remote Connectivity Analyzer to troubleshoot single sign-on issues for Office 365, Azure, or Windows Intune that describes how to diagnose single sign-on (SSO) logon issues in Azure AD/Office 365 by using the RCA. It also contains information about causes of common SSO failures and lists links to resources for how to troubleshoot the issue.

The Microsoft Connectivity Analyzer tool (client) is a downloadable companion client tool from the RCA web site. It lets both email users and IT professionals run the same tests within the user's environment. It simulates several client logon and mail flow scenarios (unless the Remote Connectivity Analyzer it helps troubleshooting specific scenarios, and provides additional capabilities of testing the on-premises AD FS infrastructure from with the corporate network as a Web application – such as OWA - would using this infrastructure for gathering the authentication token). When a test fails, many of the errors message provide troubleshooting tips to help the user or IT professional to resolve the problem.

To run the Connectivity Analyzer client to test SSO authentication, proceed with the following steps:

  1. Open a browsing session and navigate to the RCA web site at https://www.testconnectivity.microsoft.com.
  2. Click Client.

  1. Click Install Now to launch the Click-Once installation (http://go.microsoft.com/fwlink/?LinkID=313782). The Microsoft Connectivity Analyzer dialog opens up.

  1. Click I can't set up federation with Office 365, Azure, or other services that use Azure Active Directory.

  1. Enter your credentials, and then click next to start running the diagnostics.

Leveraging the AD FS enhancements for Office 365 and other considerations

Using smart links for Office 365

Smart links for Office ease the access to Office 365 workloads with federated identities. Smart links are pre-formatted links that work with the following Web passive workloads, i.e. the Office 365 portal, Outlook Web Access (OWA), and SharePoint Online.

The reason for using pre-formatted links is to simplify the sign-in process for federated users. When a user authenticates to these Office 365 workloads, the default behavior requires the user to enter his UPN at the login.microsoftonline.com prompt to trigger the home realm discovery (HRD) process before redirecting the user to his on-premises AD FS server (see section § Verifying the single sign-on).

If you rather prefer a completely transparent single sign-on experience from on-premises domain-joined work computers, you can deploy and use customized smart links to bypass the home realm discovery prompt. They thus enable to have you automatically redirect to your AD FS server. If you use this URL externally, you will get to AD FS through the web application proxy (WAP). If you use this URL internally, you should get to AD FS directly, and possibly have single sign-on.

To sign in to the Office 365 portal, you can use the following smart links and log on with your UPN such as janets@litware369.com:

https://adfs.litware369.com/adfs/ls/?wa=wsignin1.0&wtrealm=urn:federation:MicrosoftOnline

-or-

https://login.office.com/login.srf?wa=wsignin1.0&whr=litware369.com&wreply=https:%2f%2fportal.office.com%2fdefault.aspx

Another Key use of smartlinks is with Outlook Web Access (OWA) sign-in, where you can use the following smart links:

https://outlook.office365.com/litware369.com

-or-

https://login.office.com/login.srf?wa=wsignin1.0&whr=litware36.com&wreply=https:%2f%2foutlook.office365.com%2fowa%2fjanets40litware369%2ecom%2f?exsvurl=1&ll-cc=en-US

(Note that if the user has no Exchange Online license, he/she should get an error from OWA telling the user that he/she do not have a mailbox).

Finally, to sign in to SharePoint Online, you can use the following smart link:

https://login.office.com/login.srf?wa=wsignin1.0&whr=litware36.com&wreply=https:%2f%2flitware369%2esharepoint%2ecom%2f%5fforms%2fdefault%2easpx

Replace in the above smart links the parts outlined in light blue with the appropriate values of the AD FS server passive federation public endpoint, the federated domain or the user's UPN to accommodate your own configuration.

The query string parameters are detailed in OASIS WS-Federation (WS-Fed) specification (see chapter § 13 Web (Passive) Requestors).

Supporting multiple top level domains

Organizations that leverage the single sign-on capability through AD FS and that have multiple top level domains for user's UPN suffixes within their organization (for example, @litware369.fr or @litware369.co.uk) were required in the past to deploy a separate instance of the AD FS server for each suffix.

You do not have to set up multiple instances of AD FS server to support single sign-on for multiple top level domains (without sub domains) in Azure AD/Office 365. This requires the use of the SupportMultipleDomain switch with the Convert-MsolDomainToFederated cmdlet.

Important note    This switch is not required when you have a single top level domain and multiple sub domains. For example, if the domains used for the UPN suffixes are @legal.litware369.fr, @paris.litware369.fr,@litware369.fr and if the top level domain (litware369.fr in this case) was added first and federated then you don't need to use the SupportMultipleDomain switch. This is because these sub domains are effectively managed within the scope of the parent and a single AD FS server can be utilized to handle this.

If you have multiple top level domains (@litware369.fr and @ litware369.co.uk) and these domains also have sub domains (@paris.litware369.fr and @london.litware369.co.uk), the SupportMultipleDomain switch will not work out-of-the-box for the sub domains and with the default configuration these users will not be able to login. This issue relates to the fact that the Issuer URI in the issued logon token by the AD FS server is used to locate the namespace in Azure AD/Office 365.

One possible workaround consists in configuring a regular expression in the issuance transform rules of the Office 365 identity platform
relying party trust (see section § Issuance transform rules) which will truncate domain name for the Issuer URI:

c:[Type == "http://schemas.xmlsoap.org/claims/UPN"]
=> issue(Type = "http://schemas.microsoft.com/ws/2008/06/identity/claims/issuerid",
Value = regexreplace(c.Value, ".+@(?<domain>.+)", "http://${domain}/adfs/services/trust/"));

Using an alternate login ID

Some customers cannot use their on-premises UPNs to authenticate their users with Azure AD/Office 365 (or another associated services like InTune). This is commonly because their on-premises UPNs are using a non-Internet routable domain (i.e. single level domains or .local / .intranet domains). Standard guidance for such situations is to change the on-premises UPNs to use a different domain. However, those same customers may not be able to implement that guidance for a variety of reasons.

AD FS adds the capability to specify a different attribute - referred as the "Alternate login ID" - in their on-premises AD that can be used as sign-in value for their users. The attribute chosen to be the "Alternate Login ID" must be using a publically routable, verified domain, for example the email address instead of a UPN. This change does not affect the Active Directory schema. It must also be indexed and part of the global catalog. Finally, the value of this attribute must be unique across all configured forests.

Note    For additional detail on Alternate Login ID, see article Configuring Alternate Login ID and the blog post Introduction to Active Directory Federation Services (AD FS) AlternateLoginID Feature.

From AD FS support prospective, this capability has been made available with Windows Server 2012 R2 Update.

This capability is configured through the Set-AdfsClaimsProviderTrust cmdlet:

PS C:\> Set-AdfsClaimsProviderTrust -TargetIdentifier "AD AUTHORITY" -AlternateLoginID mail -LookupForests liware369.com

Note    One key caveat with implementing the AlternateID solution is that the Exchange Autodiscover process will break. This impact not only an Outlook autodiscover query (for any non-domain joined machine or for computers outside the corporate network), it's prevent cross-premises Free&Busy requests to work and will break the Exchange Hybrid configuration.

Keeping you signed in

AD FS offers users the choice to stay signed in. It professionals have the ability to configure the lifetime of these signed in experiences through the Set-AdfsProperties cmdlet:

PS C:\> Set-ADFSProperties –KmsiEnabled $true –KmsiLifetimeMins 1440

Under the cover, this configuration enables to create persistent SSO cookies via the browser. The SSO cookie revoked upon user password change.

Enabling password expiry notification

AD FS adds the capability to enable notification of expiring passwords to be displayed to the user within the Office 365 portal and applications.

From a technical standpoint, AD FS just adds password expiration claims in token if you include below issuance rule for the Microsoft Office 365 identity platform relying party trust. (See section § Microsoft Office 365 identity platform relying party trust)

c1:[Type == "http://schemas.microsoft.com/ws/2012/01/passwordexpirationtime"]
=> issue(store = "_PasswordExpiryStore", types = ("http://schemas.microsoft.com/ws/2012/01/passwordexpirationtime", "http://schemas.microsoft.com/ws/2012/01/passwordexpirationdays", "http://schemas.microsoft.com/ws/2012/01/passwordchangeurl"), query = "{0};", param = c1.Value);

Changing password

AD FS enables users to change password from inside or outside the network on their devices that are workplace joined. This can be enable with the Enable-AdfsEndpoint cmdlet:

PS C:\> Enable-AdfsEndpoint -TargetAddressPath /adfs/portal/updatepassword/

Enabling extranet account lockout protection

AD FS allows to protect Active Directory accounts from malicious lockout from external access attempts.

This interesting feature can be enable through the ExtranetLockoutThreshold and ExtranetObservationWindow switches of the Set-AdfsProperties cmdlet:

  • The ExtranetLockoutThreshold switch controls the maximum number of bad passwords.
  • The ExtranetObservationWindow switch specifies the timespan for tracking the maximum number of bad passwords. The authentication from extranet with username and password is denied for duration of an "observation window".
PS C:\> $ExtranetObservationWindow = New-Timespan -Minutes 30
PS C:\> Set-AdfsProperties -EnableExtranetLockoutEnabled $true -ExtranetLockoutThreshold 15 -ExtranetObservationWindow $ExtranetObservationWindow

The above configuration works independently of the Active Directory lockout policies. Consequently, you will need to set the AD FS threshold lower than the AD lockout threshold.

This also requires a line of sight to the PDC of user domains.

Note    For more information, see article Configuring AD FS Extranet Lockout as well as blog posts Enabling ADFS 2012 R2 Extranet Lockout Protection and ADFS 2012 R2 - An Error Occurs When BadPwdCount Not Set.

Limiting access based on the location of the client

You may want for instance to control the services in Office 365 that will be published to Internet and consequently block some external access scenarios.

Using AD FS endpoints

Client access to the service can be controlled through publishing of the AD FS endpoints (see section § Endpoints).

For example, by not publishing the Passive Federation endpoint, an organization can prevent Web clients to connect to the service from outside their corporate network.

Important note    As previously noticed, to allow Basic Authentication clients to connect (including Outlook 2010/2013), a web application proxy must be deployed in any case. If a web application proxy is not available, no Outlook 2010/2013 clients will be able to authenticate (but this will also prevent any mobile devices using Exchange ActiveSync protocol to connect) not even when they are directly connected to the internal company network.

Using client access policies

The client access policies in AD FS enable to support browser conditional access and provides in this context a simple rules logic for client access rules with support for user agent string. For that purpose, AD FS populates a set of claim from the client request context information such as the connection IP address, the AD FS endpoint, and HTTP headers sent by the client (see Appendix. Claims available for conditional access control):

  • x-ms-forwarded-client-ip     

(http://schemas.microsoft.com/2012/01/requestcontext/claims/x-ms-forwarded-client-ip).

  • x-ms-client-application

(http://schemas.microsoft.com/2012/01/requestcontext/claims/x-ms-client-application).

  • x-ms-client-user-agent

(http://schemas.microsoft.com/2012/01/requestcontext/claims/x-ms-client-user-agent).

  • x-ms-proxy

    (http://schemas.microsoft.com/2012/01/requestcontext/claims/x-ms-proxy).

  • insidecorporatenetwork

(http://schemas.microsoft.com/ws/2012/01/insidecorporatenetwork).

  • x-ms-endpoint-absolute-path

(http://schemas.microsoft.com/2012/01/requestcontext/claims/x-ms-endpoint-absolute-path).

The above request context claims can then be leveraged in the claims pipeline and, more specifically, can act upon them through relevant custom rules defined in the Issuance Authorization Rules set of the Office 365 Identity Platform
relying party trust (see section § Issuance transform rules).

The AD FS server can support access policies for allowing or denying access based upon the combination of the user requesting access, the IP address of his devices, and the access method as documented in the article Configuring Client Access Policies.

Such a solution enables the following scenarios:

  • Block all external access to Office 365. Office 365 access is allowed from all clients on the internal corporate network, but requests from external clients are denied based on the IP address of the external client.
  • Block all external access to Office 365, except Exchange ActiveSync (EAS). Office 365 access is allowed from all clients on the internal corporate network, as well as from any external client devices, such as smart phones, that make use of EAS. All other external clients are blocked.
  • Block all external access to Office 365, except for browser-based applications such as SharePoint Online or Outlook Web App (OWA). Blocks external access to Office 365, except for Office 365 Web-based services.
  • Block all external access to Office 365 for members of designated Active Directory groups. This scenario is used for testing and validating client access policy deployment. It blocks external access to Office 365 only for members of one or more Active Directory group. It can also be used to provide external access only to members of a group.

As discussed in the introduction of the document, AD FS in Windows Server 2012 R2 further enhances this access control mechanism as well as the authentication based on multiple factors, including the user identity, network location, device (AD Workplace Join), and authentication data. In order to manage the risk of granting access permissions to Azure AD/Office 365, AD FS allows to notably:

  • Support a rich multi-factor authentication Framework, trigger multi-factor authentication based on user identity or group membership, network location, etc., and use the authentication state when multi-factor authentication was performed;
  • Enforce conditional access control based on user identity or group membership, network location, device (whether it is workplace joined), and the authentication state (whether multifactor authentication was performed), etc.

These enhancements are discussed in the next two sections.

Supporting rich multi-factor authentication (MFA)

The AD FS server sits inside the corporate network and authenticates corporate users on the internal network using by default Windows Integrated Authentication (WIA).

However, it is increasingly common for corporate users to need access to their usual resources like the services in Office 365 that reside in the cloud at times when they are remote, at home, at the airport, at an Internet café, etc.

In order to benefit from single sign-on capabilities that are discussed throughout this paper, these users must be able to reach the AD FS server so that they can request authentication tokens to access the available services as needed.

Consequently, to make the AD FS server remotely accessible for their users, organizations leverage the network perimeter as an access control edge via the web application proxy, a deployment mode of AD FS specifically designed to provide remote access to the internally-hosted AD FS server and to allow proxied access to necessary services in Office 365.

This infrastructure has to be deployed on-premises (or in the Cloud on Azure for instance) and does not require specific caution.

Organizations allowing this remote access commonly consider strong authentication techniques to secure inbound access. Thus, securing remote authentication is important since attackers can reach the inbound access point easily, and successful authentication to a federation server farm potentially grants the attacker access to security tokens for numerous relying parties.

Multi-factor authentication provides improved security because it requires the user to meet two authentication criteria, for instance "something you know" (a user name/password) combined with "something you have" (a token or certificate). This does not require specific configuration on Azure AD/Office 365 - unless Azure Multi-Factor Authentication (Azure MFA) is used - and is rather managed in the organization's on-premises infrastructure. Organizations will need to deploy their own multi-factor authentication infrastructure and configure AD FS accordingly.

The AD FS authentication and access control (a.k.a. authorization) mechanism – that conceptually resembles a pipeline– has been enhanced to trigger multi-factor authentication if required.

Note    For more information about MFA and multi-factor access control in AD FS, see article Manage Risk with Additional Multi-Factor Authentication for Sensitive Applications.

For that purpose, the authentication part in the AD FS access control "pipeline" encompasses a primary authentication and possibly an additional authentication as illustrated hereafter.

Note    To give credit where credit is due, the following takes its inspiration from the webcast of the TechEd Europe 2014 session EM-B310 Active Directory + BYOD = Peace of Mind from Samuel Devasahayam, principal program manager in the AD team.

Figure 15 AD FS authentication and access control "pipeline"

The primary authentication method is network location dependent. If multiple user authentication methods are enabled, user gets a choice on the sign-in page.

Note    For intranet access, if WIA is enabled, it is performed by default as already discussed in section § Authenticating from a web browser. Authentication requests from browsers not capable of supporting WIA will as a result fail. As illustrated in the aforementioned section, you have the ability to fallback to forms-based authentication for these browsers by configuring the list of related user agents through the WIASupportedUserAgentStrings switch of the Set-ADFSProperties cmdlet.

Device authentication is performed if enabled. Device authentication can be enabled in the global primary authentication policy. When you edit this policy in the user interface, you enable the device authentication by checking Enable device authentication.

It can also be enabled through Windows PowerShell:

PS C:\> Set-AdfsGlobalAuthenticationPolicy

Triggering multi-factor authentication (MFA)

In the AD FS access control "pipeline", an additional authentication is performed only if a multi-factor authentication is required.

Figure 16 Multi-factor authentication checkpoint in the "pipeline"

In the AD FS access control "pipeline", the additional authentication (block) is only performed is a multi-factor authentication is required. Multi-factor authentication is triggered if:

  • A wire parameter in the federation protocol requires multi-factor authentication.

-or-

  • The global multi-factor authentication policy requires multi-factor authentication.

-or-

  • The resource/relying party multi-factor authentication policy requires multi-factor authentication.

Figure 17 Multi-factor authentication triggers

This is a logical 'or' semantics.

The wauth query parameter of the WS-Fed protocol enables to require multi-factor authentication:

?WAUTH=http://schemas.microsoft.com/claims/multipleauthn

This mechanism can be useful to enforce multi-factor authentication policies for cloud resources secured by Azure AD.

The multi-factor authentication triggers can also be configured in a policy. You can configure a global multi-factor authentication policy that applies to all relying parties secured by the AD FS server. The multi-factor authentication triggers are based on multiple factors supported in the user interface:

  • User identity/group membership
  • Device type (workplace-joined or not)
  • Network location (intranet or extranet)

More complex multi-factor authentication triggers can be expressed using claim rules (with the familiar syntax and the rich and expressive semantics) and Windows PowerShell. Such a claim rule simply issues an authenticationmethod (http://schemas.microsoft.com/ws/2008/06/identity/claims/authenticationmethod) claim with value multipleauthn to trigger multi-factor authentication:

issue(Type = "http://schemas.microsoft.com/ws/2008/06/identity/claims/authenticationmethod", Value = "http://schemas.microsoft.com/claims/multipleauthn");

The Set-AdfsAdditionalAuthenticationRule cmdlet enables you to add an expressed claim rule in string format ($MFATriggerClaimRule) in the global policy via the AdditionalAuthenticationRules parameter:

PS C:\> Set-AdfsAdditionalAuthenticationRule –AdditionalAuthenticationRules $MFATriggerClaimRule

Conversely, you can also configure a resource specific (per-relying party) multi-factor authentication policy that applies only to that specific resource/relying party. This can be performed in Windows PowerShell with the AdditionalAuthenticationRules parameter of the Set-AdfsRelyingPartyTrust cmdlet:

PS C:\> Set-AdfsRelyingPartyTrust –AdditionalAuthenticationRules $MFATriggerClaimRule

On the above core principles, followings are some illustrations of multi-factor authentication trigger claim rules.

The following PowerShell code snippet illustrates how to trigger multi-factor authentication based on group membership for the Office 365 Identity Platform relying party trust (see section § Issuance transform rules):

If the groupsid claim value equals 'S-1-5-21-2051694910-254885857-3069878782-1114', then issue an authenticationmethod claim with value multipleauthn to trigger multi-factor authentication

PS C:\> $rp = Get-AdfsRelyingPartyTrust –Name "Microsoft Office 365 Identity Platform"
PS C:\> $GroupMfaClaimTriggerRule = 'c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/groupsid", Value == "S-1-5-21-2051694910-254885857-3069878782-1114"] => issue(Type = "http://schemas.microsoft.com/ws/2008/06/identity/claims/authenticationmethod", Value = "http://schemas.microsoft.com/claims/multipleauthn");'
PS C:\> Set-AdfsRelyingPartyTrust –TargetRelyingParty $rp –AdditionalAuthenticationRules $GroupMfaClaimTriggerRule

Likewise, as another illustration, the following rule triggers multi-factor authentication for access from extranet by leveraging the aforementioned insidecorporatenetwork claim (see previous section § Using client access policies):

If the insidecorporatenetwork claim value equals 'false', then issue an authenticationmethod claim with value multipleauthn to trigger multi-factor authentication

'c:[type == "http://schemas.microsoft.com/ws/2012/01/insidecorporatenetwork", value == "false"] => issue(type="http://schemas.microsoft.com/ws/2008/06/identity/claims/authenticationmethod", value = "http://schemas.microsoft.com/claims/multipleauthn" );' 

Finally, the following rule triggers multi-factor authentication when users access the resource from non-workplace joined device:

If the isregistered claim value equals 'false', then issue an authenticationmethod claim with value multipleauthn to trigger multi-factor authentication

'c:[type=="http://schemas.microsoft.com/2012/01/devicecontext/claims/isregistereduser", value == "false"] => issue (type="http://schemas.microsoft.com/ws/2008/06/identity/claims/authenticationmethod", value = "http://schemas.microsoft.com/claims/multipleauthn");'

The IsRegistredUser claim is set to true when the device is workplace joined and registered to the user.

Without the aforementioned new ADAL stack enabled, the multi-factor authentication support is not available for clients other than Web browsers. The key reason is that current Outlook, Skype for Business, ActiveSync, and other rich clients do not have the capability to prompt users for strong authentication credentials and therefore cannot be supported.

An exception like the following one would be raised in such situations:

The Federation Service could not authorize token issuance for caller 'DOMAIN\User'. The caller is not authorized to request a token for the relying party 'urn:dumptoken'. See event 501 with the same Instance ID for caller identity. 
 
Additional Data
Instance ID: xxxxxxxxxxx
Relying party: yyyy
Exception details:
Microsoft.IdentityServer.Service.IssuancePipeline.CallerAuthorizationException: MSIS5007: The caller authorization failed for caller identity xxxxxx for relying party trust yyyy.
at Microsoft.IdentityModel.Threading.AsyncResult.End(IAsyncResult result)
at Microsoft.IdentityModel.Protocols.WSTrust.WSTrustServiceContract.ProcessCoreAsyncResult.End(IAsyncResult ar)
at Microsoft.IdentityModel.Protocols.WSTrust.WSTrustServiceContract.EndProcessCore(IAsyncResult ar, String requestAction, String responseAction, String trustNamespace)
User Action
Use the AD FS Management snap-in to ensure that the caller is authorized to request a token for the relying party.

Note    There are some exceptions to this rule due to a transition to browser based interactions during authentication. Indeed, when an Office 2010 application (Excel, PowerPoint, or Word) attempts to access a SharePoint Online document library, the client will rely on a response from SharePoint Online to popup a browser-like dialog window which subsequently supports federation-related Web protocols (WS-Fed) that rely on redirect schemes. This is not the case for an Office 2013 Windows client application.

To address this issue, the aforementioned x-ms-endpoint-absolute-path claim (see previous section) can be used to exclude active endpoint from having to do multi-factor authentication in your trigger rule:

c:[Type == "http://schemas.microsoft.com/ws/2012/01/insidecorporatenetwork", Value == "false"] && c1:[Type == "http://schemas.microsoft.com/2012/01/requestcontext/claims/x-ms-endpoint-absolute-path", Value =~ `"(/adfs/ls)|(/adfs/oauth2)"]
=> issue(Type = "http://schemas.microsoft.com/ws/2008/06/identity/claims/authenticationmethod", Value = "http://schemas.microsoft.com/claims/multipleauthn");

In the above rule, the 'adfs/ls' value corresponds to the WS-Fed (and SAML) requests whereas '/adfs/oauth2' corresponds to the OAuth request.

With the new ADAL-based authentication enabled Office 2013 Windows client applications, users can sign in using true multi-factor authentication. The second factor of authentication the user must provide is dependent on the configuration done by their administrator.

Configuring additional authentication methods

An additional authentication method is invoked by the AD FS authentication and access control "pipeline" if multi-factor authentication triggers determine a need to perform additional authentication.

AD FS provides built-in additional authentication as well as an extensible additional authentication infrastructure.

Using the built-in additional authentication

The built-in additional authentication provides an in-box support for X.509 Certificate-based Authentication and (virtual) smartcard based authentication. When using (virtual) smartcards, the AD FS server can project a strong authentication claim to downstream applications and services which can perform further authorization based on the strength of authentication.

Using the extensible additional authentication infrastructure

The extensible additional authentication infrastructure allows IT professionals to enable additional authentication method using the global authentication policy.

This assumes that you have an external authentication provider for AD FS installed on each of the AD FS server in your organization. Once installed and registered with AD FS, you can enforce multi-factor authentication as part of the global or per-relying-party authentication policy as shortly described above.

Each third party a provider relies on the extensible API provided in AD FS to implement its own multi-factor authentication.

Note    For more information, see the article Build a Custom Authentication Method for AD FS in Windows Server 2012 R2.

The article Configure Additional Authentication Methods for AD FS list the available Microsoft and third-party external authentication provider. As of this writing, the list is as follows:

External authentication provider

Offering

Gemalto

Gemalto Identity & Security Services

inWebo Technologies

inWebo Enterprise Authentication service

Login People

Login People MFA API connector for AD FS 2012 R2

Microsoft Corp.

Microsoft Azure MFA

RSA, The Security Division of EMC

RSA SecurID Authentication Agent for Microsoft Active Directory Federation Services

SafeNet, Inc.

SafeNet Authentication Service (SAS) Agent for AD FS

Swisscom

Mobile ID Authentication Service and Signature Services

Symantec

Symantec Validation and ID Protection Service (VIP)

Note    The whitepaper Leverage Azure Multi-Factor Authentication Server for Azure AD single sign-on with AD FS provides a complete walkthrough to install, configure, test, and evaluate the Azure Multi-Factor Authentication (MFA) provider and the related component. Interestingly enough, it builds the walkthrough on top of the Azure-based lab environment described in the Part 2 and Part 4 (bis) of this whitepaper.

Once the intended external authentication provider(s) are properly installed and configured, you can enable the related additional authentication method in the global authentication policy via the user interface by checking the related entry under Select additional authentication methods.

Conversely, IT professionals can enable the additional authentication methods via Windows PowerShell with the AdditionalAuthenticationProvider parameter of the Set-AdfsGlobalAuthenticationPolicy cmdlet:

PS C:\> Set-AdfsGlobalAuthenticationPolicy –AdditionalAuthenticationProvider "CertificateAuthentication"

When multiple additional authentication methods are enabled like in the above snapshot with both Login People Digital DNA Authentication and WindowsAzureMultiFactorAuthentication, the users get a choice on the sign-in page.

Using conditional access control

AD FS enables to enforce conditional access to resources – depending on the user identity or group membership, the network location, the device (workplace joined), the authentication state (whether multi-factor authentication was performed etc.), and of course the sensitivity of resources.

The conditional access is configured using the flexible and expressive per-application authorization policies that permit/deny access based on the user, network location, device, and authentication state data as per all the available claims listed in Appendix. Claims available for conditional access control.

This supposes to create a replying party issuance authorization rules for the application/relying party via the user interface /wizard experience for common scenarios, or the rich claims language and Windows PowerShell for advanced scenarios. Related error messages are customizable on a per-application basis.

Note    For more information on conditional access control, see article Manage Risk with Conditional Access Control.

Some rules are described below as examples to illustrate how to conditionally permit access to resources.

The following rule illustrates how to permit access only if multi-factor authentication was performed:

If the authnmethodsreferences claim value equals 'multipleauthn', then permit access

@RuleTemplate = "Authorization"
@RuleName = "PermitAccessWithMFA"
c:[Type == "http://schemas.microsoft.com/claims/authnmethodsreferences", Value =~ "^(?i)http://schemas\.microsoft\.com/claims/multipleauthn$"] => issue(Type = "http://schemas.microsoft.com/authorization/claims/permit", Value = "PermitUsersWithClaim");

The following rule illustrates how to permit access from a workplace joined device:

If the isregistereduser claim value equals 'true', then permit access

@RuleTemplate = "Authorization"
@RuleName = "PermitAccessFromRegisteredWorkplaceJoinedDevice"
c:[Type == "http://schemas.microsoft.com/2012/01/devicecontext/claims/isregistereduser", Value =~ "^(?i)true$"] => issue(Type = "http://schemas.microsoft.com/authorization/claims/permit", Value = "PermitUsersWithClaim");

Similarly, to combine multiple contextual data, the following rule illustrates how to permit access from extranet if multi-factor authentication was performed:

If the authnmethodsreferences claim value equals 'multipleauthn' and the insidecorporatenetwork claim value equals 'false', then permit access

@RuleTemplate = "Authorization"
@RuleName = "RequireMFAForExtranetAccess"
c1:[Type == "http://schemas.microsoft.com/claims/authnmethodsreferences", Value =~ "^(?i)http://schemas\.microsoft\.com/claims/multipleauthn$"] &&
c2:[Type == "http://schemas.microsoft.com/ws/2012/01/insidecorporatenetwork", Value =~ "^(?i)false$"] => issue(Type = "http://schemas.microsoft.com/authorization/claims/permit", Value = "PermitUsersWithClaim");

Likewise, the following rule illustrates how to permit access from a workplace joined device if multi-factor authentication was performed:

If the authnmethodsreferences claim value equals 'multipleauthn' and the isregistereduser claim value equals 'true'', then permit access

@RuleTemplate = "Authorization"
@RuleName = "RequireMFAOnRegisteredWorkplaceJoinedDevice"
c1:[Type == "http://schemas.microsoft.com/claims/authnmethodsreferences", Value =~ "^(?i)http://schemas\.microsoft\.com/claims/multipleauthn$"] &&
c2:[Type == "http://schemas.microsoft.com/2012/01/devicecontext/claims/isregistereduser", Value =~ "^(?i)true$"] => issue(Type = "http://schemas.microsoft.com/authorization/claims/permit", Value = "PermitUsersWithClaim");

This concludes the third part of this whitepaper. The fourth part (bis) deals with an end-to-end walkthrough to rollout a working configuration in an Azure-based lab environment.

Appendix. Claims available for conditional access control

The following Table 8 lists the claims available for conditional access control.

Table 8 Claims available for conditional access control

Claim Type

What does it mean?

User Information

denyonlyprimarygroupsid (http://schemas.microsoft.com/ws/2008/06/identity/claims/denyonlyprimarygroupsid)

The deny-only primary group SID of the user

denyonlyprimarysid (http://schemas.microsoft.com/ws/2008/06/identity/claims/denyonlyprimarysid)

The deny-only primary SID of the user

groupsid (http://schemas.microsoft.com/ws/2008/06/identity/claims/groupsid)

The group SID of the user. You can use this claim to find out if the user belongs to a specific group.

primarygroupsid (http://schemas.microsoft.com/ws/2008/06/identity/claims/primarygroupsid)

The primary group SID of the user

primarysid (http://schemas.microsoft.com/ws/2008/06/identity/claims/primarysid)

The primary SID of the user

windowsaccountname (http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname)

The domain account name of the user in the form of domain\user

CommonName (http://schemas.xmlsoap.org/claims/CommonName)

The common name of the user

denyonlysid (http://schemas.xmlsoap.org/ws/2005/05/identity/claims/denyonlysid)

The deny-only group SID of the user

name (http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name)

The unique name of the user

upn (http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn)

The user principal name (UPN) of the user

Device Information (if the device is joined to the workplace)

displayname (http://schemas.microsoft.com/2012/01/devicecontext/claims/displayname)

Display name of Device Registration

identifier (http://schemas.microsoft.com/2012/01/devicecontext/claims/identifier)

Identifier of the device

isregistereduser (http://schemas.microsoft.com/2012/01/devicecontext/claims/isregistereduser)

User is registered to use this device. When the value of this claim is true, it means that the user who authenticated is the one who originally registered the device.

ostype (http://schemas.microsoft.com/2012/01/devicecontext/claims/ostype)

OS type of the device

osversion (http://schemas.microsoft.com/2012/01/devicecontext/claims/osversion)

OS version of the device

Request information

client-request-id (http://schemas.microsoft.com/2012/01/requestcontext/claims/client-request-id)

Identifier for a user session (for troubleshooting purposes)

relyingpartytrustid (http://schemas.microsoft.com/2012/01/requestcontext/claims/relyingpartytrustid)

Identifier for the relying party

x-ms-client-application (http://schemas.microsoft.com/2012/01/requestcontext/claims/x-ms-client-application)

Type of the client application

x-ms-client-ip (http://schemas.microsoft.com/2012/01/requestcontext/claims/x-ms-client-ip)

IP address of the client

x-ms-client-user-agent (http://schemas.microsoft.com/2012/01/requestcontext/claims/x-ms-client-user-agent)

Device type the client is using to access the application

x-ms-endpoint-absolute-path (http://schemas.microsoft.com/2012/01/requestcontext/claims/x-ms-endpoint-absolute-path)

Absolute endpoint path which can be used to determine active versus passive clients.

Since multi-factor is supported only for browser applications – excepted for Office 2013 Windows client applications with the new ADAL based stack, you can use this claim to tell apart browser from non-browser requests, in case you have both kinds of protocols in the same relying party trust, which is the typical case when issuing tokens to an AD FS STS.

x-ms-forwarded-client-ip (http://schemas.microsoft.com/2012/01/requestcontext/claims/x-ms-forwarded-client-ip)

IP address of the user

x-ms-proxy (http://schemas.microsoft.com/2012/01/requestcontext/claims/x-ms-proxy)

DNS name of the federation server proxy that passed the request

insidecorporatenetwork (http://schemas.microsoft.com/ws/2012/01/insidecorporatenetwork)

Used to indicate if a request originated inside organization's corporate network. When the value is false, it means the request came through a web application proxy (WAP). When true, it means the request came directly from the browser to the AD FS STS.

Authentication information

multiple claim types (http://schemas.microsoft.com/2012/12/certificatecontext/*)

Claims that represent different fields and extensions of the X509 client certificate when used as an authentication method.

One interesting use case here is to use the EKU claim (http://schemas.microsoft.com/2012/12/certificatecontext/extension/eku) to ascertain whether the user used a smart card (exact EKU depends upon the PKI infrastructure of the customer's organization)

authenticationmethod (http://schemas.microsoft.com/ws/2008/06/identity/claims/authenticationmethod)

The primary authentication method used to authenticate the user

authnmethodsreferences (http://schemas.microsoft.com/claims/authnmethodsreferences)

Used to indicate all authentication methods used to authenticate the user

authenticationinstant (http://schemas.microsoft.com/ws/2008/06/identity/claims/authenticationinstant)

Used to display the time and date that the user was authenticated