Get a new access token after it expires (consumer apps) You can request a new access token by using the refresh token or by repeating the auth process from the beginning. When an access token expires, requests to the API return a 401 Unauthorized response. Your app should handle this response and check the token expiration before sending requests. Disable the Allow connections only from computers running Remote Desktop with Network Level Authentication option on the RD Session Host server. Change the password of the user account by using a different method. Microsoft has confirmed that this is a problem in the Microsoft products that are listed in the 'Applies to' section.

1. Office For Mac Repeatedly Requesting ... - Support.microsoft.com
2. Microsoft Onenote Authentication Session Has Expired

This article provides some guidance about how to troubleshoot problems with single sign-on (SSO) in Office Add-ins, and how to make your SSO-enabled add-in robustly handle special conditions or errors.

Note

The Single Sign-on API is currently supported for Word, Excel, Outlook, and PowerPoint. For more information about where the Single Sign-on API is currently supported, see IdentityAPI requirement sets.If you are working with an Outlook add-in, be sure to enable Modern Authentication for the Microsoft 365 tenancy. For information about how to do this, see Exchange Online: How to enable your tenant for modern authentication.

Nov 26, 2019 OneNote not guarantee that content will not be lost; Mac OneNote: Authentication Session has Expired; Please Sign-in Again; What is the Sync Keyboard Shortcut for Mac OneNote? MAC: How to Open and Edit Attachments in OneNote? Paid Feature List of OneNote for Mac.

Debugging tools

We strongly recommend that you use a tool that can intercept and display the HTTP Requests from, and Responses to, your add-in's web service when you are developing. Two of the most popular are:

• Fiddler: Free (Documentation)
• Charles: Free for 30 days. (Documentation)

Causes and handling of errors from getAccessToken

For examples of the error handling described in this section, see:

13000

The getAccessToken API is not supported by the add-in or the Office version.

• The version of Office does not support SSO. The required version is Microsoft 365 subscription, in any monthly channel.
• The add-in manifest is missing the proper WebApplicationInfo section.

Your add-in should respond to this error by falling back to an alternate system of user authentication. For more information, see Requirements and Best Practices.

13001

The user is not signed into Office. In most scenarios, you should prevent this error from ever being seen by passing the option allowSignInPrompt: true in the AuthOptions parameter.

But there may be exceptions. For example, you want the add-in to open with features that require a logged in user; but only if the user is already logged into Office. If the user is not, you want the add-in to open with an alternate set of features that do not require that the user is signed in. In this case, logic which runs when the add-in launches calls getAccessToken without allowSignInPrompt: true. Use the 13001 error as the flag to tell the add-in to present the alternate set of features.

Another option is to respond to 13001 by falling back to an alternate system of user authentication. This will sign the user into AAD, but not sign the user into Office.

This error is never seen in Office on the web. If the user's cookie expires, Office on the web returns error 13006.

13002

The user aborted sign in or consent; for example, by choosing Cancel on the consent dialog.

• If your add-in provides functions that don't require the user to be signed in (or to have granted consent), then your code should catch this error and allow the add-in to stay running.
• If the add-in requires a signed-in user who has granted consent, your code should have a sign-in button appear.

13003

User Type not supported. The user isn't signed into Office with a valid Microsoft account or Microsoft 365 Education or work account. This may happen if Office runs with an on-premises domain account, for example. Your code should fall back to an alternate system of user authentication. In Outlook, this error may also occur if modern authentication is disabled for the user's tenant in Exchange Online. For more information, see Requirements and Best Practices.

13004

Invalid Resource. (This error should only be seen in development.) The add-in manifest hasn't been configured correctly. Update the manifest. For more information, see Validate an Office Add-in's manifest. The most common problem is that the Resource element (in the WebApplicationInfo element) has a domain that does not match the domain of the add-in. Although the protocol part of the Resource value should be 'api' not 'https'; all other parts of the domain name (including port, if any) should be the same as for the add-in.

13005

Invalid Grant. This usually means that Office has not been pre-authorized to the add-in's web service. For more information, see Create the service application and Register the add-in with Azure AD v2.0 endpoint. This also may happen if the user has not granted your service application permissions to their profile, or has revoked consent. Your code should fall back to an alternate system of user authentication.

Another possible cause, during development, is that your add-in using Internet Explorer, and you are using a self-signed certificate. (To determine which browser is being used by the add-in, see Browsers used by Office Add-ins.)

13006

