Class UserAuthorizationFeature

Namespace

Microsoft.Agents.Builder.App.UserAuth

Assembly

Microsoft.Agents.Builder.dll

UserAuthorization supports and extensible number of OAuth flows.

Auto Sign In: If enabled in UserAuthorizationOptions, sign in starts automatically after the first Message the user sends. When the sign in is complete, the turn continues with the original message. On failure, OnUserSignInFailure(Func<ITurnContext, ITurnState, string, SignInResponse, CancellationToken, Task>) is called.

Manual Sign In: SignInUserAsync(ITurnContext, ITurnState, string, string, IList<string>, CancellationToken) is used to get a cached token or start the sign in. In either case, the OnUserSignInSuccess(Func<ITurnContext, ITurnState, string, string, CancellationToken, Task>) and OnUserSignInFailure(Func<ITurnContext, ITurnState, string, SignInResponse, CancellationToken, Task>) should be set to handle continuation. That is, after calling SignInUserAsync, the turn should be considered complete, and performing actions after that could be confusing. i.e., Perform additional turn activity in OnUserSignInSuccess.

public class UserAuthorizationFeature

Inheritance

object

UserAuthorizationFeature

Inherited Members

object.GetType()

object.MemberwiseClone()

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Remarks

This is always executed in the context of a turn for the user in ITurnContext.Activity.From.

Constructors

UserAuthorizationFeature(AgentApplication, UserAuthorizationOptions)

public UserAuthorizationFeature(AgentApplication app, UserAuthorizationOptions options)

Parameters

app AgentApplication

options UserAuthorizationOptions

Properties

DefaultHandlerName

public string DefaultHandlerName { get; }

Property Value

string

Methods

GetTurnToken(string)

Return a previously acquired token.

public string GetTurnToken(string handlerName)

Parameters

handlerName string

Returns

string

IsSignInCompletionEvent(IActivity)

public static bool IsSignInCompletionEvent(IActivity activity)

Parameters

activity IActivity

Returns

bool

OnUserSignInFailure(AuthorizationFailure)

The handler function is called when the user sign in flow fails

public void OnUserSignInFailure(AuthorizationFailure handler)

Parameters

handler AuthorizationFailure

The handler function to call when the user failed to signed in

Remarks

This is called for either Manual or Auto SignIn flows. However, normally expected AgentApplication Turn process has not been performed during an Auto Sign In. This handler should be used to send failure message to the user and the turn ended.

OnUserSignInSuccess(AuthorizationSuccess)

The handler function is called when the user has successfully signed in

public void OnUserSignInSuccess(AuthorizationSuccess handler)

Parameters

handler AuthorizationSuccess

The handler function to call when the user has successfully signed in

Remarks

This is only used for manual user authorization. The Auto Sign In will continue the turn with the original user message.

ResetStateAsync(ITurnContext, ITurnState, string, CancellationToken)

Clears all UserAuth state for the user. This includes cached tokens, and flow related state.

public Task ResetStateAsync(ITurnContext turnContext, ITurnState turnState, string handlerName = null, CancellationToken cancellationToken = default)

Parameters

turnContext ITurnContext

turnState ITurnState

handlerName string

cancellationToken CancellationToken

Returns

Task

SignInUserAsync(ITurnContext, ITurnState, string, string, IList<string>, CancellationToken)

Acquire a token with OAuth. OnUserSignInSuccess(Func<ITurnContext, ITurnState, string, string, CancellationToken, Task>) and OnUserSignInFailure(Func<ITurnContext, ITurnState, string, SignInResponse, CancellationToken, Task>) should be set to handle continuation. Those handlers will be called with a token is acquired.

public Task SignInUserAsync(ITurnContext turnContext, ITurnState turnState, string handlerName, string exchangeConnection = null, IList<string> exchangeScopes = null, CancellationToken cancellationToken = default)

Parameters

turnContext ITurnContext

The turn context.

turnState ITurnState

handlerName string

The name of the authorization setting.

exchangeConnection string

exchangeScopes IList<string>

cancellationToken CancellationToken

The cancellation token.

Returns

Task

Exceptions

InvalidOperationException

If a flow is already active.

SignOutUserAsync(ITurnContext, ITurnState, string?, CancellationToken)

public Task SignOutUserAsync(ITurnContext turnContext, ITurnState turnState, string? flowName = null, CancellationToken cancellationToken = default)

Parameters

turnContext ITurnContext

turnState ITurnState

flowName string

cancellationToken CancellationToken

Returns

Task