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

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 is not 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)

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 is not supported if the add-in is loaded in an Outlook.com or Gmail mailbox.

Warning: getAccessTokenAsync has been deprecated. Use Office.auth.getAccessToken instead.

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

Hosts: Excel, OneNote, Outlook, PowerPoint, Word

Important: In Outlook, this API is not supported if the add-in is loaded in an Outlook.com or Gmail mailbox.

Requirement set: IdentityAPI

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 is not 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 method 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

Hosts: Excel, OneNote, Outlook, PowerPoint, Word

Requirement set: IdentityAPI

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 === "succeeded") {
        var 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 is not 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 method 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

Hosts: Excel, OneNote, Outlook, PowerPoint, Word

Requirement set: IdentityAPI

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.