Skip to content

SSO Flow Documentation Using Microsoft Authentication Library (MSAL)

This document provides a detailed overview of the SSO flow implemented in a React application using Microsoft Authentication Library (MSAL) to obtain Microsoft security tokens (JWT) and facilitate user authentication in the nps.today platform.

Prerequisites

  • Microsoft Authentication Library (MSAL): The application uses the MSAL library (@azure/msal-browser) to manage authentication with Microsoft.
  • React Application: The application frontend is built in React.
  • User Store: An internal user database is maintained to map Microsoft accounts to nps.today user accounts.

High-Level Overview

  1. Initiate Login: The user clicks on "Sign in with Microsoft".
  2. Redirect to Microsoft Login: If no valid Microsoft token is available, the user is redirected to the Microsoft login page.
  3. Obtain and Validate Microsoft Token: After successful login, MSAL retrieves a Microsoft-issued JWT (JSON Web Token) for the user.
  4. Map User to Internal Account: The application matches the Microsoft user’s information (e.g., username) with an existing user in the nps.today user store.
  5. Issue Platform Token: If the user is found, an internal access token is issued for nps.today based on the user’s access permissions.

Step-by-Step Flow

Step 1: User Initiates Login with Microsoft

  • Action: The user clicks on the "Sign in With Microsoft" button.
  • Outcome: This triggers the MSAL login process to obtain a Microsoft token.

Step 2: Redirect to Microsoft Login (if necessary)

  • Condition: If a valid Microsoft JWT does not exist in the user’s session, MSAL redirects the user to the Microsoft login page.
  • Details:
  • The application specifies a callback URL (https://app.nps.today/login/microsoft) where the user will be redirected after a successful login.
  • MSAL Library Used: @azure/msal-browser.
  • Documentation Reference: MSAL Overview.

Step 3: Retrieve and Validate Microsoft Token

  • Action: After the user successfully logs in, MSAL retrieves a JWT from Microsoft.
  • Token Validation: The JWT is validated to ensure it is issued by Microsoft, has not expired, and is intended for the correct audience.
  • Claims Checked:
    • iss (Issuer): Ensures the token is from Microsoft.
    • exp (Expiration): Ensures the token is not expired.
    • aud (Audience): Ensures the token is intended for the current application.
  • Outcome: If valid, the token is used to access Microsoft user information (e.g., username, email).

Step 4: Map Microsoft User to Internal User Store

  • Action: The application extracts the username (or another unique identifier) from the Microsoft token and searches for a matching user in the nps.today platform's user store.
  • Conditions:
  • User Found: If a match is found in the user store, proceed to issue an internal access token.
  • User Not Found: If no match is found, the login fails.
  • Purpose: This step allows the application to associate the Microsoft user with an existing nps.today account and retrieve access permissions.

Step 5: Issue Internal Access Token for Platform Access

  • Action: If the user is authenticated in the platform’s user store, an internal access token is generated for them.
  • Token Usage: The access token is valid for access to https://app.nps.today/ and is configured based on the user's permissions in the user store.
  • Outcome: The user can now access nps.today resources and services according to their role and permissions in the platform.

Error Handling and Edge Cases

  • Invalid or Expired Microsoft Token: If the Microsoft token is invalid or expired, the user is redirected to re-authenticate with Microsoft.
  • User Not Found in Platform User Store: If the user does not exist in the platform’s user store, the application can either:
  • Display an error to the user (e.g., "Account not found").
  • Initiate a new user registration flow, depending on the application’s policies.

References

This document outlines the flow to obtain and process a Microsoft token via MSAL, map the user to an internal account, and issue a platform-specific access token for secure access within the nps.today ecosystem.