Skip to main content

​
Overview

The Portal Self-Service Backend API uses Azure Active Directory (Azure AD) for authentication via JWT tokens. This guide walks through the complete setup process.

​
Prerequisites

  • An Azure AD tenant
  • Administrative access to Azure Portal
  • Backend API deployed or running locally

​
Azure AD App Registration

1

Create App Registration

  1. Navigate to Azure Portal
  2. Go to Azure Active Directory > App registrations
  3. Click New registration
  4. Enter a name for your API (e.g., “Portal Self-Service Backend API”)
  5. Select Accounts in this organizational directory only
  6. Click Register
2

Configure API Permissions

  1. In your app registration, go to API permissions
  2. Add Microsoft Graph delegated permissions:
    • User.Read
    • email
    • profile
  3. Grant admin consent for your organization
3

Expose an API

  1. Go to Expose an API
  2. Click Add an Application ID URI
  3. Accept the default value (e.g., api://<client-id>) or set a custom URI
  4. Click Save
The Application ID URI will be used as the AZURE_AUDIENCE environment variable.
4

Configure Authentication

  1. Go to Authentication
  2. Under Implicit grant and hybrid flows, ensure tokens are NOT enabled (we use authorization code flow)
  3. Under Advanced settings, set Allow public client flows to No

​
Environment Variables

After registering your app in Azure AD, configure the following environment variables in your .env file:
.env
# Azure AD Configuration
AZURE_ISSUER_BASE_URL=https://login.microsoftonline.com/<tenant-id>/v2.0
AZURE_AUDIENCE=api://<client-id>
Replace <tenant-id> with your Azure AD tenant ID and <client-id> with your application’s client ID.

​
Finding Your Values

Tenant ID

Found in Azure Portal under Azure Active Directory > Overview > Tenant ID

Client ID

Found in your app registration under Overview > Application (client) ID

​
JWT Verification Process

The API uses the express-oauth2-jwt-bearer library to verify JWT tokens issued by Azure AD.

​
Authentication Middleware

The base JWT verification is configured in src/middleware/authMiddleware.js:
src/middleware/authMiddleware.js
import { auth } from 'express-oauth2-jwt-bearer';

// URL base para obtener el documento de metadatos de OpenID Connect (JWKS URI)
const ISSUER_BASE_URL = process.env.AZURE_ISSUER_BASE_URL; 

// El Application ID URI de tu API Backend registrado en Azure.
const AUDIENCE = process.env.AZURE_AUDIENCE; 

/**
 * Middleware de Autorización.
 * Verifica la validez de un JWT de Entra ID en el header Authorization.
 */
const checkJwtBase = auth({
    // El 'issuer' (emisor) que firmó el token debe ser Microsoft.
    issuerBaseURL: process.env.AZURE_ISSUER_BASE_URL, 
    
    // La 'audience' (audiencia) para la que fue emitido el token debe ser tu API.
    audience: process.env.AZURE_AUDIENCE,
});

​
How It Works

1

Token Validation

The middleware validates the JWT signature using Azure AD’s public keys (JWKS).
2

Issuer Verification

Verifies the token was issued by Microsoft (iss claim matches AZURE_ISSUER_BASE_URL).
3

Audience Verification

Ensures the token was intended for this API (aud claim matches AZURE_AUDIENCE).
4

Expiration Check

Validates the token hasn’t expired (exp claim).
If any validation step fails, the request is rejected with a 401 Unauthorized response.

​
Testing Your Setup

​
1. Obtain a Token

Use your Azure AD client application to obtain a JWT token with the correct audience.

​
2. Make an Authenticated Request

curl -H "Authorization: Bearer <your-jwt-token>" \
  https://your-api.com/api/empleados/profile

​
3. Verify Token Claims

Successful authentication will extract user information from the token claims:
  • oid - Azure Object ID (unique user identifier)
  • upn or preferred_username - User email
  • name - User’s display name

​
Troubleshooting

Possible causes:
  • Token is expired
  • Token signature is invalid
  • Token audience doesn’t match AZURE_AUDIENCE
  • Token issuer doesn’t match AZURE_ISSUER_BASE_URL
Solution: Verify your environment variables match your Azure AD app registration settings.
The first request fetches Azure’s public keys (JWKS). Subsequent requests use cached keys.This is normal behavior and improves performance over time.
Ensure your Azure AD token includes the upn or preferred_username claim. Check your app’s token configuration in Azure Portal.

​
Next Steps

JWT Token Structure

Learn about token claims and the authenticateAndExtract middleware

Roles & Permissions

Configure role-based access control for your API

Build docs developers (and LLMs) love

Get started for freeTalk to us