User Authentication

Step-by-Step Process & Entities

Entities Involved

1. End User (Browser)

• The person accessing the Partner Portal
• Can be a contractor employee or grid company employee
• Uses their email and password to log in

2. Blazor WebAssembly Application (Frontend)

• The Partner Portal web interface running in the user's browser
• Built with .NET Blazor WebAssembly
• Location: Source/EGU.PartnerPortal.Web
• Runs entirely client-side (in the browser)

3. MSAL.js Library

• Microsoft Authentication Library for JavaScript
• Embedded in the Blazor app
• Handles all OAuth2/OpenID Connect communication
• Manages tokens and session state

4. Microsoft Entra ID (CIAM Tenant)

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

5. ApiService (Backend API)

• The Partner Portal backend REST API
• Built with ASP.NET Core
• Location: Source/EGU.PartnerPortal.ApiService
• Validates JWT tokens on every API request
• Enforces authorization policies

High-Level Authentication Flows

Flow 1: User Login & Authentication (Steps 1-7)

┌─────────────────────────────────────────────────────────────────┐
│              LOGIN & AUTHENTICATION FLOW (Steps 1-7)            │
└─────────────────────────────────────────────────────────────────┘

    ┌──────────────┐
    │   End User   │
    │   Browser    │
    └──────┬───────┘
           │
           │ Step 1: Navigate to app
           │ (https://partners-dev.test-egzynergy.com/)
           ▼
    ┌──────────────────────┐
    │  Blazor WebAssembly  │
    │  (Partner Portal)    │
    └──────┬───────────────┘
           │
           │ Step 2: Check sessionStorage
           │ No valid token found
           │ → Redirect to login
           ▼
    ┌──────────────────────────────┐
    │  Microsoft Entra ID (CIAM)   │
    │  Login Page                  │
    └──────┬───────────────────────┘
           │
           │ Step 3: User enters
           │ email + password + MFA
           ▼
    ┌──────────────────────────────┐
    │  Microsoft Entra ID          │
    │  Validates Credentials       │
    └──────┬───────────────────────┘
           │
           │ ✅ Valid credentials
           │
           │ Step 4: Returns
           │ authorization code
           ▼
    ┌──────────────────────┐
    │  MSAL.js Library     │
    │  (in browser)        │
    └──────┬───────────────┘
           │
           │ Step 5: Exchange code
           │ for tokens (PKCE)
           ▼
    ┌──────────────────────────────┐
    │  Microsoft Entra ID          │
    │  Token Endpoint              │
    └──────┬───────────────────────┘
           │
           │ Returns 3 tokens:
           │ • Access Token (1h)
           │ • Refresh Token (90d)
           │ • ID Token (1h)
           ▼
    ┌──────────────────────┐
    │  Browser             │
    │  sessionStorage      │
    └──────┬───────────────┘
           │
           │ Step 6: Tokens stored
           │ (indexed by scope)
           │
           │ Step 7: Redirect back
           │ to original page
           ▼
    ┌────────────────────────────────┐
    │   ✅ USER AUTHENTICATED         │
    │   Ready to use the app         │
    └────────────────────────────────┘

Flow 2: API Calls with Token Validation (Steps 8-9)

┌─────────────────────────────────────────────────────────────────┐
│            API CALL & VALIDATION FLOW (Steps 8-9)               │
└─────────────────────────────────────────────────────────────────┘

    ┌────────────────────────────────┐
    │   User interacts with app      │
    │   (e.g., views overview page)  │
    └────────────┬───────────────────┘
                 │
                 │ Step 8: Blazor makes API request
                 ▼
    ┌──────────────────────────────────┐
    │  ApiAuthenticationHandler        │
    │  (HTTP Message Handler)          │
    └──────┬───────────────────────────┘
           │
           │ Requests token from MSAL.js
           │ Scope: api://4dad5d62.../ApiService_UserAccess
           ▼
    ┌──────────────────────┐
    │  MSAL.js Library     │
    │  sessionStorage      │
    └──────┬───────────────┘
           │
           │ Returns access token
           │ (or refreshes if expired)
           ▼
    ┌──────────────────────────────┐
    │  HTTP Request                │
    │  GET /api/v1/WorkOrder/...   │
    │  Authorization: Bearer eyJ... │
    └──────┬───────────────────────┘
           │
           │ Step 9: Request received
           ▼
    ┌──────────────────────────────────┐
    │  ApiService                      │
    │  JWT Authentication Middleware   │
    └──────┬───────────────────────────┘
           │
           │ Token Validation:
           │ ✓ Signature (Azure AD keys)
           │ ✓ Issuer (CIAM tenant)
           │ ✓ Audience (this API)
           │ ✓ Expiration (not expired)
           │ ✓ Groups (authorization)
           │
           ├─── ✅ Valid ────┐    ❌ Invalid ───┐
           │                 │                   │
           ▼                 ▼                   ▼
    ┌──────────────┐  ┌──────────────┐  ┌──────────────┐
    │  Controller  │  │  200 OK      │  │  401/403     │
    │  Processes   │  │  Returns     │  │  Unauthorized│
    │  Request     │  │  Data        │  │  Forbidden   │
    └──────────────┘  └──────────────┘  └──────────────┘

┌───────────────────────────────────────────────────────────────┐
│  Step 10: TOKEN RENEWAL (automatic, happens in background)    │
│                                                                │
│  When access token expires (after 1 hour):                    │
│  1. MSAL.js detects expired token                             │
│  2. Uses refresh token to get new access token                │
│  3. Stores new access token in sessionStorage                 │
│  4. User continues working (no interruption)                  │
└───────────────────────────────────────────────────────────────┘