Client Error. This error is only seen in Office on the web. Your code should suggest that the user sign out and then restart the Office browser session.

13007

The Office application was unable to get an access token to the add-in's web service.

• If this error occurs during development, be sure that your add-in registration and add-in manifest specify the profile permission (and the openid permission, if you are using MSAL.NET). For more information, see Register the add-in with Azure AD v2.0 endpoint.

• In production, there are several things that can cause this error. Some of them are:

  • The user has a Microsoft account identity.
  • Some situations that would cause one of the other 13xxx errors with a Microsoft 365 Education or work account will cause a 13007 when a MSA is used.

  For all of these cases, your code should fall back to an alternate system of user authentication.

13008

The user triggered an operation that calls getAccessToken before a previous call of getAccessToken completed. This error is only seen on Office on the web. Your code should ask the user to repeat the operation after the previous operation has completed.

13010

The user is running the add-in in Office on Microsoft Edge or Internet Explorer. The user's Microsoft 365 domain, and the login.microsoftonline.com domain, are in a different security zones in the browser settings. This error is only seen on Office on the web. If this error is returned, the user will have already seen an error explaining this and linking to a page about how to change the zone configuration. If your add-in provides functions that don't require the user to be signed in, then your code should catch this error and allow the add-in to stay running.

13012

There are several possible causes.

• The add-in is running on a platform that does not support the getAccessToken API. For example, it is not supported on iPad. See also Identity API requirement sets.
• The forMSGraphAccess option was passed in the call to getAccessToken and the user obtained the add-in from AppSource. In this scenario, the tenant admin has not granted consent to the add-in for the Microsoft Graph scopes (permissions) that it needs. Recalling getAccessToken with the allowConsentPrompt will not solve the problem because Office is allowed to prompt the user for consent to only the AAD profile scope.

Your code should fall back to an alternate system of user authentication.

In development, the add-in is sideloaded in Outlook and the forMSGraphAccess option was passed in the call to getAccessToken.

13013

The getAccessToken was called too many times in a short amount of time, so Office throttled the most recent call. This is usually caused by an infinite loop of calls to the method. There are scenarios when recalling the method is advisable. However, your code should use a counter or flag variable to ensure that the method is not recalled repeatedly. If the same 'retry' code path is running again, the code should fall back to an alternate system of user authentication. For a code example, see how the retryGetAccessToken variable is used in HomeES6.js or ssoAuthES6.js.

50001

This error (which is not specific to getAccessToken) may indicate that the browser has cached an old copy of the office.js files. When you are developing, clear the browser's cache. Another possibility is that the version of Office is not recent enough to support SSO. On Windows, the minimum version is 16.0.12215.20006. On Mac, it is 16.32.19102902.

In a production add-in, the add-in should respond to this error by falling back to an alternate system of user authentication. For more information, see Requirements and Best Practices.

Errors on the server-side from Azure Active Directory

For samples of the error-handling described in this section, see:

Conditional access / Multifactor authentication errors

In certain configurations of identity in AAD and Microsoft 365, it is possible for some resources that are accessible with Microsoft Graph to require multifactor authentication (MFA), even when the user's Microsoft 365 tenancy does not. When AAD receives a request for a token to the MFA-protected resource, via the on-behalf-of flow, it returns to your add-in's web service a JSON message that contains a claims property. The claims property has information about what further authentication factors are needed.

Your code should test for this claims property. Depending on your add-in's architecture, you may test for it on the client-side, or you may test for it on the server-side and relay it to the client. You need this information in the client because Office handles authentication for SSO add-ins. If you relay it from the server-side, the message to the client can be either an error (such as 500 Server Error or 401 Unauthorized) or in the body of a success response (such as 200 OK). In either case, the (failure or success) callback of your code's client-side AJAX call to your add-in's web API should test for this response.

Regardless of your architecture, if the claims value has been sent from AAD, your code should recall getAccessToken and pass the option authChallenge: CLAIMS-STRING-HERE in the options parameter. When AAD sees this string, it prompts the user for the additional factor(s) and then returns a new access token which will be accepted in the on-behalf-of flow.

Consent missing errors

If AAD has no record that consent (to the Microsoft Graph resource) was granted to the add-in by the user (or tenant administrator), AAD will send an error message to your web service. Your code must tell the client (in the body of a 403 Forbidden response, for example).

If the add-in needs Microsoft Graph scopes that can only be consented to by an admin, your code should throw an error. If the only scopes that are needed can be consented to by the user, then your code should fall back to an alternate system of user authentication.

