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.
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.
- Have an existing Azure AD tenant
- Have Azure AD Connect syncing users and computer objects (Windows 10 computer objects) from on-prem Active Directory
- Existing AD FS farm (2016 or higher) operating at functional level 3 or higher
- Federation between Azure AD and AD FS (additionally if you have more than one domain, review this)
- 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.
- Install the AD DS admin tools on your AD FS server
- Execute the following cmdlet on your AD FS server: Initialize-ADDeviceRegistration -ServiceAccountName “<your AD FS service account>”
- 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.
- Use the Azure AD Connect configuration wizard to enable device writeback
- 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:
- Validate the Registered Devices container exists at this location: CN=RegisteredDevices,DC=contoso,DC=com
- 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.
- Check the following object and confirm the msDS-CloudIssuerPublicCertificates property is now populated:
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):
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:
- Confirm all Azure AD verified domains are managed/not federated with the AD FS farm
- Add Claims Provider Trust for Azure AD to AD FS
- Add App Registration to Azure AD for AD FS
- 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:
Issue all claimsRule = x:=>issue(claim = x);
Device Claims Example
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.
Enterprise PRT for Web Apps
Check for the presence of Enterprise PRTs using the steps below:
- Start Fiddler and confirm a capture is running
- Open Internet Explorer or Edge legacy (see my note above)
- Navigate to your AD FS integrated web app
- The ESTSSSO cookie appears in the request (top right) representing the Enterprise PRT
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:
- Start Fiddler and confirm a capture is running
- Open the native app
- Initiate a sign-on request from the native app
- Look for a frame where a request is sent to AD FS and contains the ESTSSSO header in in the request (top right):
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.
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:
- Review Windows Hello for Business (hybrid deployment models) Deployment Planning Documentation
- Using Access Control Policies to require device authentication for certain apps
- Review this documentation to understand the validity period of PRTs and other tokens issued by AD FS
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!