Authentication

[nickrandolph]

Goal: Provide a wrapper around authentication (Eg MSAL, or perhaps a username/password (basic) authentication model)

Authentication & Authorization Requirements

• Control access to application (eg Login/Logout)
• Authorization for service calls
  • Cookies (eg Isaac project)
  • Authorization header (eg ToDo app w Graph API)

Authentication UI/UX Patterns

• In-app (eg Login form that captures username and password)
• Secure WebView
• MSAL

Authentication Token Options

• Returned from service call (eg Func Authenticate(username, password) )
• Returned in cookies in a service call
• Returned in url (web auth)

App Workflow/Scenarios

• App starts

  • Existing cached credentials (token/cookie etc)?

    • No credentials
      • Welcome/Login page
      • After login, redirect to Home/Main page of app (Needs to remove Welcome/Login from backstack)
    • Existing credentials
      • Credentials needs to be validated by either refreshing token or calling a service
        • Successful refresh -> Home/Main page
        • Refresh fails -> Welcome/Login page

  • Logout

    • Redirects to Welcome/Login page (removes all other pages from navigation stack)

  • Service call fails with auth error

    • Auth service should be called to attempt to refresh token
    • Auth service fails, user should be redirected to Welcome/Login

Caching Concerns

• If user initiates logout, should clear cached data?
• If logout because service/auth refresh fails, cached data should be persisted

[nickrandolph]

Authentication sequences

• Authenticate (where actual credentials are required)
  This is driven by some user action eg clicking login button, or launching the app

  • Credentials parameter is optional - some implementations (eg calling a custom auth endpoint) require credentials to be passed in. Others (eg MSAL) will trigger the collection of credentials
  • Since some implementations require the collection of credentials, a dispatcher instance is required in order to access the UI/UX context

• Refresh (typically requires refresh token or some other mechanism to refresh authentication)
  This is invoked as required (often in background thread). For example if service call fails due to authorization error, or when application is launched to ensure credentials are still valid

  • this doesn't use a UI/UX, so is safe to call from background service
  • this should only fail if the credentials are invalid (ie gets an authentication/authorization error back from service call). It should return true if there are credentials but that the service call failed for other reasons (Eg network failure)

• Logout (flushes cached credentials)
  This is drive by some user action eg clicking the logout button. Note that this is not the same as the user being logged out when Refresh fails.

  • this may require access to UI/UX depending on auth stack

interface IAuthenticationService
{
    Task<bool> Login(IDispatcher dispatcher, IDictionary<string,string>? credentials= null);  
    Task<bool> Refresh();  
    Task<bool> Logout(IDispatcher dispatcher);  
}

Service method return options:

• True/False to indicate success?
• No return value (assumed success) but throws exception if unable to Authenticate or Refresh
• IDictionary<string,string> that contains any tokens returned by auth process

Implementations:

• CustomAuthenticationService
  • need to define call to authenticate
  • need to define call to refresh
  • need to define call to logout

record CustomAuthenticationSettings
(
    Func<IDispatcher, ITokenCache, IDictionary<string,string>, Task<bool>> LoginCallback,
    Func<IDispatcher, ITokenCache, Task<boo>>? RefreshCallback = null,
    Func<IDispatcher, ITokenCache, Task<bool>>? LogoutCallback = null
)

record CustomAuthenticationService
(
    ITokenCache Tokens,
    CustomAuthenticationSettings Settings
)

.UseAuthentication(  CustomAuthenticationSettings )

Workflow:

• Authenticate

  Credentials are gathered from some sort of login prompt
  IAuthenticationService.Login method is invoked, passing in the credentials (IDictionary)
  LoginCallback is called with both the ITokenCache instance and the credentials (IDictionary)
  LoginCallback is responsible for invoking any auth services and populating the ITokenCache with any new tokens

• Refresh

  IAuthenticationService.Refresh is called (eg if a service call fails)
  RefreshCallback is called with the existing set of tokens in the ITokenCache
  RefreshCallback is responsible for invoking any refresh service and updating the ITokenCache

