Step-by-Step Process & Entities

1. Developer/Tester (Browser)

2. Swagger UI (Interactive API Documentation)

3. Microsoft Entra ID (Azure AD Tenant)

4. Swagger Client Application

5. ApiService (Backend REST API)

6. IntegrationServiceAPI (Integration REST API)

High-Level Authorization Flows

Flow 1: Developer Opens Swagger & Authenticates (Steps 1-6)

┌─────────────────────────────────────────────────────────────────┐
│         SWAGGER AUTHENTICATION FLOW (Steps 1-6)                 │
└─────────────────────────────────────────────────────────────────┘

    ┌──────────────┐
    │  Developer   │
    │   Browser    │
    └──────┬───────┘
           │
           │ Step 1: Navigate to Swagger UI
           │ (http://localhost:7532/swagger)
           ▼
    ┌──────────────────────┐
    │   Swagger UI Page    │
    │   (Unauthenticated)  │
    └──────┬───────────────┘
           │
           │ Step 2: Click "Authorize" button
           │ Select oauth2 security scheme
           ▼
    ┌──────────────────────────────┐
    │  Swagger Authorization Modal │
    │  Shows required scopes       │
    └──────┬───────────────────────┘
           │
           │ Step 3: Click "Authorize"
           │ → Redirect to Microsoft login
           ▼
    ┌──────────────────────────────┐
    │  Microsoft Entra ID          │
    │  Login Page                  │
    └──────┬───────────────────────┘
           │
           │ Step 4: User enters
           │ email + password + MFA
           ▼
    ┌──────────────────────────────┐
    │  Microsoft Entra ID          │
    │  Validates Credentials       │
    └──────┬───────────────────────┘
           │
           │ ✅ Valid credentials
           │
           │ Step 5: Returns
           │ authorization code
           ▼
    ┌──────────────────────┐
    │  Swagger UI          │
    │  (PKCE exchange)     │
    └──────┬───────────────┘
           │
           │ Step 6: Exchange code
           │ for access token
           ▼
    ┌──────────────────────────────┐
    │  Microsoft Entra ID          │
    │  Token Endpoint              │
    └──────┬───────────────────────┘
           │
           │ Returns access token (1h)
           ▼
    ┌────────────────────────────────┐
    │   ✅ SWAGGER AUTHORIZED         │
    │   Can test API endpoints       │
    └────────────────────────────────┘

Flow 2: Testing API Endpoint with Token (Steps 7-8)

┌─────────────────────────────────────────────────────────────────┐
│          API TEST & VALIDATION FLOW (Steps 7-8)                 │
└─────────────────────────────────────────────────────────────────┘

    ┌────────────────────────────────┐
    │   Developer clicks "Try it out"│
    │   on an API endpoint           │
    └────────────┬───────────────────┘
                 │
                 │ Step 7: Swagger adds token to request
                 ▼
    ┌──────────────────────────────────┐
    │  HTTP Request                    │
    │  GET /api/v1/WorkOrder/Overview  │
    │  Authorization: Bearer eyJ...    │
    └──────┬───────────────────────────┘
           │
           │ Step 8: Request received
           ▼
    ┌──────────────────────────────────────┐
    │  ApiService/IntegrationServiceAPI    │
    │  JWT Authentication Middleware       │
    └──────┬───────────────────────────────┘
           │
           │ Token Validation:
           │ ✓ Issuer (Azure AD tenant)
           │ ✓ Audience (this API)
           │ ✓ Signature (Azure AD keys)
           │ ✓ Expiration (not expired)
           │
           ├─── ✅ Valid ────┐    ❌ Invalid ───┐
           │                 │                   │
           ▼                 ▼                   ▼
    ┌──────────────┐  ┌──────────────┐  ┌──────────────┐
    │  Controller  │  │  200 OK      │  │  401/403     │
    │  Executes    │  │  Returns     │  │  Unauthorized│
    │  Endpoint    │  │  Data        │  │  Forbidden   │
    └──────────────┘  └──────────────┘  └──────────────┘

Step-by-Step Authorization Process

Step 1: Developer Opens Swagger UI

What happens:

Who's involved:

What you see:

Result:

Step 2: Click "Authorize" Button

What happens:

Who's involved:

Authorization modal shows:

For ApiService:

oauth2 (OAuth2, authorizationCode with PKCE)
Scopes:
  api://4dad5d62-dc8c-4378-8bd0-ae736a4d73fe/access_as_user - Access API as user

For IntegrationServiceAPI:

oauth2 (OAuth2, authorizationCode with PKCE)
Scopes:
  api://bd5100ee-af63-4880-8c60-47d4207d60c1/access_as_user - Access Integration API as user

Result:

Step 3: Initiate OAuth2 Flow

What happens:

Who's involved:

What's sent to Microsoft:

Result:

Step 4: Developer Enters Credentials

What happens:

Who's involved:

What Microsoft validates:

Result:

Step 5: Authorization Code Returned

What happens:

Who's involved:

Result:


Step 6: Exchange Code for Access Token

What happens:

Who's involved:

What's in the access token:

Result:

Step 7: Testing an API Endpoint

What happens (every time developer tests an endpoint):

  1. Developer selects an endpoint (e.g., GET /api/v1/WorkOrder/Overview)
  2. Clicks "Try it out"
  3. Fills in any required parameters
  4. Clicks "Execute"
  5. Swagger UI automatically adds the access token to the request
  6. Request sent to the API

Who's involved:

Result:

Step 8: API Validates Token

What happens (on ApiService/IntegrationServiceAPI):

  1. API receives request with token
  2. Authentication middleware examines the token
  3. Checks who issued the token (Azure AD)
  4. Validates token is authentic:
  5. If all checks pass → Request continues to controller
  6. If any check fails → Return 401 Unauthorized

Who's involved:

What's validated:

Result:

Environment-Based Access Control

Swagger UI access varies by environment for security:

Development Environment (Local)

Testing/Staging/UAT Environments

Production Environment

Token Details

Access Token (JWT)

Purpose: Proves developer is authenticated and authorized to call API endpoints

Lifetime: 1 hour

What's in the token:

When token expires:


Security Mechanisms

PKCE (Proof Key for Code Exchange)

What it does: Protects the authorization code during the OAuth2 flow Why it matters: Prevents attackers from stealing and using authorization codes How it works: Swagger UI automatically generates a secret code that only it knows, making stolen authorization codes useless

Token Signature Validation

What it does: Verifies each token was actually issued by Microsoft Why it matters: Prevents forged or tampered tokens How it works: Azure AD signs tokens with a private key, and the API verifies the signature using Azure AD's public key

Token Expiration

What it does: Tokens automatically expire after 1 hour Why it matters: Limits damage if a token is stolen What happens: Developer must re-authorize in Swagger to get a new token

Audience Validation

What it does: Ensures tokens are used for the intended API only Why it matters: Prevents using an ApiService token for IntegrationServiceAPI (and vice versa) How it works: Each API only accepts tokens specifically issued for it

Issuer Validation

What it does: Verifies tokens come from the correct Azure AD tenant Why it matters: Prevents tokens from other organizations' Azure AD How it works: API only accepts tokens from the configured tenant ID