Identity Provider (IdP) - Concepts

📋Learning Objectives

• Understand OIDC and OAuth2 protocols
• Know the different token types and their purposes
• Understand JWT structure and claims
• Explore the IdP architecture
• Understand the Hot-Core + Extension database architecture
• Run migrations and reset the IdP database
• Inspect IdP data using pgAdmin or psql

🔐OAuth2 Fundamentals

OAuth2 is an authorization framework that enables applications to obtain limited access to user accounts:

Key Concepts

• Resource Owner: The user who owns the data
• Client: The application requesting access (e.g., BFF)
• Authorization Server: Issues tokens (our IdP)
• Resource Server: Hosts protected resources (APIs)

OAuth2 Grant Types

🪪OpenID Connect (OIDC)

OIDC is an identity layer built on top of OAuth2. While OAuth2 handles authorization, OIDC adds authentication:

What OIDC Adds

• ID Token: Contains user identity information
• UserInfo Endpoint: Returns additional user claims
• Discovery: Standard endpoint for configuration
• Standard Claims: sub, email, name, etc.

OIDC Discovery Endpoint

# Get IdP's OIDC configuration
curl -k https://idp.self.empowernow.ai/api/oidc/.well-known/openid-configuration

# Response includes:
{
  "issuer": "https://idp.self.empowernow.ai",
  "authorization_endpoint": "https://idp.self.empowernow.ai/api/oidc/authorize",
  "token_endpoint": "https://idp.self.empowernow.ai/api/oidc/token",
  "userinfo_endpoint": "https://idp.self.empowernow.ai/api/oidc/userinfo",
  "jwks_uri": "https://idp.self.empowernow.ai/api/oidc/.well-known/jwks.json",
  ...
}

🎟️Token Types

1. Access Token

Used to access protected resources:

• Purpose: Authorize API requests
• Lifetime: Short (typically 1 hour)
• Contains: Subject, scopes, expiry, issuer
• Usage: Bearer token in Authorization header

2. Refresh Token

Used to obtain new access tokens:

• Purpose: Renew access without re-authentication
• Lifetime: Long (days to weeks)
• Storage: Must be stored securely (backend only)
• Usage: Exchange for new access token

3. ID Token

Contains user identity information (OIDC only):

• Purpose: Prove user authentication
• Lifetime: Short, used once after login
• Contains: User claims (sub, email, name)
• Usage: Verify user identity in client

📝JWT Structure

JSON Web Tokens (JWTs) have three parts separated by dots:

1. Header

{
  "alg": "RS256",      // Algorithm: RSA with SHA-256
  "typ": "JWT",        // Token type
  "kid": "key-id-123"  // Key ID for verification
}

2. Payload (Claims)

{
  // Standard claims
  "iss": "https://idp.self.empowernow.ai",  // Issuer
  "sub": "user-uuid-123",                        // Subject (user ID)
  "aud": "my-app-client-id",                     // Audience
  "exp": 1699900000,                             // Expiration time
  "iat": 1699896400,                             // Issued at
  "nbf": 1699896400,                             // Not before
  
  // OIDC claims
  "email": "user@empowerid.com",
  "name": "John Doe",
  
  // Custom claims
  "scope": "openid profile email",
  "roles": ["admin", "user"]
}

3. Signature

Created by signing header + payload with private key. Verified using public key from JWKS endpoint.

🏗️IdP Architecture

The EmpowerNow IdP is built with FastAPI and follows a modular architecture:

Key Components

• OIDC API: Standard OAuth2/OIDC endpoints
• Admin API: Client and user management
• MCP Server: AI agent integration (port 8070)
• Token Engine: JWT generation and validation
• Session Store: Redis-backed session management

🚀The Token Journey: From Request to Resource

Chapter 1: The Token Request

