Understanding Primary Refresh Token (PRT)

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

• Microsoft Entra joined or Microsoft Entra hybrid joined: A PRT is issued during Windows sign-in 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, Microsoft Entra CloudAP plugin is the primary authority for the PRT
• Microsoft Entra 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:
  • Adding an account via the Allow my organization to manage my device prompt after signing in to an app (for example, Outlook)
  • Adding an account from Settings > Accounts > Access Work or School > Connect

In Microsoft Entra registered device scenarios, the Microsoft Entra WAM plugin is the primary authority for the PRT since Windows sign in isn't happening with this Microsoft Entra account.

macOS Platform Single Sign-on (PSSO) is a new feature powered by Microsoft’s Enterprise SSO plug-in, Platform Credentials for macOS that enables users to sign in to Mac devices using their Microsoft Entra ID credentials.

The PSSO Primary Refresh Token (PRT) is issued exclusively to Entra-joined macOS devices that successfully completed Platform SSO registration. During this registration process, macOS generates secure enclave–backed cryptographic key pairs: one for device signing and another for device encryption. The public key references are shared with the SSO extension.

The SSO extension uses these keys to complete device registration with the Microsoft Entra ID Device Registration Service. It then configures Apple’s loginConfiguration API with the necessary parameters for PRT acquisition.

Once registration is successfully completed, macOS initiates a sign in request signed with the Device Signing key. Microsoft Entra ID validates the request, device signing key and associated parameters, and issues PRT response. macOS decrypts this response using Device Encryption key, stores the PRT and makes it available to the SSO extension. The sign in request is sent during user authentication on PSSO registered macOS.

iOS, macOS, and Android supports both Unregistered PRTs for Microsoft Edge and Registered PRTs when broker is present.

Linux supports both Unregistered PRTs for Microsoft Edge and Registered PRTs when broker is present.

A PRT is used by two key components in Windows:

• Microsoft Entra CloudAP plugin: During Windows sign in, the Microsoft Entra CloudAP plugin requests a PRT from Microsoft Entra ID 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.
• Microsoft Entra WAM plugin: When users try to access applications, the Microsoft Entra WAM plugin uses the PRT to enable SSO on Windows 10 or newer. Microsoft Entra 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 extension) and Mozilla Firefox v91+ (Firefox Windows SSO setting).

  Note

  In instances where a user has two accounts from the same Microsoft Entra 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.

A PSSO PRT is used by the SSO extension to provide SSO to apps and websites. A PRT is used to request refresh and access tokens for applications that rely on the SSO extension for token requests. It also enables SSO on browsers by injecting the PRT into browser requests.

PRT is used in a similar manner to the description of the "Microsoft Entra WAM plugin" for native apps. The browsers that support Browser SSO are Safari, Firefox, Chrome, and Microsoft Edge.

The only native apps integrated today are Intune and Microsoft Edge Browser. For browser support, only Microsoft Edge Browser is protected for device-bound tokens and Conditional Access enforcement.

Windows Platform

A PRT is renewed in two different ways:

• Microsoft Entra 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 and a new Windows sign in is done.
• Microsoft Entra 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:
  • 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.
  • An app requests WAM for an access token but the PRT is invalid or Microsoft Entra ID requires extra authorization (for example, Microsoft Entra multifactor authentication). In this scenario, WAM initiates an interactive sign-in 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.

Key considerations

• In Microsoft Entra joined and Microsoft Entra hybrid 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 Microsoft Entra ID before accepting it.

macOS renews the PSSO Primary Refresh Token (PRT) every 4 hours, or sooner if the SSO tokens are missing or have expired.

On iOS, there’s also an opportunistic update when device is charging, happening not more often than once every two days, subject to resources allocation by the iOS operating system. Similarly to other platforms, a PRT is valid for 90 days if in use.

A PRT is valid for 90 days and is renewed every 4 hours if the user actively uses the device.

• A PRT is valid for 90 days and is continuously renewed as long as the user actively uses the device.
• A PRT is only issued and renewed during native app authentication. A PRT isn't renewed or issued during a browser session.
• It's possible to obtain a PRT without the need for device registration (Workplace Join) and enable SSO.
• PRTs obtained without device registration can't satisfy the authorization criteria for Conditional Access that relies on the device's status or compliance.

