Enterprise Primary Refresh Tokens (PRT) and AD FS

Advertisement
UPDATED 3/11/21: Added Microsoft Statement on support for Enterprise PRT on Edge, Chrome and Firefox

I am back again with another blog post! I know it has been a while but I have been busy optimizing my site for mobile devices and messing around in my lab. This post is about the Enterprise Primary Refresh Token (PRT). The Enterprise PRT is a concept specifically related to device authentication in AD FS. This concept is similar to PRTs in Azure AD except that Enterprise PRTs are used for device authentication to access resources integrated with AD FS (and not Azure AD). The main benefit of PRTs is providing end users with seamless SSO on trusted devices without having to rely on IWA (Kerberos) or traditional certificate based authentication.

Overview

If you have worked with AD FS before, you will know that the default authentication methods enabled by default are Forms Based Authentication (FBA) and Integrated Windows Authentication (IWA). To elaborate, FBA is typically used for users on the extranet/internet and IWA is used for certain browsers (based on user agent string) while on the intranet. You can enable additional authentication methods by modifying the AD FS Global Authentication Policy. For the context of this blog, the additional method we would enable here is device authentication.

Benefits of the Enterprise PRT

Long ago back during the AD FS 2012 R2 release Microsoft introduced the concept of device registration and device authentication. These features provided a better user experience for users not on the intranet and for users not using a corporate issued device. Users on a registered devices seamlessly access resources. In addition, this feature also allowed another way to perform MFA (for example password + device authentication) which could be enabled for sensitive workloads by deploying Access Control Policies (the AD FS version of Conditional Access). This original form of device authentication was based on TLS and device certificates.

Fast forward to AD FS 2016 and higher where the concept of a Primary Refresh Token was born. The PRT concept first existed in early versions of Windows 10 (I recall initially seeing the PRT introduced in version 1511). It is essentially a special type of refresh token issued by AD FS (and Azure AD) to known and registered devices.

PRTs allow web apps and native apps integrated with AD FS (Enterprise Primary Refresh Token) and Azure AD (Primary Refresh Token) to seamlessly obtain tokens without prompting the end user for authentication. The way this happens under the covers depends on the OS and depends on the type of app in use (web app vs. native app). For this article, I will focus on Windows 10 and not iOS or Android. Importantly, be aware that the PRT also exists for registered mobile devices as well and provides the same benefits.

Enterprise Primary Refresh Token Prerequisites

You need to meet some requirements in order to start issuing Enterprise Primary Refresh Tokens to registered devices. In support of this I have put together a list below. It is important to call out that recent optimizations in Azure AD Connect have made meeting these requirements much easier! Here I am making the assumption that you have an Azure AD tenant and plan to use Azure AD Device Registration Service (DRS). Only registered devices can obtain PRTs! However, if your organization does not have Azure AD and does not plan to have it in the future, you could also enable device registration in an on-premises only mode by using AD FS DRS.

  1. Have an existing Azure AD tenant
  2. Have Azure AD Connect syncing users and computer objects (Windows 10 computer objects) from on-prem Active Directory
  3. Existing AD FS farm (2016 or higher) operating at functional level 3 or higher
  4. Federation between Azure AD and AD FS (additionally if you have more than one domain, review this)
  5. Review the Hybrid Azure AD Join prerequisites documentation

Initial Configuration Steps for Enterprise Primary Refresh Token Enablement

Assuming you have all of the prerequisites met, you can proceed to the initial configuration steps for enabling the issuance of Enterprise PRTs. These steps include enabling Hybrid Azure AD Joined devices, enabling Azure AD device writeback and enabling device authentication in AD FS.

  1. Install the AD DS admin tools on your AD FS server
  2. Execute the following cmdlet on your AD FS server: Initialize-ADDeviceRegistration -ServiceAccountName “<your AD FS service account>”
  3. Use the Azure AD Connect configuration wizard to enable hybrid Azure AD Join for devices. It is important to note that If your version of Azure AD Connect does not have this option, either upgrade it or perform these steps manually.

NOTE: Deploy this Group Policy setting to control when Windows 10 devices are hybrid Azure AD joined.

  1. Use the Azure AD Connect configuration wizard to enable device writeback
  2. Validate the DRS container objects exist by performing the following steps:
    • Open adsiedit.msc and connect to the Configuration partition
    • Navigate to the following path: CN=Device Registration Configuration,CN=Services,CN=Configuration,DC=contoso,DC=com
    • Validate the following objects exist:
The Device Registration Configuration container should now contain the objects pictured here
Advertisement
  1. Validate the Registered Devices container exists at this location: CN=RegisteredDevices,DC=contoso,DC=com
  2. Ensure the msDS-CloudIssuerPublicCertificates property is populated by Azure AD Connect. This can be completed by performing the following steps on your active AAD Connect server:
    • Initialize a new incremental sync by running Start-ADSyncSyncCycle
    • Check the Application log in event viewer for the following event:

