Swagger Authorization - Simple Guide

Step-by-Step Process & Entities

Entities Involved

1. Developer/Tester (Browser)

• Person accessing Swagger UI for API testing
• Can be a developer, QA tester, or technical user
• Uses their Microsoft credentials to authenticate with Swagger

2. Swagger UI (Interactive API Documentation)

• Web-based API documentation and testing interface
• Built into both ApiService and IntegrationServiceAPI
• Location: /swagger endpoint (e.g., http://localhost:7532/swagger)
• Allows developers to test API endpoints interactively
• Uses Scalar UI for enhanced API documentation

3. Microsoft Entra ID (Azure AD Tenant)

• Microsoft's cloud identity service
• Stores developer credentials and profiles
• Tenant ID: 6073ce8b-73f3-4df4-9b80-5e40cdc6965f
• Issues JWT tokens after successful authentication
• Hosted by Microsoft (external service)

4. Swagger Client Application

• Azure AD app registration specifically for Swagger UI
• Client ID: 84c38b43-12e4-4c26-8292-8910d79aa532
• Type: Single Page Application (SPA) with PKCE enabled
• Registered in the same Azure AD tenant

5. ApiService (Backend REST API)

• Core backend API
• Location: Source/EGU.PartnerPortal.ApiService
• Swagger URL: http://localhost:7532/swagger (local)
• Client ID: 4dad5d62-dc8c-4378-8bd0-ae736a4d73fe
• Scope: api://4dad5d62-dc8c-4378-8bd0-ae736a4d73fe/access_as_user

6. IntegrationServiceAPI (Integration REST API)

• External system integration API
• Location: Source/EGU.PartnerPortal.IntegrationServiceAPI
• Swagger URL: http://localhost:7098/swagger (local)
• Client ID: bd5100ee-af63-4880-8c60-47d4207d60c1
• Scope: api://bd5100ee-af63-4880-8c60-47d4207d60c1/access_as_user

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   │
    └──────────────┘  └──────────────┘  └──────────────┘