Office.Auth interface
The Office Auth namespace, Office.auth, provides a method that allows the Office client application to obtain an access token to the add-in's web application. Indirectly, this also enables the add-in to access the signed-in user's Microsoft Graph data without requiring the user to sign in a second time.
Methods
| get |
Calls the Azure Active Directory V 2.0 endpoint to get an access token to your add-in's web application. Enables add-ins to identify users. Server-side code can use this token to access Microsoft Graph for the add-in's web application by using the "on behalf of" OAuth flow. This API requires a single sign-on configuration that bridges the add-in to an Azure application. Office users sign in with Organizational Accounts and Microsoft Accounts. Microsoft Azure returns tokens intended for both user account types to access resources in the Microsoft Graph. |
| get |
Calls the Azure Active Directory V 2.0 endpoint to get an access token to your add-in's web application. Enables add-ins to identify users. Server-side code can use this token to access Microsoft Graph for the add-in's web application by using the "on behalf of" OAuth flow. Important: In Outlook, this API isn't supported if the add-in is loaded in an Outlook.com or Gmail mailbox. Warning: |
| get |
Calls the Azure Active Directory V 2.0 endpoint to get an access token to your add-in's web application. Enables add-ins to identify users. Server-side code can use this token to access Microsoft Graph for the add-in's web application by using the "on behalf of" OAuth flow. Important: In Outlook, this API isn't supported if the add-in is loaded in an Outlook.com or Gmail mailbox. Warning: |
Method Details
getAccessToken(options)
Calls the Azure Active Directory V 2.0 endpoint to get an access token to your add-in's web application. Enables add-ins to identify users. Server-side code can use this token to access Microsoft Graph for the add-in's web application by using the "on behalf of" OAuth flow. This API requires a single sign-on configuration that bridges the add-in to an Azure application. Office users sign in with Organizational Accounts and Microsoft Accounts. Microsoft Azure returns tokens intended for both user account types to access resources in the Microsoft Graph.
getAccessToken(options?: AuthOptions): Promise<string>;Parameters
- options
- Office.AuthOptions
Optional. Accepts an AuthOptions object to define sign-on behaviors.
Returns
Promise<string>
Promise to the access token.
Remarks
Applications: Excel, OneNote, Outlook, PowerPoint, Word
Requirement set: IdentityAPI 1.3
Important:
In Outlook, this API isn't supported if you load an add-in in an Outlook.com or Gmail mailbox.
In Outlook on the web, this API isn't supported if you use the Safari browser. This results in error 13001 ("The user is not signed into Office").
In Outlook on the web, if you use the displayDialogAsync method to open a dialog, you must close the dialog before you can call
getAccessToken.In an Outlook event-based activation add-in, this API is supported in Outlook on Windows starting from Version 2111 (Build 14701.20000). To retrieve an access token in older builds, use OfficeRuntime.auth.getAccessToken instead. For more information, see Enable single sign-on (SSO) in Outlook add-ins that use event-based activation.
Examples
try{
const accessToken = await Office.auth.getAccessToken({
allowSignInPrompt: true,
allowConsentPrompt: true,
forMSGraphAccess: true,
});
} catch (error) {
console.log("Error obtaining token", error);
}
getAccessTokenAsync(options, callback)
Warning
This API is now deprecated.
Use Office.auth.getAccessToken instead.
Calls the Azure Active Directory V 2.0 endpoint to get an access token to your add-in's web application. Enables add-ins to identify users. Server-side code can use this token to access Microsoft Graph for the add-in's web application by using the "on behalf of" OAuth flow.
Important: In Outlook, this API isn't supported if the add-in is loaded in an Outlook.com or Gmail mailbox.
Warning: getAccessTokenAsync has been deprecated. Use Office.auth.getAccessToken instead.
getAccessTokenAsync(options?: AuthOptions, callback?: (result: AsyncResult<string>) => void): void;Parameters
- options
- Office.AuthOptions
Optional. Accepts an AuthOptions object to define sign-on behaviors.
- callback
-
(result: Office.AsyncResult<string>) => void
Optional. Accepts a callback function that can parse the token for the user's ID or use the token in the "on behalf of" flow to get access to Microsoft Graph. If AsyncResult.status is "succeeded", then AsyncResult.value is the raw AAD v. 2.0-formatted access token.
Returns
void
Remarks
Applications: Excel, OneNote, Outlook, PowerPoint, Word
Requirement set: IdentityAPI 1.3
This API requires a single sign-on configuration that bridges the add-in to an Azure application. Office users sign in with Organizational Accounts and Microsoft Accounts. Microsoft Azure returns tokens intended for both user account types to access resources in the Microsoft Graph.
Examples
Office.context.auth.getAccessTokenAsync(function(result) {
if (result.status === Office.AsyncResultStatus.Succeeded) {
const token = result.value;
// ...
} else {
console.log("Error obtaining token", result.error);
}
});
getAccessTokenAsync(callback)
Warning
This API is now deprecated.
Use Office.auth.getAccessToken instead.
Calls the Azure Active Directory V 2.0 endpoint to get an access token to your add-in's web application. Enables add-ins to identify users. Server-side code can use this token to access Microsoft Graph for the add-in's web application by using the "on behalf of" OAuth flow.
Important: In Outlook, this API isn't supported if the add-in is loaded in an Outlook.com or Gmail mailbox.
Warning: getAccessTokenAsync has been deprecated. Use Office.auth.getAccessToken instead.
getAccessTokenAsync(callback?: (result: AsyncResult<string>) => void): void;Parameters
- callback
-
(result: Office.AsyncResult<string>) => void
Optional. Accepts a callback function that can parse the token for the user's ID or use the token in the "on behalf of" flow to get access to Microsoft Graph. If AsyncResult.status is "succeeded", then AsyncResult.value is the raw AAD v. 2.0-formatted access token.
Returns
void
Remarks
Applications: Excel, OneNote, Outlook, PowerPoint, Word
Requirement set: IdentityAPI 1.3
This API requires a single sign-on configuration that bridges the add-in to an Azure application. Office users sign in with Organizational Accounts and Microsoft Accounts. Microsoft Azure returns tokens intended for both user account types to access resources in the Microsoft Graph.
Office Add-ins
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for