Authentication flow design

[sw-joelmut]

We are planning on improving the authentication flow to provide a better user experience, and to maintain the authentication flow as simple as possible.
To represent how the flow could be, we created a sequence diagram, showing the interaction between the user, agents, and botframework service.

Note

• This design is still in preview and changes could be made to the flow, but the overall representation is there.
• Also, this flow could work in both WebChat and MsTeams, since it will be similar to what MsTeams is doing to retrieve the magic code and send the signin/verifyState Activity. Otherwise it could be conditioned per channel.
• Regarding multiple server instances, if the token isn't in memory, Agents will let the api.botframework service decide the next steps, if it returns a token, it will set the token in memory for that instance and continue as an authenticated user.

Normal login flow steps

The user when entering on a route that requires authentication or requests a token, the auth flow will request the token, since the user is trying to login, the service will return a SignIn resource, this resource is sent to the user's chat as an oAuth card.
When the user clicks on the SignIn button, the token.botframework website will open, and will notify the Agent through the /api/auth/callback endpoint, sending the magic code.
The Agent will receive the magic code and execute the continuation flow requesting the token to the api.botframework service, and continue the execution of the next route.
The magic code exchange will happen in the background so the user don't have to enter it manually.

Image

Edit tool

https://www.mermaidchart.com/app/dashboard

Code

sequenceDiagram
  actor user as user
  participant messages as api/messages (Agents)
  participant api as api.botframework
  participant token as token.botframework
  participant callback as api/auth/callback (Agents)

  user ->> messages: Trigger route with auth
  messages ->> messages: Check memory token status
  break when valid token is in memory
    Note over messages: Valid token
    messages -->> user: Continue with selected route
  end

  messages ->> api: Get token or sign-in resource
  alt is a token response
    Note over messages: Valid token
    api -->> messages: Token response
  else is a signin resource response
    Note over messages: Expired token
    api -->> messages: SignIn resource (begin)
    messages -->> user: Send oAuth card (with SignIn resource)
    user ->> token: Click SignIn button (Sign in page opens)
    token ->> callback: Send magic code
    callback -->> token: Signal Success to close the page
    callback ->> messages: Forward Activity (contains magic code)
    messages ->> api: Send magic code (continue)
    api -->> messages: Token response
  end
  Note over messages: Authenticated
  messages ->> messages: Set token in memory
  messages -->> user: Continue with selected route

Loading

[sw-joelmut]

This is a baseline to keep iterating on the auth design.

/c @rido-min @ceciliaavila

[sw-joelmut]

As discussed internally yesterday, we proceeded to change the following behaviors:

1. Remove the memory cache as it will lead to more problems than solutions, specially when SignIn out from multiple server instances.
2. Remove the automatic magic code for now, but could be a nice feature to add later. And added the old copy and paste method instead.
3. Added a flag to signal when the auth flow was started (when sending the SignIn card)

Image

Code

sequenceDiagram
  actor user as user
  participant messages as api/messages (Agents)
  participant api as api.botframework
  participant token as token.botframework
  participant storage 

  user ->> messages: Trigger route with auth

  messages ->> storage: Check flow started flag
  alt is flow started
    messages -->> messages: Set magic code to get the token in next step
  end
  messages ->> api: Get token or sign-in resource
  alt is a token response
    Note over messages: Valid token
    api -->> messages: Token response
  else is a signin resource response
    Note over messages: Expired token
    messages ->> storage: Set flow started flag
    api -->> messages: SignIn resource (begin)
    messages -->> user: Send oAuth card (with SignIn resource)
    user ->> token: Click SignIn button (Sign in page opens)
    token -->> user: Copy magic code
    user ->> messages: Paste magic code
    messages ->> api: Send magic code (continue)
    api -->> messages: Token response
  end
  Note over messages: Authenticated
  messages ->> messages: Set token in memory
  messages -->> user: Continue with selected route

Loading

[rido-min]

I think we should check if the token is available before checking if the flow has started.

