Authentication
The API validates Microsoft identity access tokens and enforces platform RBAC from the employee database. Controllers require authentication by default via a global fallback policy; only explicitly anonymous endpoints (Swagger in Local/Development, and /hc) are exempt.
Bearer token
Send the access token on every request:
<pre><code class="language-http">Authorization: Bearer <access_token>
The OpenAPI security scheme matches the Swagger definition in the service:
| Field | Value |
|---|---|
| Type | HTTP Bearer |
| Scheme | Bearer |
| Format | JWT |
| Description | Valid Entra ID / Azure B2C access token |
Portal clients obtain the token through the Azure B2C PKCE authorization-code flow. See BackOffice portal login for SPA configuration and the MITA app-registration checklist.
Token validation
The host registers JWT Bearer authentication with Microsoft.Identity.Web against the AzureAd configuration section:
<pre><code class="language-json">"AzureAd": { "Instance": "https://login.microsoftonline.com/", "TenantId": "<tenant-id>", "Domain": "<tenant-domain>", "ClientId": "<api-app-client-id>", "Audience": "api://<api-app-client-id>" }
ClientId and Audience must match the API app registration that exposes the scope requested by the portal (for example gals.access).
Platform claims
After the JWT is validated, EmployeeClaimsTransformation resolves the MCA employee and adds GALS claims, including:
| Claim | Purpose |
|---|---|
gals:employeeId | Internal employee identifier |
gals:firstName | Display name support |
| Role / permission claims | Drive [HasPermission] authorization |
On first sign-in, a valid token with no employee row auto-provisions an active employee from the Entra app role (or User) and continues.
Permission policies
Endpoints use [HasPermission(Screen, PermissionAction)]. Policies are named:
<pre><code class="language-text">Permission:{Screen}:{Action}
Examples:
| Endpoint | Policy |
|---|---|
GET /Contract/GetList | Permission:Contract:Read |
POST /Contract/Create | Permission:Contract:Write |
POST /Contract/Run (rollover) | Permission:Contract:Rollover |
GET /Reports/cycle-invoices | Permission:CycleInvoicing:Read |
Missing authentication returns 401. Missing screen permission returns 403. Inactive employees are rejected by PlatformAccessExceptionMiddleware with a 403 validation-style payload.
Calling the API from tools
1. Sign in through the portal (or another confidential client that can request the API scope). 2. Copy the access token from the browser session / token response. 3. Call an endpoint with the Authorization header, for example:
<pre><code class="language-bash">curl -H "Authorization: Bearer $TOKEN" \ "http://localhost:7137/Employee/Me"
Prefer short-lived tokens and never commit them to source control.