Claims X-Ray ADFS Online Troubleshooting Tool

When you are troubleshooting an ADFS deployment, or you’re working with a 3rd party vendor on authentication issues, or maybe when you’re just interested in a deep dive in your ADFS environment, then there are multiple tools available from Microsoft for testing purposes.
To learn more about ADFS in general the Active Directory Federation Services Wiki Portal is a good starting point, for online tools the ADFS Help from Microsoft (https://adfshelp.microsoft.com) is a good starting point.

One of the interesting online tools for troubleshooting ADFS is called Claims X-Ray. Claims X-Ray consists of a dedicated Relying Party Trust (RPT) in your ADFS environment. You can logon to the RPT automatically using the online tool, or manually via the ADFS IdpInitiatedSignon page (as discussed in my previous blogpost Implementing Active Directory Federation Services step-by-step)
The X-Ray Relying Party Trust can be created using the following PowerShell commands on your (primary) ADFS server:

[PS] C:\> {$authzRules = "=>issue(Type = `"http://schemas.microsoft.com/authorization/claims/permit`", Value = `"true`"); "
[PS] C:\> $issuanceRules = "@RuleName = `"Issue all claims`"`nx:[]=>issue(claim = x); "
[PS] C:\> $redirectUrl = "https://adfshelp.microsoft.com/ClaimsXray/TokenResponse"
[PS] C:\> $samlEndpoint = New-AdfsSamlEndpoint -Binding POST -Protocol SAMLAssertionConsumer -Uri $redirectUrl

[PS] C:\> Add-ADFSRelyingPartyTrust -Name "Claims X-ray" -Identifier "urn:microsoft:adfs:claimsxray" -IssuanceAuthorizationRules $authzRules -IssuanceTransformRules $issuanceRules -WSFedEndpoint $redirectUrl -SamlEndpoint $samlEndpoint

As shown in the following screenshot:

ADFS RPT X-Ray

If you want to test the Claims X-Ray using oAuth you need to create the oAuth client using the following PowerShell commands, again on your (primary) ADFS server:

[PS] C:\> Add-AdfsClient -Name "Claims X-ray Client" -ClientId "claimsxrayclient" -RedirectUri https://adfshelp.microsoft.com/ClaimsXray/TokenResponse
[PS] C:\> if ([System.Environment]::OSVersion.Version.major -gt 6) { Grant-AdfsApplicationPermission -ServerRoleIdentifier urn:microsoft:adfs:claimsxray -AllowAllRegisteredClients -ScopeNames "openid","profile" }

X-Ray oAuth client

When the Relying Party Trust is created you can continue with the online tool to test it, and thus have a closer look at your environment. In the Claims X-Ray tool enter the federation instance (i.e. federation.exchangelabs.nl) and click Test Authentication as shown in the following screenshot:

Claims X-Ray

It will redirect to your WAP server (default ADFS behavior), enter valid user credentials and it will show the returned SAML token, including the claims it contains.

If I do this for my own environment, it will return a token with 21 claims which contain interesting information like the IP address of the originating client (userip or x-ms-forwarded-client-ip, where I ran the web browser), the IP address of the ADFS WAP server (x-ms-clientip), the type of browser I am using, whether I’m on the corporate network or not, the UPN, implicit UPN and Windows accountname to name a few. A couple of these claims are shown in the following screenshot:

ADFS Token Claims

It is also possible to use the IdpInitiatedSignon page, the Claims X-Ray RPT option is added to this page by the PowerShell commands:

Claims X-Ray initiated signon

When you logon you’ll see a new token with different claims, depending on the location where you are logged on at that moment. While commuting in the train for example I can figure out the way I’m authenticated by ADFS and which claims are issued for this particular scenario:

Claims X-Ray initiated signon authentication

Using the Claims X-Ray online tool you can test the behavior of your ADFS environment from different clients, networks etc. when you have to troubleshoot your environment, or if you are just interested.

For example, at the moment I’m working on an issue where we are difficulties with a MobileIron deployment that needs to authenticate against an ADFS deployment. The rules and policies from the regular RPT can be copied to the Claims X-Ray RPT, after which you can determine the behavior of the RPT, and hopefully figure out why it won’t work in the first place.

More information

Claims X-Ray – https://adfshelp.microsoft.com/ClaimsXray/TokenRequest

 

Upgrade Azure Connect

Although it is possible to auto-upgrade your Azure AD Connect server, not all releases are available through the auto-upgrade mechanism.

The current version of Azure AD Connect is 1.4.38.0, released on December 9, 2019 and is not available through auto-upgrade for example. The version on my Azure AD connect server is 1.4.18.0. You can easily check this in Control Panel | Programs | Programs and Features.

Azure AD Connect 1.4.18.0

For the version release history of Azure AD Connect check this page: Azure AD Connect: Version release history.

Upgrading is easy, download the latest version from Microsoft Azure Active Directory Connect download page and start the downloaded Windows installer package. When the Upgrade Azure Active Directory Connect window appears, click Upgrade and follow the wizard.

Upgrade Azure AD Connect

Enter the global tenant admin password in the Connect to Azure AD window, click Next and the Ready to Configure window appears.

Start the synchronization process when configuration completes

It will upgrade the Azure AD synchronization configuration and it will enable auto-upgrade. If needed, you can uncheck the start the synchronization process when configuration completes checkbox, this way you can make manual changes before synchronization start.

Click Upgrade and with 2 minutes the upgrade is finished, and synchronization will resume.

 

Implementing Active Directory Federation Services step-by-step part II

In the previous blog (Implementing Active Directory Federation Services step-by-Step) I have showed you how to install and configure Active Directory Federation Services (ADFS) in your internal network and DMZ, capable of handling Office 365 authentication request. In this blog I’ll show you how to configure Office 365 and how to test it.

Federated Domains

In a typical managed domain, the user accounts and password hashes are synchronized to Azure Active Directory. Office 365 uses Domain Controllers in Azure AD to authenticate the users and grant them access to the resources in the cloud.

In a federated domain, the user accesses the Office 365, but access is denied, and the request is redirected to Azure Active Directory. There, the home realm (the user’s domain) is discovered and the request is redirected to the ADFS server based on the home realm. If my user account is j.wesselius@exchangelabs.nl, my home realm is exchangelabs.nl and the request is redirected to the federation server that was created earlier, and that was used to configure the domain in Azure Active Directory.

I did a session on this at IT Dev Connections in 2017 (in San Francisco), the following is one animated slide that can be downloaded which shows the flow between a client, Office 365, Azure AD and the on-premises ADFS and Domain Controller:

ADFS Federation Flow

To get this working, the domain in Azure Active Directory needs to be converted to a federated domain so that Azure AD knows any authentication request needs to be redirected to the on-premises ADFS environment.

When adding a domain to Azure Active Directory it is automatically created as a managed domain. As said before, authentication takes places against Domain Controllers in Azure AD. You can check a domain using the Get-MsolDomain -DomainName exchangelabs.nl PowerShell command as shown in the following screenshot:

Get-MsolDomain

To convert this to a federated domain, start a PowerShell command (with elevated privileges) and enter the following commands:

[PS] C:\> Connect-MsolService

[PS] C:\> Set-MsolADFSContext -Computer ams-adfs01.labs.local

[PS] C:\> Convert-MsolDomainToFederated -DomainName Exchangelabs.nl

Note. Use the FQDN of the local first ADFS server with the Set-MsolADFSContext command, not the federation URL

This will connect the existing on-premises infrastructure to Azure AD, and convert the domain to a federated domain. Now, when checking the domain in Azure AD using the same command as before you’ll see it now is a federated domain:

Set-MsolAdfsContext Exchangelabs

In in the ADFS Management Console you’ll a new Relying Party Trust (RPT) for use with Office 365:

ADFS Relying Party Trust

To get more into detail in Azure AD about the federation settings, you can use the Get-MsolDomainFederationSettings command which shows more information:

Get-MsolDomainFederationSettings

Clearly visible are the Logon, Issuer and LogOffUri, which point to our on-premises ADFS implementation. Even more information can be retrieved using the Get-MsolFederationProperty command as shown in the following screenshot:

Get-MsolFederationProperty

To test the new configuration, navigate to the Microsoft Online Portal and login using an account with the domain we just configured, i.e. j.wesselius@exchangelabs.nl:

Microsoft Online Portal

When selecting this account, Azure AD determines the home realm (exchangelabs.nl) and redirect to the on-premises URL as found in the federation settings in Azure AD. You’ll see this happen on the fly in your browser:

Taking you to your organizations sign-in page

And a few seconds later we are redirected to our on-premises ADFS environment:

ADFS Federation Sign-in page

Clearly visible is the Federation Service display Name which was configured with the first ADFS server in the previous blogpost.

Enter your password, and how wonder, MFA is still working as well (which was a pleasant surprise for me 😊):

ADFS Exchangelabs MFA

Another interesting test is using the Remote Connectivity Analzyer ( (https://aka.ms/exrca) which has a Single Sign-On test. Navigate to the Remote Connectivity Analyzer, click the Office 365 tab and select the Office 365 Single Sign-On test radio button.

Enter username and password, do the verification code test and await the results. You’ll see something similar as the following screenshot:

Remote Connectivity Analyzer Single Sign-On Test

The logon attempt was successful, but more interesting is that you can expand all test steps to see what’s going on under the hood and try to understand how ADFS works.

Summary

In the previous two blogposts I demonstrated how to install and configure ADFS in your on-premises infrastructure. I installed only one ADFS server and one WAP proxy, which is far from a high available environment. Why high available? Without the ADFS server it is no longer possible to logon to any Office 365 service, so a high available infrastructure is a requirement for any ADFS implementation.

But customers are moving to the cloud to decommission their on-premises solutions, and with ADFS we’re building an on-premises solution for authenticating cloud solutions. But for compliancy reasons it might be needed to authenticate against local domain controllers (no passwords in the cloud for example). On the other hand, you can use Pass Through Authentication (PTA, see my blogpost Azure AD Connect Pass-through authentication) for this as well. PTA doesn’t offer as much possibilities as ADFS yet, but it is improving.

Is ADFS future proof? Some people say it isn’t, but as long as I find articles like What’s new in Active Directory Federation Services for Windows Server 2019 on the Microsoft website I don’t see too many issues with that.

More information

Implementing Active Directory Federation Services step-by-step

In 2013 I installed my first ADFS environment and I was pretty impressed. Several other deployments followed and I always wanted to blog about it, but it never happened. A good way to start the new year, approx. 7 years after I deployed my first ADFS environment here’s my blog about implemeting ADFS 😊

I am not going to discuss pros and cons of password hash synchronization, Pass-through Authentication (PTA) or 3rd party solutions like Octa. Neither am I going to discuss whether you should implement ADFS or another solution. I just see a lot of customers using password hash synchronization and looking into other scenarios where authentication takes place in-house (for all kind of reasons). In this blogpost I will show you in a step-by-step manner how to deploy a federation infrastructure based on ADFS.

In Office 365 there are multiple ways for users to authenticate, and this is related to the type of identity being used:

  • Cloud Identity – is created in the cloud, password lives in the cloud and user authenticates in the cloud.
  • Synced Identity – is create in on-premises Active Directory and is synchronized to the cloud, including its password (most of the times). User authenticates in the cloud with on-premises password.
  • Federated Identity – is created in on-premises Active Directory and is synchronized to the cloud, sometimes including its password (recommended for disaster recovery). User authenticates against on-premises Domain Controllers using federation infrastructure (ADFS).

Active Directory Federation Services

In a federated environment when you try to logon to a cloud service (in Office 365 this can be SharePoint, Teams, Exchange, OneDrive, the Microsoft Portal) an authentication request is presented. Instead of entering a password that can be authenticated by an Azure AD Domain Controller, the request is redirected to an on-premises federation server. This service is called the Security Token Service or STS. The STS in an Active Directory environment is implemented by means of an ADFS instance running on a Windows 2016 server in the DMZ. This is the Windows Application Proxy or WAP server. Common names for this server are sts.contoso.com, adfs.contoso.com or federation.contoso.com.

The authentication request is proxied to the internal ADFS server, which hands over the request to an Active Directory Domain Controller. Once authenticated, the ADFS server uses the STS to return a SAML token which authenticates the user in the Office 365 service.

For this to work you need an Azure AD Connect server which synchronized the accounts in Active Directory to Azure Active Directory. This is not different from a password hash synchronization solution. Then you need an ADFS solution on-premises which handles the requests from Office 365. The last thing you need is a domain in Azure AD that’s configured as a federated domain, where a regular domain is configured as a managed domain.

This is show in the following figure:

Federation Infrastructure

I assume that you already have configured your Office 365 tenant and that Azure AD is already up-and-running and you have synced identities in your Office 365 environment. At this point they can be configured with mailboxes, that’s not important for the remainder of this blogpost.

My WAP server is a stand-alone Windows 2016 server (in the DMZ) named ams-sts01.exchangelabs.nl. It has a Digicert certificate with the federation.exchangelabs.nl as the Common Name. It has an internal IP address and an external IP address. It can resolve IP addresses of internal servers (be aware that federation.exchangelabs.nl should resolve to the internal ADFS server) and is externally only accessible on port 443.

The internal ADFS server is a domain-joined Windows 2016 server with only an internal IP address (of course) named AMS-ADFS01. It has the same SSL certificate as the WAP server (federation.exchangelabs.nl). The WAP server should be able to reach this server on port 443.

Building the infrastructure

Building the ADFS infrastructure consists of several steps:

  • Deploying the first ADFS server of an ADFS farm (Configuration of the first ADFS server is part of the installation process).
  • Deploying additional servers in the ADFS farm (not in this blogpost).
  • Deploying the first WAP server in the DMZ.
  • Configure te first WAP server.
  • Deploying additional servers in the DMZ (not in this blogpost).

I will discuss these steps in the following sections.

Deploying the first federation server

The first step is to deploy the internal ADFS server. After installing and patching the Windows 2016 server this you can use Server Manager to install the ADFS server role. Open Server Manager, select local server, click Manage and select Add Roles and Features.

In the Add Roles and Features wizard, click Role-Based or feature-based installation, select the server you want to install the ADFS role and check the Active Directory Federation Services checkbox. Leave the select features options default and finish the wizard. The ADFS Role will now be installed.

When the installation has finished, click on configure the federation service on this server to start the ADFS configuration.

Create the first federation server in a federation farm

Specify an account with sufficient privileges to perform the ADFS configuration. Typically, a domain administrator account will do. When needed, select an alternative account, otherwise click Next to continue.

You can import the SSL certificate from a PFX file, or if you have imported the SSL certificate during installation of the Windows 2016 server you can use the drop-down box to select it. Enter a federation service name, this is the name that’s visible on the ADFS logon page after installation, so you should use a name that makes sense.

ADFS Service Properties

The following step is to enter a service account that’s used by the ADFS service. You can manually create one, or use a group managed service account. This as the advantage of changing its password automatically, so I recommend using this.

ADFS Group Managed Service Account

Next is the selection of the database where the configuration data is stored. This can be a Windows Internal Database or a SQL database. I will skip this screenshot.
The last step is to review the configuration options:

ADFS Review Options

When the review options are ok, you can click Next and a prerequisite check is performed.

ADFS Prerequisite checks

When all prerequisites are installed and configured correctly you can click Configure and the installation and configuration of the first ADFS server will be started. After a few minutes the installation and configuration is finished and the results are shown:

ADFS this server was configured successfully

At this moment I don’t worry about the warning messages. Click Close and reboot the server as requested.

On the internal DNS server, create an A record for your federation server (federation.exchangelabs.nl) and point it to your internal ADFS server. Also create a CNAME record for enterpriseregistration, and use the FQDN of your ADFS server (federation.contoso.com).

When the ADFS server is rebooted and the DNS record is in place you can use a URL similar to this one (https://federation.exchangelabs.nl/adfs/fs/federationserverservice.asmx) to check the federation service on your ADFS server. It will show an XML output similar to the following screenshot:

Check Federation Service

At this point you have successfully deployed your first ADFS server. The next step is to deploy the first WAP server.

Deploying the Proxy servers

After installing and patching the Windows 2016 server (don’t forget the SSL certificate) you can use Server Manager to install the Web Application Server as part of the Remote Access services. In the Add Roles and Features wizard, click Role-Based or feature-based installation, select the server you want to install the Web Application Proxy role and check the Remote Access checkbox.

Server Roles Remote Access

Leave the select features options default, and in the Role Services window check the Web Application Proxy checkbox. In the additional features pop-up window click on Add Features and continue with the wizard to install the Web Application Proxy server.

When the WAP server software is installed, click on Open the Web Application Proxy wizard (under notifications in Server Manager).

For the federation service name use the name you are planning to use (i.e. federation.exchangelabs.nl) and enter the credentials of a local administrator on the ADFS server that was installed in the previous section.

WAP Federation Server

Select the SSL certificate that was installed on the Windows 2016 server during installation (I will skip this screenshot here) and the confirmation window will be shown.

WAP Confirmation

Click Configure to start the configuration of the Web Application Proxy server and after a few moments the Results window will be shown.

To check the operations status of the WAP server after the installation, open the Remote Access Management Console (under Administrative Tools), click on the server and you’ll see two green checkboxes to indicate the server is up-and-running:

Remote Access Operational Status

You can also check the Event viewer. Under xx/xx/xx you should be able to find EventID 245, indication that the WAP server successfully retrieved its configuration settings from the internal ADFS server:

ADFS Event ID 245

A quick external check can be to retrieve the federation metadata from your ADFS server. From an external client use a URL similar to this (https://federation.exchangelabs.nl/federationmetadata/2007-06/federationmetadata.xml) to retrieve the federation metadata. It should shown an XML output similar to the following:

ADFS Federation MetaData

Another test is to use the Idp Initiated Signon page, located on https://federation.exchangelabs.nl/adfs/ls/idpinitiatedsignon.htm. There’s one catch here, this is enabled by default in Windows 2012 R2, but not in Windows 2016. To enable it, execute the following PowerShell command on your (internal) ADFS server:

[PS] C:\> Set-AdfsProperties –EnableIdpInitiatedSignonPage $True

Now when you navigate to the IdpInitiatedSignon page you’ll see a static HTML page with a Sign In button. When you click on it you can use your credentials to sign in to your environment and you’ll see something like the following screenshot:

idp initiated signon page

Now we know the ADFS environment is working properly, and we can continue with the configuration of Azure AD and Office 365.

At this moment we’ve installed and configured a simple ADFS infrastructure into the existing on-premises Windows environment, capable of handling Office 365 authentication request. I will discuss the configuration of Office 365 (and thus Azure Active Directory) in the next blog.