From 6c2c073bd980f2dca1b9ba99b8127734bc4d2f42 Mon Sep 17 00:00:00 2001 From: Alex Jerabek Date: Thu, 21 Mar 2019 15:55:32 -0700 Subject: [PATCH] Adding SSO APIs to preview --- types/office-js-preview/index.d.ts | 84 ++++++++++++++++++++++++++++++ 1 file changed, 84 insertions(+) diff --git a/types/office-js-preview/index.d.ts b/types/office-js-preview/index.d.ts index 6ef3d9d8b5..498dfcea24 100644 --- a/types/office-js-preview/index.d.ts +++ b/types/office-js-preview/index.d.ts @@ -660,6 +660,12 @@ declare namespace Office { *
HostsAccess, Excel, Outlook, PowerPoint, Project, Word
*/ interface Context { + /** + * Provides information and access to the signed-in user. + * + * @beta + */ + auth: Auth; /** * True, if the current platform allows the add-in to display a UI for selling or upgrading; otherwise returns False. * @@ -1263,6 +1269,84 @@ declare namespace Office { */ asyncContext?: any } + + /** + * 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. + * + * @beta + */ + interface Auth { + /** + * 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 + * {@link https://docs.microsoft.com/azure/active-directory/develop/active-directory-v2-protocols-oauth-on-behalf-of | "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. + * + * @remarks + * + * + *
HostsExcel, OneNote, Outlook, PowerPoint, Word
Requirement sets{@link https://docs.microsoft.com/office/dev/add-ins/develop/specify-office-hosts-and-api-requirements | 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. + * + * @param options - Optional. Accepts an AuthOptions object to define sign-on behaviors. + * @param callback - 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. + * + * @beta + */ + getAccessTokenAsync(options?: AuthOptions, callback?: (result: AsyncResult) => void): void; + /** + * 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 + * {@link https://docs.microsoft.com/azure/active-directory/develop/active-directory-v2-protocols-oauth-on-behalf-of | "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. + * + * @remarks + * + * + *
HostsExcel, OneNote, Outlook, PowerPoint, Word
Requirement sets{@link https://docs.microsoft.com/office/dev/add-ins/develop/specify-office-hosts-and-api-requirements | 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. + * + * @param callback - 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. + * + * @beta + */ + getAccessTokenAsync(callback?: (result: AsyncResult) => void): void; + } + /** + * Provides options for the user experience when Office obtains an access token to the add-in from AAD v. 2.0 with the getAccessTokenAsync method. + */ + interface AuthOptions { + /** + * Causes Office to display the add-in consent experience. Useful if the add-in's Azure permissions have changed or if the user's consent has + * been revoked. + */ + forceConsent?: boolean, + /** + * Prompts the user to add their Office account (or to switch to it, if it is already added). + */ + forceAddAccount?: boolean, + /** + * Causes Office to prompt the user to provide the additional factor when the tenancy being targeted by Microsoft Graph requires multifactor + * authentication. The string value identifies the type of additional factor that is required. In most cases, you won't know at development + * time whether the user's tenant requires an additional factor or what the string should be. So this option would be used in a "second try" + * call of getAccessTokenAsync after Microsoft Graph has sent an error requesting the additional factor and containing the string that should + * be used with the authChallenge option. + */ + authChallenge?: string + /** + * A user-defined item of any type that is returned, unchanged, in the asyncContext property of the AsyncResult object that is passed to a callback. + */ + asyncContext?: any + } /** * Provides an option for preserving context data of any type, unchanged, for use in a callback. */