Invalid or missing scope (permission) errors

This kind of error should only be seen in development.

• Your server-side code should send a 403 Forbidden response to the client which should log the error to the console or record it in a log.
• Be sure your add-in manifest Scopes section specifies all needed permissions. And be sure your registration of the add-in's web service specifies the same permissions. Check for spelling mistakes too. For more information, see Register the add-in with Azure AD v2.0 endpoint.

Invalid audience error in the access token (not the bootstrap token)

Your server-side code should send a 403 Forbidden response to the client which should present a friendly message to the user and possibly also log the error to the console or record it in a log.

A Primary Refresh Token (PRT) is a key artifact of Azure AD authentication on Windows 10, Windows Server 2016 and later versions, iOS, and Android devices. It is 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, we will provide details on how a PRT is issued, used, and protected on Windows 10 devices.

This article assumes that you already understand the different device states available in Azure AD and how single sign-on works in Windows 10. 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 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 devices. WAM also provides a plugin framework that identity providers can build on and enable SSO to their applications relying on that identity provider. (Not included in Windows Server 2016 LTSC builds)
• 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, 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 generally contained in any Azure AD refresh token. 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.

Can I see what’s in a PRT?

A PRT is an opaque blob sent from Azure AD whose contents are not known to any client components. You cannot 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. 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 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 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 device. Users can add an account to Windows 10 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 Azure AD registered device scenarios, the Azure AD WAM plugin is the primary authority for the PRT since Windows logon is not 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 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

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 does not 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. 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 is supported on Microsoft Edge (natively) and Chrome (via the Windows 10 Accounts or Office Online extensions).

How is a PRT renewed?

A PRT is renewed in two different methods:

• Azure AD CloudAP plugin every 4 hours: The CloudAP plugin renews the PRT every 4 hours during Windows sign in. If the user does not 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 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 Azure AD requires additional authorization (for example, Azure AD Multi-Factor Authentication). In this scenario, WAM initiates an interactive logon requiring the user to reauthenticate or provide additional 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

• A PRT is only issued and renewed during native app authentication. A PRT is not 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?

A PRT is protected by binding it to the device the user has signed in to. Azure AD and Windows 10 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 is not issued if the corresponding device key signature cannot be validated.
• During token requests and renewal: When a PRT is issued, Azure AD also issues an encrypted session key to the device. It is 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, cannot be tampered with. Azure AD will invalidate any requests from the device that are not 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. Starting Windows 10, 1903 update, Azure AD does not 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, Azure AD supports browser SSO in Internet Explorer and Microsoft Edge natively or in Google Chrome via the Windows 10 accounts extension. 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 is very difficult to tamper with. This PRT-cookie is included in the request header for Azure AD to validate the device it is 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 multi-factor 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.
  • As Windows Hello for Business is considered multi-factor 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 is not 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 will be regarded as the first proof of authentication. A new AT will be required with a second proof and an imprinted MFA claim. This will also issue a new PRT and RT.
• MFA during device registration: If an admin has configured their device settings in Azure AD to require MFA to register devices, the user needs to do MFA to complete the registration. During this process, the PRT that is issued to the user has the MFA claim obtained during the registration. This capability only applies to the registered owner of the device, not to other users who sign in to that device.
  • Similar to the WAM interactive sign in, the MFA claim is not updated continuously, so the MFA duration is based on the lifetime set on the directory.

Windows 10 maintains 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.

Office For Mac Repeatedly Requesting ... - Support.microsoft.com

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 cannot 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 cannot 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 does not have SSO to any resources from that device.
• Password change: After a user changes their password, the PRT obtained with the previous password is invalidated by Azure AD. Password change results in the user getting a new PRT. This invalidation can happen in two different ways:
  • 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 does not have an internet connection, the new password cannot be validated, Windows may require the user to enter their old password.
  • 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 cannot 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

Note

In Azure AD joined devices, this exchange happens synchronously to issue a PRT 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 only waiting until 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.

PRT renewal in subsequent logons

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

Microsoft Onenote Authentication Session Has Expired

Browser SSO using PRT

Note

The Browser SSO flow described in the steps above does not apply for sessions in private modes such as InPrivate in Microsoft Edge, or Incognito in Google Chrome (when using the Microsoft Accounts extension).

Next steps

For more information on troubleshooting PRT-related issues, see the article Troubleshooting hybrid Azure Active Directory joined Windows 10 and Windows Server 2016 devices.