What is a Primary Refresh Token?

 Article
 03/17/2023
 14 contributors
Feedback

In this article
1. Key terminology and components
2. What does the PRT contain?
3. How is a PRT issued?
4. What is the lifetime of a PRT?
Show 7 more

A Primary Refresh Token (PRT) is a key artifact of Azure AD authentication on

Windows 10 or newer, Windows Server 2016 and later versions, iOS, and Android
devices. It's a JSON Web Token (JWT) specially issued to Microsoft first party token
brokers to enable single sign-on (SSO) across the applications used on those devices.
In this article, provide details on how a PRT is issued, used, and protected on
Windows 10 or newer devices. We recommend using the latest versions of Windows
10, Windows 11 and Windows Server 2019+ to get the best SSO experience.

This article assumes that you already understand the different device states available
in Azure AD and how single sign-on works in Windows 10 or newer. For more
information about devices in Azure AD, see the article What is device management in
Azure Active Directory?

Key terminology and components

The following Windows components play a key role in requesting and using a PRT:

 Cloud Authentication Provider (CloudAP): CloudAP is the modern

authentication provider for Windows sign in, that verifies users logging
to a Windows 10 or newer device. CloudAP provides a plugin framework
that identity providers can build on to enable authentication to Windows
using that identity provider’s credentials.
 Web Account Manager (WAM): WAM is the default token broker on
Windows 10 or newer devices. WAM also provides a plugin framework
that identity providers can build on and enable SSO to their applications
relying on that identity provider.

1
  Azure AD CloudAP plugin: An Azure AD specific plugin built on the
CloudAP framework that verifies user credentials with Azure AD during
Windows sign in.
 Azure AD WAM plugin: An Azure AD specific plugin built on the WAM
framework that enables SSO to applications that rely on Azure AD for
authentication.
 Dsreg: An Azure AD specific component on Windows 10 or newer, that
handles the device registration process for all device states.
 Trusted Platform Module (TPM): A TPM is a hardware component built
into a device that provides hardware-based security functions for user
and device secrets. More details can be found in the article Trusted
Platform Module Technology Overview.

What does the PRT contain?

A PRT contains claims found in most Azure AD refresh tokens. In addition, there are
some device-specific claims included in the PRT. They are as follows:

 Device ID: A PRT is issued to a user on a specific device. The device ID

claim deviceID determines the device the PRT was issued to the user on.
This claim is later issued to tokens obtained via the PRT. The device ID
claim is used to determine authorization for Conditional Access based on
device state or compliance.
 Session key: The session key is an encrypted symmetric key, generated
by the Azure AD authentication service, issued as part of the PRT. The
session key acts as the proof of possession when a PRT is used to obtain
tokens for other applications. Session key is rolled on Windows 10 or
newer Azure AD joined or Hybrid Azure AD joined devices if it's older
than 30 days.

Can I see what’s in a PRT?

A PRT is an opaque blob sent from Azure AD whose contents aren't known to any
client components. You can't see what’s inside a PRT.

How is a PRT issued?

Device registration is a prerequisite for device based authentication in Azure AD. A
PRT is issued to users only on registered devices. For more in-depth details on device
registration, see the article Windows Hello for Business and Device Registration.

2
During device registration, the dsreg component generates two sets of cryptographic
key pairs:

 Device key (dkpub/dkpriv)

 Transport key (tkpub/tkpriv)

The private keys are bound to the device’s TPM if the device has a valid and
functioning TPM, while the public keys are sent to Azure AD during the device
registration process. These keys are used to validate the device state during PRT
requests.

The PRT is issued during user authentication on a Windows 10 or newer device in

two scenarios:

 Azure AD joined or Hybrid Azure AD joined: A PRT is issued during

Windows logon when a user signs in with their organization credentials.
A PRT is issued with all Windows 10 or newer supported credentials, for
example, password and Windows Hello for Business. In this scenario,
Azure AD CloudAP plugin is the primary authority for the PRT.
 Azure AD registered device: A PRT is issued when a user adds a
secondary work account to their Windows 10 or newer device. Users can
add an account to Windows 10 or newer in two different ways -
o Adding an account via the Allow my organization to manage
my device prompt after signing in to an app (for example,
Outlook)
o Adding an account from Settings > Accounts > Access Work
or School > Connect

In Azure AD registered device scenarios, the Azure AD WAM plugin is the primary
authority for the PRT since Windows logon isn't happening with this Azure AD
account.

Note

