Step-by-Step Process & Entities
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)
6. IntegrationServiceAPI (Integration REST API)
Step 4: Developer Enters Credentials
What happens:
- Developer sees Microsoft login page
- Enters email (e.g.,
developer@example.com) - Enters password
- Completes MFA challenge (required)
- (First time only) Consents to app permissions
Who's involved:
- Developer
- Microsoft Entra ID
What Microsoft validates:
- User credentials are correct
- User has access to the tenant
- User consents to requested scope
Result:
- Microsoft Entra ID validates credentials
- If valid → Proceed to Step 5
- If invalid → Show error, retry
Step 5: Authorization Code Returned
What happens:
- Microsoft Entra ID generates a one-time authorization code
- Redirects browser back to Swagger's callback page
- Code is valid for 10 minutes
Who's involved:
- Microsoft Entra ID
- Swagger UI
Result:
- Swagger UI receives authorization code
- Ready to exchange code for access token
Step 6: Exchange Code for Access Token
What happens:
- Swagger UI automatically exchanges authorization code for access token
- Sends code + PKCE verifier to Microsoft token endpoint
- Microsoft validates code and PKCE verifier
- Returns access token
Who's involved:
- Swagger UI
- Microsoft Entra ID
What's in the access token:
- Who issued it (Microsoft Entra ID)
- Who it's for (ApiService or IntegrationServiceAPI)
- Developer's identity (name and email)
- What permissions are granted
- When it expires (1 hour)
Result:
- Swagger UI now has access token (valid for 1 hour)
- Authorization modal closes
- Lock icons change to closed locks (black) indicating authorized
- Developer can now test endpoints
Step 7: Testing an API Endpoint
What happens (every time developer tests an endpoint):
- Developer selects an endpoint (e.g.,
GET /api/v1/WorkOrder/Overview) - Clicks "Try it out"
- Fills in any required parameters
- Clicks "Execute"
- Swagger UI automatically adds the access token to the request
- Request sent to the API
Who's involved:
- Developer
- Swagger UI
- ApiService or IntegrationServiceAPI
Result:
- API receives authenticated request with token
- Token proves developer's identity and permissions
Step 8: API Validates Token
What happens (on ApiService/IntegrationServiceAPI):
- API receives request with token
- Authentication middleware examines the token
- Checks who issued the token (Azure AD)
- 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)
- If all checks pass → Request continues to controller
- If any check fails → Return 401 Unauthorized
Who's involved:
- ApiService or IntegrationServiceAPI
- JWT Authentication Middleware
- Microsoft Entra ID (public keys used for validation)
What's validated:
- Token signature: Proves it's authentic and not forged
- Issuer: Confirms it came from Azure AD
- Audience: Ensures it's for the correct API
- Expiration: Checks it hasn't expired
Result:
- ✅ Valid token → Controller executes, returns response (200 OK)
- ❌ Invalid token → Authentication fails, returns 401 Unauthorized
- Swagger UI displays the response