From e9a1eb208a07a8aefe229f9bfc68c07982e64c96 Mon Sep 17 00:00:00 2001 From: Rick-Kirkham Date: Wed, 12 Aug 2020 11:40:20 -0700 Subject: [PATCH] =?UTF-8?q?[office-js,=20office-js-preview,=20office-runti?= =?UTF-8?q?me]=20change=20sso=20status=20from=E2=80=A6=20(#46683)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * [office-js, office-js-preview, office-runtime] change sso status from preview to release * review changes * aligning asterisks * remove trailing whitespace * review changes * review change --- types/office-js-preview/index.d.ts | 79 ++++++++++++++---------- types/office-js/index.d.ts | 97 ++++++++++++++++++++++++++++- types/office-runtime/index.d.ts | 98 +++++++++++++++--------------- 3 files changed, 194 insertions(+), 80 deletions(-) diff --git a/types/office-js-preview/index.d.ts b/types/office-js-preview/index.d.ts index 820b32ce76..802863323c 100644 --- a/types/office-js-preview/index.d.ts +++ b/types/office-js-preview/index.d.ts @@ -1181,18 +1181,16 @@ declare namespace Office { } /** - * 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. + * The Office Auth namespace, `Office.context.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. - * - * @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 + * 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. + * **Important**: In Outlook, this API is not supported if the add-in is loaded in an Outlook.com or Gmail mailbox. * * @remarks * @@ -1200,22 +1198,20 @@ declare namespace Office { * * **Requirement set**: {@link https://docs.microsoft.com/office/dev/add-ins/reference/requirement-sets/identity-api-requirement-sets | IdentityAPI} * - * This API requires a single sign-on configuration that bridges the add-in to an Azure application. Office users sign-in with Organizational + * 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 + * @param options - Optional. Accepts an `AuthOptions object` to define sign-on behaviors. + * @param callback - 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. */ 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 + * 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. + * **Important**: In Outlook, this API is not supported if the add-in is loaded in an Outlook.com or Gmail mailbox. * * @remarks * @@ -1223,41 +1219,62 @@ declare namespace Office { * * **Requirement set**: {@link https://docs.microsoft.com/office/dev/add-ins/reference/requirement-sets/identity-api-requirement-sets | IdentityAPI} * - * This API requires a single sign-on configuration that bridges the add-in to an Azure application. Office users sign-in with Organizational + * 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 + * @param callback - 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. */ 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. + * 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. + * Allows Office to get an access token silently or through interactive consent, if one is required. Default value is `false`. + * If set to `false`, Office will silently try to get an access token. If it fails to do so, Office will return a descriptive error. + * If set to `true`, Office will show an interactive consent UI after it fails to silently get an access token. + * The prompt will only allow consent to the AAD profile scope, not to any Microsoft Graph scopes. */ - forceConsent?: boolean, + allowConsentPrompt?: boolean; /** - * Prompts the user to add their Office account (or to switch to it, if it is already added). + * Allows Office to get an access token silently provided consent is present or show interactive UI to sign in the user. Default value is `false`. + * If set to `false`, Office will silently try to get an access token. If it fails to do so, Office will return a descriptive error. + * If set to `true`, Office will show an interactive sign-in UI after it fails to silently get an access token. */ - forceAddAccount?: boolean, + allowSignInPrompt?: boolean; + /** + * Prompts the user to add their Office account (or to switch to it, if it is already added). Default value is `false`. + * + * @deprecated Use `allowSignInPrompt` instead. + */ + forceAddAccount?: boolean; + /** + * 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. Default value is `false`. + * + * @deprecated Use `allowConsentPrompt` instead. + */ + forceConsent?: 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. + * 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 + 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. + * 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 + asyncContext?: any; + /** + * Causes Office to return a descriptive error when the add-in wants to access Microsoft Graph and the user/admin has not granted consent to Graph scopes. Default value is `false`. + * Office only supports consent to Graph scopes when the add-in has been deployed by a tenant admin. This information will not be available during development. + * Setting this option to `true` will cause Office to inform your add-in beforehand (by returning a descriptive error) if Graph access will fail. + */ + forMSGraphAccess?: boolean; } /** * Provides an option for preserving context data of any type, unchanged, for use in a callback. diff --git a/types/office-js/index.d.ts b/types/office-js/index.d.ts index 4a72d565c0..be7b8cf4fe 100644 --- a/types/office-js/index.d.ts +++ b/types/office-js/index.d.ts @@ -1021,7 +1021,102 @@ declare namespace Office { */ asyncContext?: any } - + /** + * The Office Auth namespace, `Office.context.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. + */ + 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 + * + * **Hosts**: Excel, OneNote, Outlook, PowerPoint, Word + * + * **Requirement set**: {@link https://docs.microsoft.com/office/dev/add-ins/reference/requirement-sets/identity-api-requirement-sets | 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 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. + */ + 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 + * + * **Hosts**: Excel, OneNote, Outlook, PowerPoint, Word + * + * **Requirement set**: {@link https://docs.microsoft.com/office/dev/add-ins/reference/requirement-sets/identity-api-requirement-sets | 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 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. + */ + 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 { + /** + * Allows Office to get an access token silently or through interactive consent, if one is required. Default value is `false`. + * If set to `false`, Office will silently try to get an access token. If it fails to do so, Office will return a descriptive error. + * If set to `true`, Office will show an interactive consent UI after it fails to silently get an access token. + * The prompt will only allow consent to the AAD profile scope, not to any Microsoft Graph scopes. + */ + allowConsentPrompt?: boolean; + /** + * Allows Office to get an access token silently provided consent is present or show interactive UI to sign in the user. Default value is `false`. + * If set to `false`, Office will silently try to get an access token. If it fails to do so, Office will return a descriptive error. + * If set to `true`, Office will show an interactive sign-in UI after it fails to silently get an access token. + */ + allowSignInPrompt?: boolean; + /** + * Prompts the user to add their Office account (or to switch to it, if it is already added). Default value is `false`. + * + * @deprecated Use `allowSignInPrompt` instead. + */ + forceAddAccount?: boolean; + /** + * 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. Default value is `false`. + * + * @deprecated Use `allowConsentPrompt` instead. + */ + forceConsent?: 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; + /** + * Causes Office to return a descriptive error when the add-in wants to access Microsoft Graph and the user/admin has not granted consent to Graph scopes. Default value is `false`. + * Office only supports consent to Graph scopes when the add-in has been deployed by a tenant admin. This information will not be available during development. + * Setting this option to `true` will cause Office to inform your add-in beforehand (by returning a descriptive error) if Graph access will fail. + */ + forMSGraphAccess?: boolean; + } /** * Provides an option for preserving context data of any type, unchanged, for use in a callback. */ diff --git a/types/office-runtime/index.d.ts b/types/office-runtime/index.d.ts index 4c51abc30d..6dfe240b42 100644 --- a/types/office-runtime/index.d.ts +++ b/types/office-runtime/index.d.ts @@ -164,73 +164,75 @@ declare namespace OfficeRuntime { } /** * Contains authorization related APIs. - * @beta */ const auth: Auth; - /** - * Provides options for the user experience when Office obtains an access token to the add-in from AAD v. 2.0 with the getAccessToken method. - * @beta - */ - interface AuthOptions { /** - * Allows Office to get an access token silectly or through interactive consent, if one is required. - * If set to false, Office will silently try to get an access token. If it fails to do so, Office will return a descriptive error. - * If set to true, Office will show an interactive consent UI after it fails to silently get an access token. - * The prompt will only allow consent to the AAD profile scope, not to any Microsoft Graph scopes. + * Provides options for the user experience when Office obtains an access token to the add-in from AAD v. 2.0 with the `getAccessToken` method. */ - allowConsentPrompt?: boolean; - /** - * Allows Office to get an access token silently provided consent is present or show interactive UI to sign in the user. - * If set to false, office will silently try to get an access token. If it fails to do so, Office will return a descriptive error. - * If set to true, Office will show an interactive sign-in UI after it fails to silently get an access token. - */ - allowSignInPrompt?: boolean; - /** - * Deprecated - * 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 getAccessToken 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; - /** - * Causes Office to return descriptive error when the add-in wants to access MS Graph and the user/admin has not granted consent to MS Graph scopes. - * Office only supports consent to graph scopes when the add-in has been deployed by a tenant admin. This information will not be available during development. - * Setting this option to true will allow Office to inform your add-in beforehand if MS graph access will fail by returning back a descriptive error. - */ - forMSGraphAccess?: boolean; + interface AuthOptions { + /** + * Allows Office to get an access token silently or through interactive consent, if one is required. Default value is `false`. + * If set to `false`, Office will silently try to get an access token. If it fails to do so, Office will return a descriptive error. + * If set to `true`, Office will show an interactive consent UI after it fails to silently get an access token. + * The prompt will only allow consent to the AAD profile scope, not to any Microsoft Graph scopes. + */ + allowConsentPrompt?: boolean; + /** + * Allows Office to get an access token silently provided consent is present or show interactive UI to sign in the user. Default value is `false`. + * If set to `false`, Office will silently try to get an access token. If it fails to do so, Office will return a descriptive error. + * If set to `true`, Office will show an interactive sign-in UI after it fails to silently get an access token. + */ + allowSignInPrompt?: boolean; + /** + * Prompts the user to add their Office account (or to switch to it, if it is already added). Default value is `false`. + * + * @deprecated Use `allowSignInPrompt` instead. + */ + forceAddAccount?: boolean; + /** + * 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. Default value is `false`. + * + * @deprecated Use `allowConsentPrompt` instead. + */ + forceConsent?: 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 `getAccessToken` 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; + /** + * Causes Office to return a descriptive error when the add-in wants to access Microsoft Graph and the user/admin has not granted consent to Graph scopes. Default value is `false`. + * Office only supports consent to Graph scopes when the add-in has been deployed by a tenant admin. This information will not be available during development. + * Setting this option to `true` will cause Office to inform your add-in beforehand (by returning a descriptive error) if Graph access will fail. + */ + forMSGraphAccess?: boolean; } /** * Interface that contains authorization related APIs. - * @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 + * 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}. * 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. * - * Important: In Outlook, this API is not supported if the add-in is loaded in an Outlook.com or Gmail mailbox. + * **Important**: In Outlook, this API is not supported if the add-in is loaded in an Outlook.com or Gmail mailbox. * * @remarks * - * **Hosts**: Excel, PowerPoint, Word + * **Hosts**: Excel, Outlook, PowerPoint, Word * - * @beta - * - * @param options - Optional. Accepts an AuthOptions object to define sign-on behaviors. + * @param options - Optional. Accepts an `AuthOptions` object to define sign-on behaviors. * returns: Promise to the access token. */ getAccessToken(options?: AuthOptions): Promise;