3rd party identity providers need to support the WS-Trust protocol to enable PRT
issuance on Windows 10 or newer devices. Without WS-Trust, PRT cannot be issued
to users on Hybrid Azure AD joined or Azure AD joined devices. On ADFS only
usernamemixed endpoints are required. Both
adfs/services/trust/2005/windowstransport and
adfs/services/trust/13/windowstransport should be enabled as intranet facing
endpoints only and must NOT be exposed as extranet facing endpoints through the
Web Application Proxy.

Note

3
Azure AD Conditional Access policies are not evaluated when PRTs are issued.

Note

We do not support 3rd party credential providers for issuance and renewal of Azure
AD PRTs.

What is the lifetime of a PRT?

Once issued, a PRT is valid for 14 days and is continuously renewed as long as the
user actively uses the device.

How is a PRT used?

A PRT is used by two key components in Windows:

 Azure AD CloudAP plugin: During Windows sign in, the Azure AD

CloudAP plugin requests a PRT from Azure AD using the credentials
provided by the user. It also caches the PRT to enable cached sign in
when the user doesn't have access to an internet connection.
 Azure AD WAM plugin: When users try to access applications, the
Azure AD WAM plugin uses the PRT to enable SSO on Windows 10 or
newer. Azure AD WAM plugin uses the PRT to request refresh and access
tokens for applications that rely on WAM for token requests. It also
enables SSO on browsers by injecting the PRT into browser requests.
Browser SSO in Windows 10 or newer is supported on Microsoft Edge
(natively), Chrome (via the Windows 10 Accounts or Office
Online extensions) or Mozilla Firefox v91+ (Firefox Windows SSO setting)
Note

In instances where a user has two accounts from the same Azure AD
tenant signed in to a browser application, the device authentication
provided by the PRT of the primary account is automatically applied to
the second account as well. As a result, the second account also satisfies
any device-based Conditional Access policy on the tenant.

How is a PRT renewed?

A PRT is renewed in two different methods:

4
  Azure AD CloudAP plugin every 4 hours: The CloudAP plugin renews
the PRT every 4 hours during Windows sign in. If the user doesn't have
internet connection during that time, CloudAP plugin will renew the PRT
after the device is connected to the internet.
 Azure AD WAM plugin during app token requests: The WAM plugin
enables SSO on Windows 10 or newer devices by enabling silent token
requests for applications. The WAM plugin can renew the PRT during
these token requests in two different ways:
o An app requests WAM for an access token silently but there’s
no refresh token available for that app. In this case, WAM uses
the PRT to request a token for the app and gets back a new
PRT in the response.
o An app requests WAM for an access token but the PRT is
invalid or Azure AD requires extra authorization (for example,
Azure AD Multifactor Authentication). In this scenario, WAM
initiates an interactive logon requiring the user to
reauthenticate or provide extra verification and a new PRT is
issued on successful authentication.

In an ADFS environment, direct line of sight to the domain controller isn't required to
renew the PRT. PRT renewal requires only /adfs/services/trust/2005/usernamemixed
and /adfs/services/trust/13/usernamemixed endpoints enabled on proxy by using
WS-Trust protocol.

Windows transport endpoints are required for password authentication only when a
password is changed, not for PRT renewal.

Note

Azure AD Conditional Access policies are not evaluated when PRTs are renewed.

Key considerations

 A PRT is only issued and renewed during native app authentication. A

PRT isn't renewed or issued during a browser session.
 In Azure AD joined and hybrid Azure AD joined devices, the CloudAP
plugin is the primary authority for a PRT. If a PRT is renewed during a
WAM-based token request, the PRT is sent back to CloudAP plugin,
which verifies the validity of the PRT with Azure AD before accepting it.

How is the PRT protected?

5
A PRT is protected by binding it to the device the user has signed in to. Azure AD
and Windows 10 or newer enable PRT protection through the following methods:

 During first sign in: During first sign in, a PRT is issued by signing
requests using the device key cryptographically generated during device
registration. On a device with a valid and functioning TPM, the device
key is secured by the TPM preventing any malicious access. A PRT isn't
issued if the corresponding device key signature can't be validated.
 During token requests and renewal: When a PRT is issued, Azure AD
also issues an encrypted session key to the device. It's encrypted with the
public transport key (tkpub) generated and sent to Azure AD as part of
device registration. This session key can only be decrypted by the private
transport key (tkpriv) secured by the TPM. The session key is the Proof-
of-Possession (POP) key for any requests sent to Azure AD. The session
key is also protected by the TPM and no other OS component can access
it. Token requests or PRT renewal requests are securely signed by this
session key through the TPM and hence, can't be tampered with. Azure
AD invalidates any requests from the device that aren't signed by the
corresponding session key.

