Office.Auth interface

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

The Office Auth namespace, Office.context.auth, provides a method that allows the Office host 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

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.

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.

Method Details

getAccessTokenAsync(options, callback)

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

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.

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: AsyncResult<string>) => void

Optional. Accepts a callback method that can use 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)

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

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.

getAccessTokenAsync(callback?: (result: AsyncResult<string>) => void): void;

Parameters

callback
(result: AsyncResult<string>) => void

Optional. Accepts a callback method that can use 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.