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:
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.
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:
Note Azure AD can act as a federation hub for the last two bullets.
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:
, 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.
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.
To cover the aforementioned objectives, this document adopts an organization according to the following themes, each of them being addressed in the following sections:
(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.
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 | 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. |
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.
The Windows devices must be on the latest service packs of Windows 7, Windows 8/8.1, or Windows 10.
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.
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.
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:
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).
This section discusses the types of user authentication that work with Office 365 for a Federated Identity.
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:
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:
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.
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:
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).
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).
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:
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).
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.
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.
Use the
Microsoft Connect form
to request for your Skype for Business Online service to be enabled for modern authentication.
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:
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.
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.
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:
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.
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.
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:
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.
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:
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.
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:
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.
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:
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).
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.
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.
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.
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:
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:
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.
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.
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.
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.
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:
http://www.microsoft.com/en-us/download/details.aspx?id=47594
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:
http://connect.microsoft.com/site1164/Downloads/DownloadDetails.aspx?DownloadID=59185
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. |
The process consists in the following four steps:
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.
Alias or host: litware369.com
Value: MS=ms58060785
TTL: 1 hour
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.
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:
To execute Azure AD Connect and configure your on-premises identity infrastructure, proceed with the following steps:
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.
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:
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:
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.
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.
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:
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.
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:
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:
- and/or -
You need to manually update the configuration by proceeding as follows:
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:
PS C:\> Set-ExecutionPolicy Unrestricted
PS C:\>.\O365-Fed-MetaData-Update-Task-Installation.ps1
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
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:
To see the created scheduled task, proceed as follows:
C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe –command C:\Office365-Scripts\Microsoft-Office365-Update-MSOLFederatedDomain.ps1
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.
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:
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:
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:
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:
The following rules are declared for the Acceptance Transform Rules set regarding the Active Directory attribute store.
The incoming claim types are as follows:
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.
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:
-or-
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:
The automated definition of the trust creates 2 custom rules in the Issuance Transform Rules set.
These 2 rules are defined as follows:
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);
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:
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.
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");
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:
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.
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.
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:
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:
If, for some reason, a client is hitting the wrong endpoint, this command (Get-MsolFederationProperty) can be run to assist in determining why.
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:
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.
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:
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.
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:
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.
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.
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:
Outlook attempts to connect to Exchange Online (via Integrated Windows Authentication and the SSPI layer using Negotiate), but Exchange Online challenges for Basic Authentication.
Azure AD returns with the active profile endpoint URL (/adfs/services/trust/2005/usernamemixed) of the organization's on-premises AD FS server.
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.
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:
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.
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:
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:
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-
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-
(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:
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).
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/"));
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.
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.
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);
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/
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:
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.
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.
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.
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):
(http://schemas.microsoft.com/2012/01/requestcontext/claims/x-ms-forwarded-client-ip).
(http://schemas.microsoft.com/2012/01/requestcontext/claims/x-ms-client-application).
(http://schemas.microsoft.com/2012/01/requestcontext/claims/x-ms-client-user-agent).
(http://schemas.microsoft.com/2012/01/requestcontext/claims/x-ms-proxy).
(http://schemas.microsoft.com/ws/2012/01/insidecorporatenetwork).
(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:
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:
These enhancements are discussed in the next two sections.
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
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:
-or-
-or-
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:
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.
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.
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.
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.
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.
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 |