By securing these keys with the TPM, we enhance the security for PRT from malicious
actors trying to steal the keys or replay the PRT. So, using a TPM greatly enhances
the security of Azure AD Joined, Hybrid Azure AD joined, and Azure AD registered
devices against credential theft. For performance and reliability, TPM 2.0 is the
recommended version for all Azure AD device registration scenarios on Windows 10
or newer. Starting with the Windows 10, 1903 update, Azure AD doesn't use TPM 1.2
for any of the above keys due to reliability issues.

How are app tokens and browser cookies protected?

App tokens: When an app requests token through WAM, Azure AD issues a refresh
token and an access token. However, WAM only returns the access token to the app
and secures the refresh token in its cache by encrypting it with the user’s data
protection application programming interface (DPAPI) key. WAM securely uses the
refresh token by signing requests with the session key to issue further access tokens.
The DPAPI key is secured by an Azure AD based symmetric key in Azure AD itself.
When the device needs to decrypt the user profile with the DPAPI key, Azure AD
provides the DPAPI key encrypted by the session key, which CloudAP plugin requests
TPM to decrypt. This functionality ensures consistency in securing refresh tokens and
avoids applications implementing their own protection mechanisms.

Browser cookies: In Windows 10 or newer, Azure AD supports browser SSO in

Internet Explorer and Microsoft Edge natively, in Google Chrome via the Windows 10

6
accounts extension and in Mozilla Firefox v91+ via a browser setting. The security is
built not only to protect the cookies but also the endpoints to which the cookies are
sent. Browser cookies are protected the same way a PRT is, by utilizing the session
key to sign and protect the cookies.

When a user initiates a browser interaction, the browser (or extension) invokes a
COM native client host. The native client host ensures that the page is from one of
the allowed domains. The browser could send other parameters to the native client
host, including a nonce, however the native client host guarantees validation of the
hostname. The native client host requests a PRT-cookie from CloudAP plugin, which
creates and signs it with the TPM-protected session key. As the PRT-cookie is signed
by the session key, it's difficult to tamper with. This PRT-cookie is included in the
request header for Azure AD to validate the device it's originating from. If using the
Chrome browser, only the extension explicitly defined in the native client host’s
manifest can invoke it preventing arbitrary extensions from making these requests.
Once Azure AD validates the PRT cookie, it issues a session cookie to the browser.
This session cookie also contains the same session key issued with a PRT. During
subsequent requests, the session key is validated effectively binding the cookie to
the device and preventing replays from elsewhere.

When does a PRT get an MFA claim?

A PRT can get a multifactor authentication (MFA) claim in specific scenarios. When an
MFA-based PRT is used to request tokens for applications, the MFA claim is
transferred to those app tokens. This functionality provides a seamless experience to
users by preventing MFA challenge for every app that requires it. A PRT can get an
MFA claim in the following ways:

 Sign in with Windows Hello for Business: Windows Hello for Business
replaces passwords and uses cryptographic keys to provide strong two-
factor authentication. Windows Hello for Business is specific to a user on
a device, and itself requires MFA to provision. When a user logs in with
Windows Hello for Business, the user’s PRT gets an MFA claim. This
scenario also applies to users logging in with smartcards if smartcard
authentication produces an MFA claim from ADFS.
o As Windows Hello for Business is considered multifactor
authentication, the MFA claim is updated when the PRT itself is
refreshed, so the MFA duration will continually extend when
users sign in with Windows Hello for Business.
 MFA during WAM interactive sign in: During a token request through
WAM, if a user is required to do MFA to access the app, the PRT that is
renewed during this interaction is imprinted with an MFA claim.

7
 o In this case, the MFA claim isn't updated continuously, so the
MFA duration is based on the lifetime set on the directory.
o When a previous existing PRT and RT are used for access to an
app, the PRT and RT are regarded as the first proof of
authentication. A new AT is required with a second proof and
an imprinted MFA claim. This process also issues a new PRT
and RT.

Windows 10 or newer maintain a partitioned list of PRTs for each credential. So,
there’s a PRT for each of Windows Hello for Business, password, or smartcard. This
partitioning ensures that MFA claims are isolated based on the credential used, and
not mixed up during token requests.

Note

When using password to sign into Windows 10 or newer Azure AD joined or Hybrid
Azure AD joined device, MFA during WAM interactive sign in may be required after
session key associated with PRT is rolled.

How is a PRT invalidated?

A PRT is invalidated in the following scenarios:

 Invalid user: If a user is deleted or disabled in Azure AD, their PRT is

