|
| 1 | +--- |
| 2 | +title: Working with the AADTokenProvider |
| 3 | +description: Learn how to work with, and configure, the AADTokenProvider API for certain scenarios. |
| 4 | +ms.date: 04/13/2023 |
| 5 | +ms.localizationpriority: high |
| 6 | +--- |
| 7 | +# Working with the AADTokenProvider |
| 8 | + |
| 9 | +The [AADTokenProvider](/javascript/api/sp-http-base/aadtokenprovider) API in the SharePoint Framework (SPFx) allows developers to obtain OAuth tokens from Azure AD. These tokens are used to authenticate the user from the SharePoint page to other services, such as Power BI, Sway, Exchange, Yammer, etc. |
| 10 | + |
| 11 | +## Handling the popupEvent |
| 12 | + |
| 13 | +A SPFx component requests an access token from Azure AD to connect to a secured service, such as Microsoft Graph, uses the **AADTokenProvider** to perform this task. |
| 14 | + |
| 15 | +When the component requests an access token from a browser SPFx first attempts to use a hidden `<iframe>` to obtain the token. This technique is referred to as *silent SSO* |
| 16 | + |
| 17 | +However in the case where a browser blocks third-party cookies, such as Safari when its Intelligent Tracking Protection (ITP) feature is enabled, SPFx will force a full page redirect to prompt the user to sign in to Azure AD and then obtain the access token. |
| 18 | + |
| 19 | +The [SPFx v1.17 release](release-1.17.md) introduced a capability that enables tenant administrators to change this behavior and, instead, allow users to sign in via a popup window experience instead of the full page redirect. |
| 20 | + |
| 21 | +To support this scenario, a new event was added to the **AADTokenProvider** so developers can intercept the popup request and add their own business logic to handle the popup flow. |
| 22 | + |
| 23 | +### Enabling the popup flow experience |
| 24 | + |
| 25 | +To enable the popup experience, a tenant administrator must first enable the feature on the tenant. This is done using the [Set-SPOTenant](/powershell/module/sharepoint-online/set-spotenant) to set the `[-IsEnableAppAuthPopupEnabled](/powershell/module/sharepoint-online/set-spotenant?view=sharepoint-ps#-isenableappauthpopupenabled)` argument on the tenant. |
| 26 | + |
| 27 | +> [!IMPORTANT] |
| 28 | +> The SPFx will always first attempt to obtain an access token using the *silent SSO* first with the hidden `<iframe>`. |
| 29 | +> |
| 30 | +> If the SPFx fails to obtain an access token using the silent SSO approach, it will then fall back to the full page redirect or the popup flow experience. |
| 31 | +
|
| 32 | +### Handling the popupEvent |
| 33 | + |
| 34 | +SPFx components that wish to use the **AADTokenProvider** and want to implement the popup flow can do so by handling the [AADTokenProvider.popupEvent](/javascript/api/sp-http-base/aadtokenprovider#@microsoft-sp-http-base-aadtokenprovider-popupevent-member). |
| 35 | + |
| 36 | +> [!TIP] |
| 37 | +> Popups are commonly blocked by browsers unless they are initiated by a user action or gesture. |
| 38 | +
|
| 39 | +Prior to requesting an access token, your component should implement a handler for the `popupEvent`. For example, this could be done in the `onInit()` method of a web part. |
| 40 | + |
| 41 | +```typescript |
| 42 | +const configurableTokenProvider: AadTokenProvider = _AadTokenProviders.configurable as AadTokenProvider; |
| 43 | + |
| 44 | +configurableTokenProvider.popupEvent.add(this, (args: IPopupEventArgs) => { |
| 45 | + args.cancel(); // REQUIRED: to cancel the default popup that is called to open |
| 46 | + args.showPopup(); // initiate the popup flow |
| 47 | +}); |
| 48 | +``` |
| 49 | + |
| 50 | +This event will be called by SPFx when the silent SSO process fails and if the tenant has been configured to enable the popup flow for access token acquisition. |
0 commit comments