OfficeRuntime.AuthOptions interface

Package:

office-runtime

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.

Remarks

The methods in this interface are equivalent to those in the Office.AuthOptions interface. If new authentication types are added in the future, they will only be added to the Office.AuthOptions interface. For simplicity, the code examples throughout the documentation use Office.AuthOptions.

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.