Device Certificate Sync Event

Log Name: Application
Source: Directory Synchronization
Date: 4/23/2020 11:59:18 AM
Event ID: 904
Task Category: None
Level: Information
Keywords: Classic
User: N/A
Computer: aadcserver.controso.com
Description:
Finished: Device Certificate Sync Step. Duration: 0 sec.
  1. Check the following object and confirm the msDS-CloudIssuerPublicCertificates property is now populated:
The msDS-CloudIssuerPublicCertificates property should be populated so AD FS is aware of the signing certificates used by the Azure AD DRS when device certificates are generated

NOTE: AAD Connect syncs the Azure AD DRS signing certificate once per day. New deployments will have the certificate populated after the next sync cycle as in these cases it has not been executed before.

Other Important Considerations

Once devices are able to register with Azure AD, the device objects created in Azure AD will synchronize back to on-prem Active Directory on the next scheduled sync. The msDS-KeyCredentialLink property must be populated for an Enterprise PRT to be issued. This may require an additional synchronization.

Another consideration is the BrowserSSO related settings in AD FS. You can specify a list of user agents to be enabled for use with Enterprise Primary Refresh Tokens by populating the BrowserSsoSupportedUserAgents paramenter. This is a list of browsers allowed to use the Enterprise PRT for web apps. It is worth noting that this works similarly to the WIASupportedUserAgents setting.

Enable AD FS Device Authentication

Now that you have completed the prerequisites to issue Enterprise PRTs in AD FS you can enable device authentication in AD FS. The cmdlet used to enable device authentication is:

Set-AdfsGlobalAuthenticationPolicy -DeviceAuthenticationEnabled $true -DeviceAuthenticationMethod SignedToken

To control the allowed authentication methods for devices set the DeviceAuthenticationMethod parameter. The device authentication methods can also be specified on a specific Relying Party Trust or on a specific Web App/API in an application group (for OAuth and OpenID Connect based apps integrated with AD FS). For Windows 10 devices we are targeting ‘SignedToken’.

Validate AD FS Device Authentication

You can use two methods to validate the issuance of Enterprise PRTs. One method will validate the issuance of the PRT from the device side using DSRegCMD. The other will validate the issuance of the PRT and the related device claims with a sample web app.

Use DSRegCMD Tool

In Windows 10, you can open a command prompt and run dsregcmd /status. This will result in output similar to the following (this output varies based on the version of Windows 10 being used):

The properties highlighted in red can be used to validate if the device was successfully hybrid joined to Azure AD and to determine if an Azure AD PRT and AD FS PRT have been issued

In the image above, I highlighted the key properties in red. Only trusted devices can be issued Enterprise PRTs. The example above shows a device which has been successfully joined to Azure AD. As a result, it has an Azure AD PRT as well as an AD FS Enterprise PRT.

Validate Device Claims with Sample Web App

It is always helpful to have a sample app deployed and integrated with your AD FS farm. This allows you to easily test claims issuance rules, access control policies and more! Check out this sample web app which uses MSAL and integrates with AD FS. In addition, check out the Claims X-Ray tool on AD FS Help from Microsoft.


Supported Browser Limitations – Updated 3/11/21

NOTE: Only Internet Explorer and the legacy version of Edge support the use of the Enterprise PRT for web apps. Microsoft has stated there are no plans to develop a browser plug-in for Edge, Chrome or Firefox. A suggestion was provided in order to provide SSO to all AD FS integrated apps for these browsers. It is only viable in scenarios where the AD FS farm is not federated with your Azure AD tenant (domains are in managed mode). Here are the high level steps:

  1. Confirm all Azure AD verified domains are managed/not federated with the AD FS farm
  2. Add Claims Provider Trust for Azure AD to AD FS
  3. Add App Registration to Azure AD for AD FS
  4. Add linked sign-on app to My Apps portal ensuring the WHR parameter (WS-Fed or SAML apps) or the domain_hint (OAuth/Open ID) parameter is sent in the request to AD FS

With my sample app, I now see additional claims issued by AD FS related to the device context of the device I am using. Additional claims are added when device authentication is enabled. Send all claims to the sample app by configuring the Claim Issuance rules appropriately. Here is a claim rule which passes through all issued claims:

Name = Issue all claims
Rule = x:[]=>issue(claim = x);

Device Claims Example