Our story begins when a service (let's call it the "Scheduler Service") needs to call the Calendar API. The Scheduler doesn't have a user—it's a background job. So it uses the client credentials flow:

Chapter 2: Inside the IdP

When the token request arrives, the IdP performs several critical steps:

1. Client Lookup — Query the oauth_clients table (the hot-core we discussed)
2. Secret Verification — Hash the provided secret with PBKDF2-SHA256 and compare
3. Scope Validation — Ensure the client is allowed to request these scopes
4. JWT Generation — Create the token with claims (sub, iss, aud, exp, scope)
5. Signing — Sign with the private key (RSA-SHA256)

Chapter 3: At the API Gateway

When the Calendar API receives the request, it never calls back to the IdP. Instead:

1. Extract Token — Parse the Authorization: Bearer header
2. Decode Header — Base64-decode the first segment to find the kid
3. Fetch JWKS — Get public keys from the IdP (cached for hours)
4. Verify Signature — Use the matching public key to verify the signature
5. Validate Claims — Check exp (not expired), iss (correct issuer), aud (intended for this API)
6. Check Scopes — Ensure the token has permission for this operation

Chapter 4: When Things Go Wrong

Understanding the journey helps you debug failures:

• 401 at /token → Client credentials wrong (check client_id, secret)
• 401 at API "invalid_token" → Signature verification failed (kid mismatch? key rotation?)
• 401 at API "token_expired" → Check the exp claim, token needs refresh
• 403 at API → Token is valid but missing required scope

🌐Identity Federation

What is Identity Federation?

Federation means trusting another Identity Provider to authenticate users on your behalf. Instead of managing credentials locally, you delegate authentication to an external IdP (like Azure AD, Okta, or Google) and accept their tokens as proof of identity.

Federation vs Local Authentication

*Federated users can access EmpowerNow without any entry in the local users table—PDP policies authorize access based on their ARN pattern.

How Federation Works

When a user clicks "Sign in with Azure AD", a multi-step dance happens between three parties:

Key Steps Explained

• Steps 1-3: User initiates login; EmpowerNow IdP redirects to Azure
• Steps 4-5: User authenticates with Azure (their IT policies apply—MFA, conditional access, etc.)
• Steps 6-8: Azure returns an authorization code; IdP exchanges it for Azure tokens
• Step 9: IdP validates Azure tokens using JWKS (JSON Web Key Set)—no introspection needed
• Step 10: IdP mints its own tokens with a provider-scoped ARN as the subject
• Steps 13-15: All authorization decisions use the ARN—PDP doesn't care if you're local or federated

Identity ARNs for Federated Users

Every identity in EmpowerNow—local or federated—gets a canonical ARN (Amazon Resource Name-style identifier):

auth:{type}:{provider}:{subject}

# Examples:
auth:account:empowernow:alice                    # Local user
auth:account:entra.contoso:ffe9b9f0-ec04-4b9c   # Azure AD user (oid)
auth:account:okta:00u1a2b3c4d5e6f7g8            # Okta user
auth:account:google:108234567890123456789       # Google user
auth:agent:acme-corp:invoice-bot                # AI agent

Why ARNs Matter

• Provider namespacing: entra.contoso vs entra.fabrikam prevents cross-tenant collisions
• Stable identity: Azure oid (Object ID) is used, not email (which can change)
• Policy targeting: Write PDP policies that match ARN patterns: auth:account:entra.*:*
• Audit trails: Every action is attributed to a specific, traceable identity

JWKS Validation (No Introspection)

When the IdP receives an Azure token, it validates using JWKS (JSON Web Key Set)—a public endpoint where Azure publishes its signing keys:

# Azure JWKS endpoint (per-tenant)
https://login.microsoftonline.com/{tenant-id}/discovery/v2.0/keys

# Response contains public keys:
{
  "keys": [
    {
      "kty": "RSA",
      "kid": "abc123...",     // Key ID (matches JWT header)
      "n": "0vx7agoebG...",   // RSA modulus
      "e": "AQAB"             // RSA exponent
    }
  ]
}

Validation steps:

1. Fetch JWKS from Azure (cached for ~24 hours)
2. Find the key matching the JWT's kid (key ID) header
3. Verify the signature using the public key
4. Validate iss (issuer), aud (audience), exp (expiry)

Claims Mapping

Azure tokens have Azure-specific claims. The IdP maps them to EmpowerNow's format:

Example: Federated Token

After federation, the EmpowerNow IdP mints a token like this:

{
  "iss": "https://idp.self.empowernow.ai",
  "sub": "auth:account:entra.contoso:ffe9b9f0-ec04-4b9c-bd48-30fdefd72a5e",
  "aud": ["bff-client"],
  "email": "john.doe@contoso.com",
  "name": "John Doe",
  "roles": ["User", "Admin"],
  "idp": "entra.contoso",
  "idp_sub": "ffe9b9f0-ec04-4b9c-bd48-30fdefd72a5e",
  "federation": {
    "orig_iss": "https://login.microsoftonline.com/contoso.com/v2.0",
    "orig_sub": "ffe9b9f0-ec04-4b9c-bd48-30fdefd72a5e",
    "stable_id_claim": "oid"
  },
  "exp": 1706000000,
  "iat": 1705996400
}

🗄️Data Layer: Hot-Core + Extension Architecture

The IdP uses a two-table design that separates hot-path data from flexible configuration. This keeps token endpoint queries fast while allowing configuration changes without migrations.

Why Two Tables?

Key Tables

• oauth_clients: Client registrations (client_id, secret_hash, scopes, grant_types)
• oauth_client_ext: Flexible client config and metadata (JSONB)
• accounts: User accounts (sub, name, email, status)
• account_ext: User preferences and custom attributes (JSONB)
• credentials: Passwords and WebAuthn passkeys
• identities: Email, phone, and federated identity links

SELECT client_id, secret_hash, grant_types, scopes, fapi_profile
FROM idp.oauth_clients WHERE client_id = $1;

🔄Running Migrations

IdP uses Alembic with separate dev and prod migration chains (versions_shared + versions_dev vs versions_shared + versions_prod). The idp-alembic container picks alembic.ini or alembic-prod.ini from IDP_MIGRATION_PROFILE (add -f docker-compose.prod.yml for prod). See docs/idp-migration-devops-guide.html.

Automatic Setup (Default)

When you run docker compose --profile core up, migrations run automatically. From your project root (e.g. EmpowerNow):

# Migrations are automatic! Just start services:
cd ServiceConfigs/Deployment
docker compose --profile core up -d

# The idp-alembic container (default dev profile):
# 1. Creates the 'idp' schema (versions_shared 0001-0008)
# 2. Seeds infrastructure (0009 in versions_shared)
# 3. Runs dev chain (versions_dev): full clients/users from 0010, then 0011-0017
# 4. Prod chain (versions_prod p0010-p0012) only if IDP_MIGRATION_PROFILE=prod
# 5. IdP waits for alembic to complete before starting

Fresh Start (Reset Database)

If you need to completely reset the IdP database:

# Stop IdP first
docker stop idp-app

# Drop and recreate database
docker exec empowernow-db-1 psql -U postgres -c "DROP DATABASE IF EXISTS idp_db;"
docker exec empowernow-db-1 psql -U postgres -c "CREATE DATABASE idp_db WITH ENCODING 'UTF8';"

# Run migrations + seed data
docker compose -f docker-compose.yml -f docker-compose-build.yml \
    --profile core up idp-alembic --build

# Restart IdP
docker start idp-app

Verify Seeded Data

# Check that clients were seeded
docker exec empowernow-db-1 psql -U postgres -d idp_db -c \
    "SELECT client_id FROM idp.oauth_clients;"

# Check that users were seeded
docker exec empowernow-db-1 psql -U postgres -d idp_db -c \
    "SELECT sub, name FROM idp.accounts;"

docker exec empowernow-db-1 psql -U postgres -d idp_db \
    -c "DROP SCHEMA IF EXISTS idp CASCADE;"

🔧Using pgAdmin to Inspect Database

pgAdmin provides a web UI for exploring the PostgreSQL database.

Start pgAdmin

# Add tools profile to your compose command:
docker compose --profile core --profile tools up -d pgadmin

# Or start tools with everything:
docker compose --profile core --profile monitoring --profile tools up -d

Access pgAdmin

Add Server Connection

Right-click "Servers" → "Register" → "Server":

Example Queries

-- List all OAuth clients
SELECT client_id, client_name, client_type, grant_types
FROM idp.oauth_clients;

-- List all user accounts
SELECT sub, name, status, mfa_enabled
FROM idp.accounts;

-- Join client with extension config
SELECT c.client_id, c.client_name, e.config, e.metadata
FROM idp.oauth_clients c
LEFT JOIN idp.oauth_client_ext e ON c.id = e.client_id;

Alternative: psql CLI

# Interactive psql session
docker exec -it empowernow-db-1 psql -U postgres -d idp_db

# Inside psql:
\dt idp.*                    -- List all tables
\d idp.oauth_clients         -- Describe table
SELECT * FROM idp.oauth_clients LIMIT 5;
\q                           -- Quit

➕Adding New Clients & Users

New OAuth clients and users are added by editing the seed migration file.

Edit Seed Migration

Open IdP/migrations/versions_dev/0010_seed_clients_and_users.py

Confidential Client Template

# Add to CLIENTS dictionary:
"my-service-client": {
    "client_type": "confidential",
    "secret_hash": SECRET1_HASH,  # Hash of "secret1"
    "description": "My service description",
    "grant_types": ["client_credentials"],
    "scopes": ["openid", "profile"],
    "default_audience": "api://my-api",
    "token_endpoint_auth_method": "client_secret_post",
},

Public Client Template (SPA/Mobile)

"my-spa-client": {
    "client_type": "public",
    "description": "My SPA application",
    "grant_types": ["authorization_code", "refresh_token"],
    "scopes": ["openid", "profile", "email", "offline_access"],
    "redirect_uris": [
        "http://localhost:3000/callback",
        "https://myapp.example.com/callback"
    ],
    "post_logout_uris": ["http://localhost:3000"],
},

User Account Template

# Add to USERS dictionary:
"john.smith": {
    "name": "John Smith",
    "given_name": "John",
    "family_name": "Smith",
    "email": "john.smith@empowerid.com",
    "roles": ["user"],
    "password_hash": PASSWORD_HASH,  # Hash of "password"
},

Generate Password Hash

# Generate a new password hash:
python -c "
from passlib.hash import pbkdf2_sha256
hash = pbkdf2_sha256.using(rounds=600000).hash('your-password')
print(hash)
"

Apply Changes

# Reset and re-run migrations
docker exec empowernow-db-1 psql -U postgres -d idp_db \
    -c "DROP SCHEMA IF EXISTS idp CASCADE;"

docker compose -f docker-compose.yml -f docker-compose-build.yml \
    --profile core up idp-alembic --build

# Verify your new client/user
docker exec empowernow-db-1 psql -U postgres -d idp_db \
    -c "SELECT client_id FROM idp.oauth_clients WHERE client_id = 'my-service-client';"

🔬Hands-on Labs

curl -s https://idp.self.empowernow.ai/api/oidc/.well-known/openid-configuration | jq .

curl -s https://idp.self.empowernow.ai/api/oidc/.well-known/openid-configuration | jq -r '.token_endpoint'

curl -s https://idp.self.empowernow.ai/api/oidc/.well-known/openid-configuration | jq '.scopes_supported'

curl -s https://idp.self.empowernow.ai/api/oidc/.well-known/openid-configuration | jq '.grant_types_supported'

TOKEN_RESPONSE=$(curl -s -X POST https://idp.self.empowernow.ai/api/oidc/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=bff-client" \
  -d "client_secret=secret1" \
  -d "scope=openid profile")

echo $TOKEN_RESPONSE | jq .

ACCESS_TOKEN=$(echo $TOKEN_RESPONSE | jq -r '.access_token')
echo "Token: ${ACCESS_TOKEN:0:50}..."

# Split by dots
HEADER=$(echo $ACCESS_TOKEN | cut -d'.' -f1)
PAYLOAD=$(echo $ACCESS_TOKEN | cut -d'.' -f2)
SIGNATURE=$(echo $ACCESS_TOKEN | cut -d'.' -f3)

echo "Header:    ${HEADER:0:30}..."
echo "Payload:   ${PAYLOAD:0:30}..."
echo "Signature: ${SIGNATURE:0:30}..."

# Add padding and decode
echo $HEADER | tr '_-' '/+' | base64 -d 2>/dev/null | jq .

echo $PAYLOAD | tr '_-' '/+' | base64 -d 2>/dev/null | jq .

EXP=$(echo $PAYLOAD | tr '_-' '/+' | base64 -d 2>/dev/null | jq -r '.exp')
date -d @$EXP    # Linux
# On macOS: date -r $EXP

docker exec -it empowernow-db-1 psql -U postgres -d idp_db

\dt idp.*

\d idp.oauth_clients

SELECT client_id, client_type, grant_types 
FROM idp.oauth_clients;

SELECT client_id, client_type, scopes, token_endpoint_auth_method
FROM idp.oauth_clients 
WHERE client_id = 'bff-client';

SELECT c.client_id, e.config, e.metadata
FROM idp.oauth_clients c
LEFT JOIN idp.oauth_client_ext e ON c.id = e.client_id
WHERE c.client_id = 'bff-client';

SELECT sub, name, email, status 
FROM idp.accounts LIMIT 5;

\q

curl -s https://idp.self.empowernow.ai/api/oidc/.well-known/jwks.json | jq .

curl -s https://idp.self.empowernow.ai/api/oidc/.well-known/jwks.json | jq '.keys[].kid'

# If you still have $ACCESS_TOKEN from Lab 2:
TOKEN_KID=$(echo $ACCESS_TOKEN | cut -d'.' -f1 | tr '_-' '/+' | base64 -d 2>/dev/null | jq -r '.kid')
echo "Token kid: $TOKEN_KID"

curl -s https://idp.self.empowernow.ai/api/oidc/.well-known/jwks.json | \
  jq --arg kid "$TOKEN_KID" '.keys[] | select(.kid == $kid)'

🔧Troubleshooting: When Tokens Go Wrong

# Quick check: is the token expired?
echo $TOKEN | cut -d'.' -f2 | base64 -d 2>/dev/null | jq '.exp'
date +%s  # Compare with current timestamp

echo $TOKEN | cut -d'.' -f2 | base64 -d 2>/dev/null | jq '.scope'
# Output: "openid profile"
# Missing: "calendar:write" which the endpoint requires!

# Example: request with additional scope
curl -X POST $TOKEN_ENDPOINT \
  -d "grant_type=client_credentials" \
  -d "client_id=my-client" \
  -d "client_secret=secret" \
  -d "scope=openid profile calendar:write"  # Added calendar:write

# Get kid from a failing token
echo $FAILING_TOKEN | cut -d'.' -f1 | base64 -d 2>/dev/null | jq '.kid'
# Output: "key-2024-01"

# Check what keys are in JWKS
curl -s $JWKS_URI | jq '.keys[].kid'
# Output: "key-2024-02"  ← The old key is gone!

❓Knowledge Check

📝Day 6 Checkpoint

• Can explain the difference between OAuth2 and OIDC
• Know when to use each OAuth2 grant type
• Understand the purpose of Access, Refresh, and ID tokens
• Can decode a JWT and identify its claims
• Understand the IdP architecture components
• Understand why IdP uses Hot-Core + Extension tables
• Can reset the IdP database and run migrations
• Can inspect IdP data using pgAdmin or psql CLI
• Know how to add new OAuth clients and users