Edit

Share via

Office.Auth interface

  • Reference
Package:
office

The Office Auth namespace, Office.auth, provides methods for the Office client application to obtain access tokens 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.

Remarks

Examples

// Get the auth context object and use it to get an
// access token.
const authContext = Office.context.auth;
authContext.getAccessTokenAsync(function(result) {
    if (result.status === Office.AsyncResultStatus.Succeeded) {
        const token = result.value;
        console.log(token);
    } else {
        console.log("Error obtaining token", result.error);
    }
});

Methods

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.
getAccessTokenAsync(options, callback)

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.
getAccessTokenAsync(callback)

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.
getAuthContext()

Gets information about the signed-in user. The add-in can pass this information to the Microsoft authentication library (MSAL.js) to get an access token for the current session.

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 Firefox with Enhanced Tracking Protection turned on. This results in error 13001 ("The user is not signed into Office").

  • In Outlook on the web and new Outlook on Windows, 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.

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.

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.

getAuthContext()

Gets information about the signed-in user. The add-in can pass this information to the Microsoft authentication library (MSAL.js) to get an access token for the current session.

getAuthContext(): Promise<AuthContext>;

Returns

Promise<Office.AuthContext>

Promise to the AuthContext object.

Remarks

Hosts: Excel, OneNote, Outlook, PowerPoint, Word

Requirement set: NestedAppAuth 1.1

Examples

try{
    const authContext = await Office.auth.getAuthContext();
    console.log(authContext.userPrincipalName);
} catch (error) {
    console.log("Error obtaining token", error);
}