Edit

Share via

Office.AuthOptions interface

  • Reference
Package:
office

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.

Properties

allowConsentPrompt

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.
allowSignInPrompt

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.
asyncContext

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.
authChallenge

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.
forceAddAccount

Prompts the user to add their Office account (or to switch to it, if it is already added). Default value is false.
forceConsent

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.
forMSGraphAccess

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. Setting this option to true will cause Office to inform your add-in beforehand (by returning a descriptive error) if Graph access will fail.

Property Details

allowConsentPrompt

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;

Property Value

boolean

allowSignInPrompt

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;

Property Value

boolean

asyncContext

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;

Property Value

any

authChallenge

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;

Property Value

string

forceAddAccount

Warning

This API is now deprecated.

Use allowSignInPrompt instead.

Prompts the user to add their Office account (or to switch to it, if it is already added). Default value is false.

forceAddAccount?: boolean;

Property Value

boolean

forceConsent

Warning

This API is now deprecated.

Use allowConsentPrompt instead.

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.

forceConsent?: boolean;

Property Value

boolean

forMSGraphAccess

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. 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;

Property Value

boolean

Remarks

Note: If you're developing an Outlook add-in that uses single sign-on (SSO), comment out the forMSGraphAccess option before sideloading the add-in for testing. Otherwise, you'll receive error 13012. For additional guidance, see Details on SSO with an Outlook add-in.