Authentication Data Flow

Status: Work in progress

Version	Date	Author	Status	Description
0.1	2025-08-29	isierra	WIP	Initial version

Introduction

In the TDP System, authentication is a critical process that ensures only authorized users can access specific resources. The authentication data flow involves several key components and steps to verify user identities and provide user’s information to the different parts of the system.

Processes Boundaries

The user’s information has to go through various processes boundaries. The following diagram illustrates the coarse grained flow of authentication data within the TDP System:

Microsoft Entra External ID

Microsoft Entra External ID (MSEEID) allows registering and managing internal users, as well as providing secure access to external partners and applications.

Application Registrations

An Application Registration must be created for each application that wants to use MSEEID for authentication or the management of any entity in the MS Graph API.

Frontend Application Registration

The frontend needs a corresponding Application Registration in MSEEID to authenticate users and manage their sessions. Depending on the type of frontend and the specific library to interact with MSEEID, the configuration may vary.

Frontend Redirect URIs

If the frontend application is a web application, it will typically use OAuth 2.0 authorization code flow with PKCE (Proof Key for Code Exchange) to obtain access tokens. You access the AppRegistration -> Manage -> Authentication section to add a Web Platform with corresponding redirect URIs.

The redirect URIs depend on the specific routes in your application that handle the authentication response. The following libraries are recommended to handle this part of the authentication:

• Use Microsoft Identity Platform for general documentation.
• For ASP.NET: Use the Microsoft.Identity.Web library family.
• For Vue.js: Use the @azure/msal-browser library and additional guidance on how to use it on Vue.js like this skaylink.

Note

For Desktop or Mobile application consider reviewing the documentation for up to date guidance.

Frontend Client Secret

This App registration requires a ClientSecret (needs periodic renewal) so that the frontend can securely communicate with the MSEEID endpoints.

Caution

NEVER store the value of the client secret in the GIT repository. We recommend one of the following mechanisms to securely store and manage your client secrets:

In development:

• Use a local secrets management tool like dotnet user-secrets for ASP.NET applications.
• Use a .env file (excluded from version control) for other types of applications.

In production:

• Use a Key Vault service, like Azure Key Vault, AWS Secrets Manager, or HashiCorp Vault.
• Avoid using standard Kubernetes Secrets for storing sensitive information.

Frontend API Permissions

The section of API permissions of the frontend application need the following permissions with administrator consent granted:

• openid: Sign users in in MSEEID. Implies the need of a ClientSecret.
• email: View user’s email address.
• profile: View user’s basic profile information.
• offline_access: Maintain access to the user’s data even when they are not actively using the application.
• https://graph.microsoft.com/User.Read: View user’s Microsoft Graph profile information.
• api://<gateway-client-id>/Access: The permission to access the gateway API with access tokens emitted by MSEEID.

Frontend Configuration

Usually the configuration information necessary for using MSEEID in the frontend to issue idToken includes:

• Instance: The URL of the MSEEID instance, where the frontend can find the well-known configuration. E.g. https://<sub-domain>.ciamlogin.com/
• Domain: The domain of the application, used for token validation and other purposes. E.g. <sub-domain>.ciamlogin.com
• TenantId: The ID of the tenant in MSEEID in UUID format. E.g. 11111111-2222-3333-4444-555555555555
• ClientId: The ID of the client application in MSEEID in UUID format. E.g. 11111111-2222-3333-4444-555555555555
• ClientSecret: The secret key of the client application in MSEEID. E.g. <random-string-stored-in-secure-location>
• Other settings like signin/signout callback paths, etc. required by the protocol and the specific authentication library.

In order to access the Gateway API, the frontend application needs to include the following configuration:

• GatewayApiUrl: The URL of the Gateway API. E.g. https://<gateway-url>/api/
• GatewayScopes: The scopes required for accessing the Gateway API. E.g. api://<gateway-client-id>/Access

Frontend API Access

The specific library used for accessing the API from the frontend application must have a way to acquire an access token, and then that token must be added to each Gateway API request as a Bearer Authorization header. E.g. Authorization: Bearer <access_token>.

Also, when logging a user in, the frontend must go through the session request process to obtain a valid Session ID and store that value in the user’s session (like localStorage or sessionStorage). That value MUST be sent with each Gateway API request as a Session-ID header.

Gateway Application Registration

Users Internal Application Registration

Projects Internal Application Registration

Gateway API

Internal Service API

Technical Boundaries

Marten DB

NATS

Temporal.io