Microsoft Entra ID 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, Microsoft Entra ID also issues an encrypted session key to the device. It's encrypted with the public transport key (tkpub) generated and sent to Microsoft Entra ID 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 Microsoft Entra ID. 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. Microsoft Entra 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 Microsoft Entra joined, Microsoft Entra hybrid joined, and Microsoft Entra registered devices against credential theft. For performance and reliability, TPM 2.0 is the recommended version for all Microsoft Entra device registration scenarios on Windows 10 or newer. After the Windows 10, 1903 update, Microsoft Entra ID doesn't use TPM 1.2 for any of the above keys due to reliability issues.

A Primary Refresh Token (PRT) is securely bound to the device on which the user signs in. Microsoft Entra ID and macOS enforce this protection through several mechanisms:

The PRT is issued only after a request is signed using a secure enclave–backed Device Signing Key, which is cryptographically generated during device registration. If the signature from this key can't be validated, the PRT won't be issued.

• When an app requests token through WAM, Microsoft Entra ID issues an access token and, in some types of the requests, a refresh token. However, WAM only returns the access token to the app and secures the refresh token:
  • If it is a refresh token for an SSO user, then this refresh token is bound to the device, with a session key (the same as PRT) or the device key.
  • If it is a refresh token for a non-SSO user, then this refresh token is not bound to the device.
• All refresh tokens are encrypted by the DPAPI.

• iOS unmanaged: On devices without MDM SSO extension profile, broker returns both the access token and the refresh token to the calling app. The calling app uses the refresh token for subsequent refreshes and that refresh token won’t be protected.
• macOS/iOS managed: On devices with MDM SSO extension profile, broker returns only the access token to the calling app. Broker uses PRT for any subsequent token refresh and doesn't use unprotected refresh token. We recommend customers to use this configuration over the unmanaged one due to the extra protection it provides.

• Broker only returns the access token to the calling app and stores the app refresh token locally for both managed and unmanaged devices.

• On Linux, the broker only returns the access token to the calling app and stores refresh tokens locally for both managed and unmanaged devices.
• The locally stored refresh tokens are encrypted with an encryption key stored in UNIX User’s sign in keyring.

• In Windows 10 or newer, Microsoft Entra ID supports browser SSO in Microsoft Edge natively, in Google Chrome via native support or 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.
• When a user initiates a browser interaction, the browser (or the extension) invokes a platform API. The extension calls this API via a native messaging host. The API ensures that the page is from one of the allowed domains. The browser sends full query string, which includes a nonce. The platform API creates a PRT and device header, which are signed with the TPM-protected keys. The PRT-header is signed by the session key, the device header by device key, thus it's difficult to tamper with. These headers are included in all requests for Microsoft Entra ID to validate the device it's originating from and the user. Once Microsoft Entra ID validates those headers, it issues a session cookie to the browser. This session cookie also contains the same session or device key used to sign the request. During subsequent requests, the session key is validated effectively binding the cookie to the device and preventing replays from elsewhere.

Safari and Microsoft Edge with the SSO extension profile will have cookies protected by the PRT session key. Microsoft Edge requires user to be logged into the Microsoft Edge profile. Cookies aren't protected without the SSO extension profile.

During interactive sign-ins, browser SSO cookie is generated (using the PRT and session key that is in Android account managed storage). Only applicable to Microsoft Edge browser and user must be signed in.

Microsoft Edge on Linux can request the broker for a browser SSO cookie to enable SSO in Microsoft Edge. The broker generates the SSO cookie using PRT and Session Key that is stored in the user and device broker context respectively to return the generated cookie to Microsoft Edge. Microsoft Edge requires user to be logged in to the profile. Theoretically, apps other than Microsoft Edge can also request this cookie from Broker since there's no app identity on the Linux platform. The OS security boundary is around the UNIX user and only apps in the same user context are able acquire SSO cookie for a user in that context.

• 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 smart cards if Smartcard authentication produces an MFA claim from ADFS.
  • 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.
  • In this case, the MFA claim isn't updated continuously, so the MFA duration is based on the lifetime set on the directory.
  • 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 RT 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 smart card. This partitioning ensures that MFA claims are isolated based on the credential used, and not mixed up during token requests.

If the CA policies have been set by the admin, user is required to do MFA. In those cases, the PRT would be upgraded and will get an MFA claim. The claim duration is based on the lifetime set on the directory.