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

...

• ✅ 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)

...