Skip to content

Latest commit

 

History

History
56 lines (38 loc) · 3.25 KB

device-bound-tokens.md

File metadata and controls

56 lines (38 loc) · 3.25 KB

Acquiring Device Bound Tokens using Web Account Manager (WAM) on Windows

MSAL.js supports acquiring tokens from the Web Account Manager (WAM) on Windows. These tokens are bound to the device they were acquired on and are not cached in the browser's localStorage or sessionStorage.

Supported Environment

This feature is currently only supported in the following environment:

  • A machine running a Windows build that supports the feature (more to come on this)
  • Chrome and Edge browsers or Teams
  • Windows Accounts extension (version 1.0.5 or higher) is installed if using Chrome or Edge
  • App must be hosted on https

Additionally, this feature is currently only supported for Work and School Accounts

Enable the feature in MSAL.js

In order to enable this feature in MSAL.js set the allowPlatformBroker flag to true in your configuration object like so:

const msalConfig = {
    auth: {
        clientId: "insert-clientId",
    },
    system: {
        allowPlatformBroker: true,
    },
};

Additionally, you will need to call and await the new initialize API before invoking any other MSAL.js API.

const pca = new PublicClientApplication(msalConfig);

// Initialize will establish a connection with the browser extension, if present
await pca.initialize();

// Call handleRedirectPromise, after initialization is complete
await pca.handleRedirectPromise();

// After initialize and handleRedirectPromise have completed, you may call any of the other APIs as you would without this feature
pca.acquireTokenSilent();

No other changes are needed to support this new feature. Any user accessing your app from a supported environment will now be able to acquire device bound tokens. Users in non-supported environments will continue to acquire tokens through the traditional web-based flows.

A working sample can be found here

Differences when using WAM to acquire tokens

There are a few things that may behave a little differently when acquiring tokens through WAM.

  • All cache related configuration applies only to MSAL's local cache. The native broker controls its own, more secure, cache which is used instead of browser storage and it does not support configuration of its cache behavior. This means you may receive a cached token regardless of the value of request parameters such as: forceRefresh, cacheLookupPolicy or storeInCache. In addition, tokens received from the native broker are not stored in local or session storage regardless of what you have configured on PublicClientApplication.
  • If WAM needs to prompt the user for interaction a system prompt will be opened. This prompt looks a bit different from the browser popup windows you may be used to.
  • Switching your account in the WAM prompt is not supported and MSAL.js will throw an error (Error Code: user_switch) if this happens. It is your app's responsibility to catch this error and handle it in a way that makes sense for your scenarios (e.g. Show an error page, retry with the new account, retry with the original account, etc.)