invalidated and can't be used to obtain tokens for applications. If a
deleted or disabled user already signed in to a device before, cached
sign-in would log them in, until CloudAP is aware of their invalid state.
Once CloudAP determines that the user is invalid, it blocks subsequent
logons. An invalid user is automatically blocked from sign in to new
devices that don’t have their credentials cached.
 Invalid device: If a device is deleted or disabled in Azure AD, the PRT
obtained on that device is invalidated and can't be used to obtain tokens
for other applications. If a user is already signed in to an invalid device,
they can continue to do so. But all tokens on the device are invalidated
and the user doesn't have SSO to any resources from that device.
 Password change: If a user obtained the PRT with their password, the
PRT is invalidated by Azure AD when the user changes their password.
Password change results in the user getting a new PRT. This invalidation
can happen in two different ways:
o If user signs in to Windows with their new password, CloudAP
discards the old PRT and requests Azure AD to issue a new PRT
with their new password. If user doesn't have an internet

8
 connection, the new password can't be validated, Windows
may require the user to enter their old password.
o If a user has logged in with their old password or changed their
password after signing into Windows, the old PRT is used for
any WAM-based token requests. In this scenario, the user is
prompted to reauthenticate during the WAM token request
and a new PRT is issued.
 TPM issues: Sometimes, a device’s TPM can falter or fail, leading to
inaccessibility of keys secured by the TPM. In this case, the device is
incapable of getting a PRT or requesting tokens using an existing PRT as
it can't prove possession of the cryptographic keys. As a result, any
existing PRT is invalidated by Azure AD. When Windows 10 detects a
failure, it initiates a recovery flow to re-register the device with new
cryptographic keys. With Hybrid Azure Ad join, just like the initial
registration, the recovery happens silently without user input. For Azure
AD joined or Azure AD registered devices, the recovery needs to be
performed by a user who has administrator privileges on the device. In
this scenario, the recovery flow is initiated by a Windows prompt that
guides the user to successfully recover the device.

Detailed flows
The following diagrams illustrate the underlying details in issuing, renewing, and
using a PRT to request an access token for an application. In addition, these steps
also describe how the aforementioned security mechanisms are applied during these
interactions.

PRT issuance during first sign in

9
Note

In Azure AD joined devices, Azure AD PRT issuance (steps A-F) happens

synchronously before the user can logon to Windows. In hybrid Azure AD joined
devices, on-premises Active Directory is the primary authority. So, the user is able to
login hybrid Azure AD joined Windows after they can acquire a TGT to login, while
the PRT issuance happens asynchronously. This scenario does not apply to Azure AD
registered devices as logon does not use Azure AD credentials.

Step Description
A User enters their password in the sign in UI. LogonUI passes the credentials in an auth buffer
to LSA, which in turns passes it internally to CloudAP. CloudAP forwards this request to the
CloudAP plugin.
B CloudAP plugin initiates a realm discovery request to identify the identity provider for the
user. If user’s tenant has a federation provider setup, Azure AD returns the federation
provider’s Metadata Exchange endpoint (MEX) endpoint. If not, Azure AD returns that the
user is managed indicating that user can authenticate with Azure AD.

10
Step Description
C If the user is managed, CloudAP gets the nonce from Azure AD. If the user is federated,
CloudAP plugin requests a SAML token from the federation provider with the user’s
credentials. Nonce is requested before the SAML token is sent to Azure AD.
D CloudAP plugin constructs the authentication request with the user’s credentials, nonce, and
a broker scope, signs the request with the Device key (dkpriv) and sends it to Azure AD. In a
federated environment, CloudAP plugin uses the SAML token returned by the federation
provider instead of the user’ credentials.
E Azure AD validates the user credentials, the nonce, and device signature, verifies that the
device is valid in the tenant and issues the encrypted PRT. Along with the PRT, Azure AD
also issues a symmetric key, called the Session key encrypted by Azure AD using the
Transport key (tkpub). In addition, the Session key is also embedded in the PRT. This
Session key acts as the Proof-of-possession (PoP) key for subsequent requests with the PRT.
F CloudAP plugin passes the encrypted PRT and Session key to CloudAP. CloudAP request
the TPM to decrypt the Session key using the Transport key (tkpriv) and re-encrypt it using
the TPM’s own key. CloudAP stores the encrypted Session key in its cache along with the
PRT.

PRT renewal in subsequent logons