• Logout

  IAuthenticationService.Logout is called
  LogoutCallback is called with the existing ITokenCache
  LogoutCallback is responsible for calling any service necessary (often not required) to end current session. LogoutCallback does not need to clear the ITokenCache as this will be handled internally after the LogoutCallback has completed. The return bool value can be set to true to cancel the logout (ITokenCache would not be cleared in this case)

• MSALAuthenticationService

  • launches MSAL for auth
  • needs to define a bunch of MSAL parameters as settings

record MSALAuthenticationService 
(
    ITokenCache Tokens,
    MSALSetting Settings
)

Workflow:

• Authenticate

  IAuthenticationService.Login method is invoked, no credentials are passed in
  Login method invokes MSAL auth process to capture credentials (forces user to go through login process)
  Login method updates ITokenCache with new tokens

• Refresh

  IAuthenticationService.Refresh is called (eg if a service call fails)
  Refresh method invokes MSAL silent auth process to update tokens
  Refresh method updates ITokenCache

• Logout

  IAuthenticationService.Logout is called
  Logout method clears all MSAL accounts
  Logout method clears ITokenCache

[nickrandolph]

Authorization options for service calls

• Apply access and/or refresh token as cookies - Setting cookies requires accessing the CookieContainer on the HttpClientHandler
• Apply authorization header - Authorization header can be set on the httprequest

Implementations:
CookieAuthorizationHandler - caches cookies and reattaches cookies to each request
AuthorizationHeaderHandler - sets access token to each request

record CookieAuthorizationHandler
{
    ITokenCache Tokens;
}

record AuthorizationHeaderHandler
{
    ITokenCache Tokens;
    string AuthorizationTokenName;
}

[nickrandolph]

****** Ignore for now

Authentication Workflow

IAuthenticationService deals with the actual calls to authenticate/refresh, it doesn't help with defining what the user experience should be for login/auth. A typical scenario would be that the app launches and then either goes to a welcome/login page (assuming no cached credentials), after the user logs in, the app redirects to the home page of the app (and removes the login page from any backstack).

interface IAuthenticationWorkflow
{
    void Start(INavigator navigator);
}

interface IAuthenticationSession
{
    Task<bool> Login(IDictionary<string,string> credentials);
    Task<bool> Logout();
}

Workflow:

• IAuthenticationWorkflow is defines as part of IHost setup
• ShellViewModel takes a depedency on IAuthenticationWorkflow
• ShellViewModel calls Start method instead of navigating to any particular page
• IAuthenticationWorkflow determines where to navigate to:
  • Calls IAuthenticationService.Refresh to determine whether it has valid credentials
  • On "true" result from Refresh, navigates to home route
  • On "false" result from Refresh, navigates to login route
• Login view model takes a dependency on IAuthenticationSession
  • After user has entered credentials, the IAuthenticationSession.Login method is called
  • IAuthenticationSession.Login calls IAuthenticationService.Login
    • On "true" result from Login, navigates to home route
    • On "false" result, does nothing (returns false)
• Settings/Provide view model can take a dependency on IAuthenticationSession
  • If user clicks Logout button, IAuthenticationSession.Logout method is called
  • IAuthenticationSession.Logout calls IAuthenticationService.Logout
    • On "true" result from Logout, navigates to login route
    • On "false" result, does nothing (returns false)
• IAuthenticationService.Refresh fails (ie user needs to be logged out without clearing cache)
  • IAuthenticationSession navigates to login route

record AuthenticationWorkflow
{
    IAuthenticationService AuthenticationService,
    ITokenCache TokenCache,
    string? LoginRoute = null,
    Type? LoginView = null,
    Type? LoginViewModel = null,
    string? HomeRoute = null,
    Type? HomeView = null,
    Type? HomeViewModel = null,
}

AuthenticationWorkflow should listen to TokenCache for a "clear" event in order to redirect user back to login page.

[nickrandolph]

Token Cache

interface ITokenCache
{
   Task Save(IDictionary<string, string> tokens); 
   Task Clear();
   Task<IDictionary<string,string>> GetAll();
   event EventHandler TokensCleared;
}