Missing the last call to storage to remove the flow started flag

What means "Set token in memory" ?

[sw-joelmut]

What means "Set token in memory" ?
Ignore it, I forgot to remove it, and set the flag in the storage

I think we should check if the token is available before checking if the flow has started.
I put it first because if the user sends the magic code and the flow is started, use the get token or sign-in resource method once by passing the magic code. Maybe in the code could work this way.

[rido-min]

ah.. I see what you mean. Then we need to consider two entry points, one to check the magic code and one to trigger the oauth flow on first request to a secure handler

[sw-joelmut]

Yea, i couldnt find a way to represent what im trying to do in the code, but this part will be in charge of the decide method.
The decide method will function like an orchestrator, it will detect what is the intention.
For example i have these simple notes i made to remember, but will probably need to be extended to other conditions. So i know which flow i need to take.

// continue: flow started flag + magic code (retry) + continuation activity
// begin: no token from service
// continue: signin/verifyState activity
// exchange: signing/tokenExchange activity

[sw-joelmut]

Creating class diagram ...

[sw-joelmut]

Automatic auth flow sumarized steps

1. Trigger auth route (e.g. graph)
2. Run method will call Decide method
3. Decide (name could change) method, based on certain criteria (flow state, magic code, verifyState or exchangeToken activities, etc.) will decide what to execute, begin, continue, etc.
4. For the decide to complete and continue executing the router, all authorization handlers must be authorized.
5. After finishing the decide process, the Run method will load each AuthorizationHandler instance to the AgentApplication.authorization property for the user to consume.
6. Inside an AgentApplication instance, the token can be accessed by using this.authorization.graph.token.

Note

Since the Run method always check if the user is authorized on the specified auth handler, the route configured method will always have a token.
Other route methods that don’t have could not have the token if the session expired against the service.

[rido-min]

For the decide to complete and continue executing the router, all authorization handlers must be authorized.

I'd say each "decide" should operate on a single auth handler

[rido-min]

Inside an AgentApplication instance, the token can be accessed by using this.authorization.graph.token.

how this could work when running in multiple instances? (we could make a smart property accessor to call the service on first access, but then we should handle expiries.

[sw-joelmut]

Yes, the decide could be handled per auth handler.

Regarding the multiple instances
Since the decide part will take care of getting the token, it will always set the token in the this.authorization.graph.token for the user to consume it.

[sw-joelmut]

This is the base code design structure of the new auth flow. There are parts in the structure that changed compared to the class diagram like class naming, responsibilities, what is exposed to the sample's perspective, etc.
The structure and naming could be improved, but for now it serves as a guideline to start implementing.

What is the idea of this structure:

Naming

1. AuthorizationGuard => graph, github, etc.
2. AutoAuthorization => creates AuthorizationGuard instances.
3. AuthorizationGuardManager => handles the decision of the next auth flow (begin, continue, exchange, etc.)
4. AuthorizationGuardContext => has information exposed to the sample, like token, logout method, etc.

Reason
Decouple the Authorization flow as much as possible from the AgentApplication to avoid configuration and usage mistakes, and provide easy usage and configuration.

Flow of execution

1. AutoAuthorization.create will generate based on the provided information an authorization guard (github, graph, etc.)
2. Each guard will be used in the AgentApplication routes to signal each route that authorization is required.
3. The AgentApplication internally, when the run method is executed, it will detect on the selected route an authorization guard is configured and proceed with the auth flow.
4. The auth flow will be handled by the guard manager, performing the decision to show the oAuth card, receive the magic code, get the token, etc.
5. Once the manager finishes the execution a guard context will be generated, containing information like token, logout method, etc.
6. This guard context will be accessed from the route handler in the sample to retrieve said information.

Notes

• Auth guard manager and auth guard can be combined to reduce the number of classes for this and centralize a bit the auth guard functionality.
• The route handler, before turn, after turn events, etc. everything that comes after the authorization guard configured in the route will only be executed if authorized (finished the authorization flow, and it has a token)