11
Ste Description
p
A User enters their password in the sign in UI. LogonUI passes the credentials in an auth buffer
to LSA, which in turns passes it internally to CloudAP. CloudAP forwards this request to the
CloudAP plugin.
B If the user has previously logged on to the user, Windows initiates cached sign in and
validates credentials to log the user in. Every 4 hours, the CloudAP plugin initiates PRT
renewal asynchronously.
C CloudAP plugin initiates a realm discovery request to identify the identity provider for the
user. If user’s tenant has a federation provider setup, Azure AD returns the federation
provider’s Metadata Exchange endpoint (MEX) endpoint. If not, Azure AD returns that the
user is managed indicating that user can authenticate with Azure AD.
D If the user is federated, CloudAP plugin requests a SAML token from the federation provider
with the user’s credentials. Nonce is requested before the SAML token is sent to Azure AD. If
the user is managed, CloudAP will directly get the nonce from Azure AD.
E CloudAP plugin constructs the authentication request with the user’s credentials, nonce, and
the existing PRT, signs the request with the Session key and sends it to Azure AD. In a

12
Ste Description
p
federated environment, CloudAP plugin uses the SAML token returned by the federation
provider instead of the user’ credentials.
F Azure AD validates the Session key signature by comparing it against the Session key
embedded in the PRT, validates the nonce and verifies that the device is valid in the tenant
and issues a new PRT. As seen before, the PRT is again accompanied with the Session key
encrypted by Transport key (tkpub).
G CloudAP plugin passes the encrypted PRT and Session key to CloudAP. CloudAP requests
the TPM to decrypt the Session key using the Transport key (tkpriv) and re-encrypt it using
the TPM’s own key. CloudAP stores the encrypted Session key in its cache along with the
PRT.
Note

A PRT can be renewed externally without the need of a VPN connection when
usernamemixed endpoints are enabled externally.

PRT usage during app token requests

13
Ste Description
p
A An application (for example, Outlook, OneNote etc.) initiates a token request to WAM. WAM,
in turn, asks the Azure AD WAM plugin to service the token request.
B If a Refresh token for the application is already available, Azure AD WAM plugin uses it to
request an access token. To provide proof of device binding, WAM plugin signs the request
with the Session key. Azure AD validates the Session key and issues an access token and a
new refresh token for the app, encrypted by the Session key. WAM plugin requests CloudAP
plugin to decrypt the tokens, which, in turn, requests the TPM to decrypt using the Session
key, resulting in WAM plugin getting both the tokens. Next, WAM plugin provides only the
access token to the application, while it re-encrypts the refresh token with DPAPI and stores it
in its own cache
C If a Refresh token for the application isn't available, Azure AD WAM plugin uses the PRT to
request an access token. To provide proof of possession, WAM plugin signs the request
containing the PRT with the Session key. Azure AD validates the Session key signature by
comparing it against the Session key embedded in the PRT, verifies that the device is valid and
issues an access token and a refresh token for the application. in addition, Azure AD can issue

14
Ste Description
p
a new PRT (based on refresh cycle), all of them encrypted by the Session key.
D WAM plugin requests CloudAP plugin to decrypt the tokens, which, in turn, requests the TPM
to decrypt using the Session key, resulting in WAM plugin getting both the tokens. Next,
WAM plugin provides only the access token to the application, while it re-encrypts the refresh
token with DPAPI and stores it in its own cache. WAM plugin uses the refresh token going
forward for this application. WAM plugin also gives back the new PRT to CloudAP plugin,
which validates the PRT with Azure AD before updating it in its own cache. CloudAP plugin
uses the new PRT going forward.
E WAM provides the newly issued access token to WAM, which in turn, provides it back to the
calling application

Browser SSO using PRT

Step Description
A User logs in to Windows with their credentials to get a PRT. Once user opens the browser,
browser (or extension) loads the URLs from the registry.
B When a user opens an Azure AD login URL, the browser or extension validates the URL with
the ones obtained from the registry. If they match, the browser invokes the native client host
for getting a token.
C The native client host validates that the URLs belong to the Microsoft identity providers
(Microsoft account or Azure AD), extracts a nonce sent from the URL and makes a call to
CloudAP plugin to get a PRT cookie.

15
Step Description
D The CloudAP plugin creates the PRT cookie, sign in with the TPM-bound session key and
send it back to the native client host.
E The native client host returns this PRT cookie to the browser, which includes it as part of the
request header called x-ms-RefreshTokenCredential and request tokens from Azure AD.
F Azure AD validates the Session key signature on the PRT cookie, validates the nonce,
verifies that the device is valid in the tenant, and issues an ID token for the web page and an
encrypted session cookie for the browser.
Note

The Browser SSO flow described in the previous steps doesn't apply for sessions in
private modes such as InPrivate in Microsoft Edge, Incognito in Google Chrome
(when using the Microsoft Accounts or Office Online extensions) or in private mode
in Mozilla Firefox v91+

16