ClaimValue
http://schemas.microsoft.com/2012/01/devicecontext/claims/displaynamecontoso-ws
http://schemas.microsoft.com/2012/01/devicecontext/claims/identifieracff3dc2-3a1c-40c3-bb28-455de882255d
http://schemas.microsoft.com/2012/01/devicecontext/claims/ismanagedTRUE
http://schemas.microsoft.com/2012/01/devicecontext/claims/isregistereduserTRUE
http://schemas.microsoft.com/2012/01/devicecontext/claims/ostypeWindows
http://schemas.microsoft.com/2012/01/devicecontext/claims/osversion10.0 (18362)
http://schemas.microsoft.com/2012/01/devicecontext/claims/registrationid11E33DDEDC8F1B2CCBE9212EB01B75E4272A7FAD
http://schemas.microsoft.com/2014/02/devicecontext/claims/isknownTRUE
http://schemas.microsoft.com/2014/02/deviceusagetime2020-04-23T19:18:03.726Z
http://schemas.microsoft.com/2014/03/pssoTRUE
http://schemas.microsoft.com/2014/09/devicecontext/claims/iscompliantFALSE
http://schemas.microsoft.com/2014/09/devicecontext/claims/trusttypeWorkplace
http://schemas.microsoft.com/2015/09/prtpassword
Device context claims issued once device authentication is enabled. Note the prt claim and the psso claim!

Using Fiddler to Check for Enterprise PRT Usage

You can use Fiddler to check for PRTs added to AD FS requests. PRTs passed in requests to AD FS enable end users to experience seamless SSO for AD FS integrated apps. This includes native apps and web apps.

Assuming you do not have Fiddler installed yet, follow these instructions to install Fiddler. Secondly, follow these instructions to decrypt HTTPS traffic.

Enterprise PRT for Web Apps

Check for the presence of Enterprise PRTs using the steps below:

  1. Start Fiddler and confirm a capture is running
  2. Open Internet Explorer or Edge legacy (see my note above)
  3. Navigate to your AD FS integrated web app
  4. The ESTSSSO cookie appears in the request (top right) representing the Enterprise PRT
When the Enterprise PRT is sent in requests to AD FS it appears in the request header as a series of cookies

You can see the ESTSSSO cookies being sent in the requests to the AD FS server in the example above. This provides seamless SSO for the end user’s browser session for AD FS integrated web apps. Notice that FBA and IWA are not used.

Enterprise PRT for Native Apps

Native Apps integrated with AD FS using MSAL or ADAL libraries can also take advantage of the Enterprise PRT. Subsequently, by using the Enterprise PRT end users experience seamless SSO to these apps.

Check out this official sample native app from Microsoft. You can use Fiddler to validate the use of Enterprise PRTs. To do this perform the following steps:

  1. Start Fiddler and confirm a capture is running
  2. Open the native app
  3. Initiate a sign-on request from the native app
  4. Look for a frame where a request is sent to AD FS and contains the ESTSSSO header in in the request (top right):
The ESTSSSO cookies also appear for native apps when the native apps are using MSAL or ADAL libraries

Once again, you can see the ESTSSSO cookies being sent in the requests to the AD FS server. This provides seamless SSO for the end user when accessing the AD FS integrated native app.

Closing Summary

Now that you have enabled device authentication in AD FS and have validated Enterprise PRTs are being issued you can provide seamless SSO to your end users when accessing AD FS integrated apps. This is regardless of their network location when using trusted devices. More importantly, you are also one step closer to going password-less as device registration and authentication are required for Windows Hello for Business. Additionally, don’t forget that Azure AD also issues PRTs so your users will also have seamless SSO for Azure AD integrated apps! As next steps I would recommend reviewing the list below:

Action Items

Leave Feedback

I hope this post was helpful. Thanks for checking it out! Please leave comments and feedback as it is valuable! Also, if you want to check out more, check out my previous posts. Until next time, rock on!

4 thoughts on “Enterprise Primary Refresh Tokens (PRT) and AD FS”

  1. I have been wracking my brain for a while now trying to figure out why device authentication won’t work with non-IE and newer chromium based browsers. Finally I came across acknowledgement in your article. You mentioned that you have brought this up to Microsoft which was almost a year ago. Do you know if there is any update on this? Is there any official acknowledgement of the problem, or any way for me to know when they’ve got it fixed? I appreciate it.

    1. Hi Michael,

      Thanks for reading! I have actually received an update from Microsoft. There are no plans for a browser plug-in to be developed to support the Enterprise PRT. Therein lies the issue. Microsoft did suggest a workaround to get SSO in these browsers for all AD FS integrated apps but it would not be feasible if your AD FS farm is still federated with Azure AD. I will post the details in this blog post in a few minutes.

      -Ed

    1. Yes you are correct. It seems there are no plans to have a plug-in developed for Chrome and Firefox to support Enterprise PRTs. However, they do support the Azure AD PRTs.

Comments are closed.