Page History

...

• Swagger UI is loaded but cannot test endpoints yet
• Need to authenticate first

...

Step 2: Click "Authorize" Button

What happens:

• Developer clicks the "Authorize" button (or clicks a lock icon)
• Modal dialog appears showing available security schemes
• Shows OAuth2 (Authorization Code with PKCE) security scheme
• Displays the required scope for the API

Who's involved:

• Developer
• Swagger UI

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:

• Developer sees what permissions will be requested
• Ready to start OAuth2 flow

...

Step 3: Initiate OAuth2 Flow

What happens:

• Developer clicks "Authorize" in the modal
• Swagger UI starts the OAuth2 Authorization Code flow
• Browser redirects to Microsoft Entra ID login page
• Security code (PKCE) generated automatically

Who's involved:

• Swagger UI
• Microsoft Entra ID

What's sent to Microsoft:

• Swagger client ID
• Which API scope is needed
• Security challenge code (PKCE)
• Where to redirect back after login

Result:

• Browser redirected to Microsoft login page

...

Step 4: Developer Enters Credentials

...

1. API receives request with token
2. Authentication middleware examines the token
3. Checks who issued the token (Azure ADEntra ID)
4. Validates token is authentic:
   • Signature is valid (proves token came from Azure AD)
   • Issuer matches (correct Azure AD tenant)
   • Audience matches (token is for this specific API)
   • Not expired (within 1-hour lifetime)
5. If all checks pass → Request continues to controller
6. If any check fails → Return 401 Unauthorized

...

• Token signature: Proves it's authentic and not forged
• Issuer: Confirms it came from Azure ADEntra ID
• Audience: Ensures it's for the correct API
• Expiration: Checks it hasn't expired

...

• ✅ Valid token → Controller executes, returns response (200 OK)
• ❌ Invalid token → Authentication fails, returns 401 Unauthorized
• Swagger UI displays the response

...

Environment-Based Access Control

Swagger UI access varies by environment for security:

Development Environment (Local)

• Access: Fully open - anyone on localhost can use Swagger
• URL: http://localhost:7532/swagger or http://localhost:7098/swagger

Testing/Staging/UAT Environments

• Access: IP whitelist required - only approved IP addresses can access
• Restriction: Returns 403 Forbidden if IP not on whitelist
• 📄 See: Swagger IP Whitelisting Documentation

Production Environment

• Access: Completely disabled for security
• Result: Swagger endpoints return 404 Not Found

...

Token Details

Access Token (JWT)

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

Lifetime: 1 hour

What's in the token:

• Audience: Which API this token is for (ApiService or IntegrationServiceAPI)
• Issuer: Microsoft Entra ID (proves it came from Azure AD)
• Expiration: When the token expires
• User identity: Developer's name and email
• Permissions: What the developer can access (scope)
• Signature: Cryptographic proof the token is authentic

When token expires:

• After 1 hour, developer must click "Authorize" again
• No automatic refresh (unlike the Web app)
• Lock icons change back to open (grayed out)

...

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

...

Quick Reference

ApiService

...

IntegrationServiceAPI

...

Common Values

...