Day 01: Platform Overview & Architecture | EmpowerNow Developer Academy

🎯 Learning Objectives

By the end of today's session, you will be able to:

Articulate the EmpowerNow platform's mission and core value proposition
Identify all core services (BFF, IdP, PDP, Membership, CRUD, Workflow) and their responsibilities
Explain JWT token anatomy, OIDC authentication flows, and PKCE security
Understand identity federation with external IdPs and ARN-based addressing
Describe token exchange, OBO flows, and service-to-service authentication
Understand advanced security features: DPoP, CAEP, WebAuthn, Agent authentication
Map service dependencies and data flow through Kafka event-driven architecture
Explain the single-tenant deployment model and data isolation strategies

📚 Introduction to EmpowerNow

What is EmpowerNow?

EmpowerNow is a comprehensive Identity and Access Management (IAM) platform built on modern microservices architecture. It provides organizations with the tools to manage identities, authenticate users, authorize access, and govern permissions across their entire digital ecosystem.

💡

Why "EmpowerNow"?

The platform empowers organizations to implement fine-grained access control immediately, without waiting for complex integrations. It's designed for rapid deployment while maintaining enterprise-grade security.

Core Platform Principles

🔒 Zero-Trust Security

Never trust, always verify. Every request is authenticated and authorized regardless of origin.

🔌 Pluggable Architecture

Extend functionality through plugins without modifying core services.

📊 Policy-as-Code

Define access policies in YAML with version control and audit trails.

🌐 Standards-Based

Built on OAuth 2.0, OIDC, AuthZEN 1.1, and other industry standards.

🏗️ Architecture Overview

The EmpowerNow platform follows a layered microservices architecture where each service has a single responsibility. This separation of concerns enables independent scaling, deployment, and development.

EmpowerNow Platform Architecture

CLIENT LAYER

🌐

Web Browser

SPA / Plugins

📱

Mobile App

Native / PWA

⚙️

API Client

M2M / Service

GATEWAY LAYER

🚪

BFF Gateway

:8000 • api.self

SERVICE LAYER

🔐

IdP

:8002

⚖️

PDP

:8001

👥

Membership

:8003

📊

CRUD Service

:8005

DATA LAYER

🐘

PostgreSQL

:5432

🔴

Redis

:6379

🕸️

Neo4j

:7687

INFRASTRUCTURE

🔑

OpenBao

Secrets

📈

Prometheus

Metrics

📋

Loki

Logs

🔧 Core Services Deep Dive

Let's explore each core service in detail, understanding their responsibilities, technologies, and how they fit into the overall architecture.

1. BFF (Backend-for-Frontend) Gateway

🚪

BFF Service

Port 8000 • bff.self.empowernow.ai

The BFF is the central gateway and orchestration layer for the Experience App. It provides Plugin Management & Discovery (dynamic plugin loading, enforcement, telemetry), AI Builder & Chat (WebSocket-based AI streaming, LLM proxying), Dynamic Routing (YAML-driven routes with service proxying and token policies), and Background Workers (queue-based plugin builds and async processing).

Plugin Management AI Builder WebSocket Chat OAuth2/OIDC Dynamic Routing Session & CSRF Token Policies LLM Proxy

💜

Why BFF Pattern?

The BFF pattern allows us to optimize API responses for specific client needs, handle authentication in one place, and provide a stable API contract even as backend services evolve. It's the only service exposed publicly.

Key BFF Responsibilities:

Authentication Proxy: Handles OAuth2 flows with the IdP, managing tokens securely
Session Management: Stores sessions in Redis with secure cookies
Dynamic Routing: Routes requests to appropriate backend services
Plugin Delivery: Serves and manages the Experience Platform plugins
LLM Proxy: Provides authorized access to AI services (OpenAI, Anthropic)

2. IdP (Identity Provider)

🔐

IdP Service

Port 8002 • idp.self.empowernow.ai

The IdP is a fully compliant OpenID Connect Provider that handles all authentication concerns. It issues JWTs, manages user identities, supports multiple authentication methods, and provides CAEP for continuous access evaluation.

OIDC Provider JWT Tokens Token Exchange DPoP Support CAEP

OIDC Discovery

# OIDC Discovery Endpoint
GET https://idp.self.empowernow.ai/.well-known/openid-configuration

# Key endpoints exposed:
{
  "issuer": "https://idp.self.empowernow.ai",
  "authorization_endpoint": "/authorize",
  "token_endpoint": "/token",
  "userinfo_endpoint": "/userinfo",
  "introspection_endpoint": "/introspect",
  "jwks_uri": "/.well-known/jwks.json"
}
                

🧪 Try It: Fetch OIDC Discovery Document

Copy curl and run in your terminal to fetch the live OIDC configuration from your running IdP service.

IdP Token Types:

Access Tokens: Short-lived JWTs for API authorization (default: 1 hour)
Refresh Tokens: Long-lived tokens for obtaining new access tokens
ID Tokens: User identity information for clients
PAT (Personal Access Tokens): User-generated tokens for API access

🧪 Try It: Get Access Token (Client Credentials)

Service-to-service authentication using client credentials grant. This is how backend services authenticate.

🔬

Deep Dive: JWT Token Anatomy

Every JWT (JSON Web Token) issued by the IdP consists of three Base64URL-encoded parts separated by dots:

🔴 Header (Algorithm & Token Type)

Specifies the signing algorithm and token type. Never contains sensitive data.

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

🟣 Payload (Claims)

Contains the claims - statements about the user and token metadata.

{
  "iss": "https://idp.self.empowernow.ai",   // Issuer
  "sub": "user_abc123",                          // Subject (user ID)
  "aud": "api://empowernow",                     // Audience
  "exp": 1736779200,                             // Expiration (Unix timestamp)
  "iat": 1736775600,                             // Issued at
  "nbf": 1736775600,                             // Not valid before
  "scope": "openid profile api.read",            // Granted scopes
  "client_id": "spa-client",                     // Client that requested token
  "tenant_id": "acme-corp"                       // Multi-tenant identifier
}

🔵 Signature (Verification)

Cryptographic signature ensuring the token hasn't been tampered with.

RSASHA256(
  base64UrlEncode(header) + "." + base64UrlEncode(payload),
  privateKey
)

// Verified using the public key from: /.well-known/jwks.json

💡

Why RS256?

EmpowerNow uses RS256 (RSA + SHA-256) instead of HS256 because it uses asymmetric cryptography. The IdP signs with a private key, and any service can verify using the public key from JWKS - no shared secrets needed!

OpenID Connect Authentication Flow

Authorization Code Flow with PKCE

sequenceDiagram autonumber participant U as 👤 User Browser participant B as 🚪 BFF participant I as 🔐 IdP participant R as 🔴 Redis Note over U,R: 1. User Initiates Login U->>B: GET /auth/login B->>B: Generate code_verifier & code_challenge (PKCE) B->>R: Store code_verifier in session B-->>U: 302 Redirect to IdP /authorize Note over U,R: 2. User Authenticates at IdP U->>I: GET /authorize?client_id=bff&code_challenge=... I->>I: Show login form U->>I: POST credentials I->>I: Validate credentials I-->>U: 302 Redirect to BFF /callback?code=AUTH_CODE Note over U,R: 3. BFF Exchanges Code for Tokens U->>B: GET /callback?code=AUTH_CODE B->>R: Retrieve code_verifier B->>I: POST /token (code + code_verifier) I->>I: Verify PKCE, validate code I-->>B: {access_token, refresh_token, id_token} B->>R: Store tokens in session B-->>U: 302 Redirect to app + Set-Cookie: session_id Note over U,R: 4. User Accesses Protected Resource U->>B: GET /api/resource (Cookie: session_id) B->>R: Get tokens from session B->>B: Attach Authorization: Bearer token B->>B: Proxy to backend service

🔒

Why PKCE?

PKCE (Proof Key for Code Exchange) prevents authorization code interception attacks. Even if an attacker captures the auth code, they can't exchange it without the original code_verifier that only the BFF knows.

🌐

Deep Dive: Identity Federation

EmpowerNow supports identity federation - users can authenticate with external Identity Providers (Azure AD, Okta, Google) and access EmpowerNow without creating a local account.

Federation Flow with External IdP

sequenceDiagram participant U as 👤 User participant E as 🏢 External IdP (Okta/Azure AD) participant I as 🔐 EmpowerNow IdP participant P as ⚖️ PDP U->>I: Login with Okta I-->>U: Redirect to Okta U->>E: Authenticate E-->>U: External Token U->>I: Token callback I->>I: Validate external token I->>I: Map to ARN: auth:account:okta:user123 I-->>U: EmpowerNow Token (sub=ARN) U->>P: Access resource P->>P: Evaluate policies against ARN P-->>U: PERMIT/DENY

ARN (Authentication Resource Names)

Every identity in EmpowerNow has a unique ARN - a standardized identifier format:

ARN Format

auth:{entity_type}:{provider}:{subject}

# Examples:
auth:account:empowernow:alice          # Local user
auth:account:okta:00u123abc            # Okta federated user  
auth:account:entra.tenant1:bob@corp.com # Azure AD user
auth:identity:google:12345             # Google identity
auth:agent:acme-corp:invoice-bot       # AI Agent
                    

💡

No Local Account Required!

Federated users can access the system WITHOUT any entry in the local users table. The only requirement is that PDP policies exist to authorize access for their ARN pattern.

🔄

Deep Dive: Token Exchange & On-Behalf-Of (OBO)

When Service A needs to call Service B on behalf of a user, it uses RFC 8693 Token Exchange. This is critical for maintaining the security chain in microservices.

Token Exchange Flow (Service-to-Service)

sequenceDiagram participant U as 👤 User participant A as 📦 Service A participant I as 🔐 IdP participant B as 📦 Service B Note over U,B: User's original token has audience: Service A U->>A: Request + Token (aud=service-a) A->>A: Need to call Service B A->>I: POST /token (grant_type=token_exchange) Note right of A: subject_token=user's token, audience=service-b, scope=service-b:read I->>I: Validate original token I->>I: Check if A can request tokens for B I-->>A: New Token (aud=service-b, act={A}) A->>B: Request + New Token B->>B: Validate: aud=service-b ✓ B->>B: Log: User via Service A B-->>A: Response A-->>U: Response

Token Exchange Grant Types:

Grant Type	Use Case	Actor Claim
`urn:ietf:params:oauth:grant-type:token-exchange`	Service-to-service with user context	`"act": {"sub": "service-a"}`
`client_credentials`	Service-to-service without user	No actor, service is subject
`delegation`	User delegates to another user/agent	`"act": {"sub": "delegate-arn"}`

🛡️

Advanced IdP Security Features

🔑 DPoP (Demonstrating Proof of Possession)

Binds tokens to a specific client by requiring a cryptographic proof. Even if a token is stolen, it can't be used without the client's private key.

Token Binding Theft Prevention

📡 CAEP (Continuous Access Evaluation)

Real-time session revocation. When a user's status changes (fired, compromised), all their active sessions are immediately invalidated.

Real-time Revocation SSE Events

🔐 WebAuthn / Passkeys

Passwordless authentication using biometrics or hardware keys. More secure than passwords and resistant to phishing.

FIDO2 Biometrics

🤖 Agent Authentication (A2A)

AI agents register as OAuth clients with capability-scoped permissions. Agents can act on behalf of users with explicit delegation.

DCR Capability Scopes

3. PDP (Policy Decision Point)

⚖️

PDP Service

Port 8001 • pdp.self.empowernow.ai

The PDP evaluates authorization requests against policies using the AuthZEN 1.1 specification. It provides fine-grained access control with support for ABAC, RBAC, and relationship-based access control patterns.

AuthZEN 1.1 YAML Policies PIPs Neo4j Integration Caching

Policy Hierarchy (5 Levels):

Global: Platform-wide defaults
Tenant: Organization-specific policies
Application: App-scoped rules
Resource Type: Entity-level permissions
Resource Instance: Individual resource access

PDP Authorization Decision Flow

flowchart TD A[📨 Evaluation Request] --> B{Token Valid?} B -->|No| C[❌ DENY - Invalid Token] B -->|Yes| D[Extract Subject Claims] D --> E[Load Policies by Hierarchy] E --> F{Global Policy?} F -->|DENY| G[❌ DENY - Global Block] F -->|PERMIT/No Match| H{Tenant Policy?} H -->|DENY| I[❌ DENY - Tenant Block] H -->|PERMIT/No Match| J{App Policy?} J -->|DENY| K[❌ DENY - App Block] J -->|PERMIT/No Match| L{Resource Type Policy?} L -->|DENY| M[❌ DENY - Type Block] L -->|PERMIT/No Match| N{Resource Instance?} N -->|DENY| O[❌ DENY - Instance Block] N -->|PERMIT| P[✅ PERMIT] N -->|No Match| Q{Default Policy} Q -->|DENY| R[❌ DENY - Default] Q -->|PERMIT| P style A fill:#3b82f6,color:#fff style P fill:#10b981,color:#fff style C fill:#f43f5e,color:#fff style G fill:#f43f5e,color:#fff style I fill:#f43f5e,color:#fff style K fill:#f43f5e,color:#fff style M fill:#f43f5e,color:#fff style O fill:#f43f5e,color:#fff style R fill:#f43f5e,color:#fff

🔬

Deep Dive: Policy Information Points (PIPs)

PIPs fetch additional context data that policies need but isn't in the request. They extend the PDP's decision-making capabilities.

PIP Type	Data Source	Example Use Case
Membership PIP	Neo4j Graph	Fetch user's roles, group memberships, manager chain
Resource PIP	CRUD Service	Get resource owner, classification, sensitivity level
Time PIP	System Clock	Check if within business hours, maintenance window
Risk PIP	External Service	Get user's risk score, device trust level

AuthZEN Evaluation Request

POST /access/v1/evaluation
Content-Type: application/json

{
  "subject": {
    "type": "user",
    "id": "user_123",
    "properties": {
      "department": "engineering"
    }
  },
  "action": {
    "name": "read"
  },
  "resource": {
    "type": "document",
    "id": "doc_456"
  },
  "context": {
    "ip_address": "10.0.0.1",
    "time": "2026-01-13T10:00:00Z"
  }
}
                

🧪 Try It: Authorization Evaluation

Test a real authorization decision. Can user "alice" read a document? The PDP will evaluate policies and return PERMIT or DENY.

4. Membership Service

👥

Membership Service

Port 8003 • membership.self.empowernow.ai

Manages organizational structure, role hierarchies, and user-role assignments using a graph database. It supports complex relationship models, vector search capabilities, and hierarchical role inheritance.

Neo4j Graph Role Hierarchies Vector Search Location-Based

5. IdP UI (Identity Provider Interface)

🖥️

IdP UI

Port 80 • authn.self.empowernow.ai

React-based administrative interface for managing the Identity Provider. Provides user management, client configuration, OIDC testing tools, and real-time monitoring dashboards.

React TypeScript Admin Portal Real-time

6. CRUD Service (Data Operations)

📊

CRUD Service

Port 8005 • crud.self.empowernow.ai

Generic data operations service providing Create, Read, Update, Delete operations for all entities. Handles schema validation, tenant isolation, and emits events for all data changes.

REST API Schema Validation Tenant Isolation Event Emission

CRUD Service Responsibilities:

Entity Management: Generic CRUD operations for users, roles, applications, resources
Schema Enforcement: Validates data against JSON schemas before persistence
Audit Trail: Every operation is logged with who, what, when, and from where
Event Publishing: Emits Kafka events for all mutations (created, updated, deleted)

CRUD API Example

# Create a new application
POST /api/v1/applications
Content-Type: application/json
Authorization: Bearer {token}

{
  "name": "Finance Dashboard",
  "description": "Executive financial reporting",
  "owner_arn": "auth:account:empowernow:alice",
  "classification": "confidential"
}

# Response includes tenant-scoped ID
{
  "id": "app_7k2m9n4p",
  "tenant_id": "acme-corp",
  "created_at": "2026-01-13T10:00:00Z",
  ...
}
                

🏗️ Infrastructure Services

These services form the backbone of the platform, handling networking, messaging, and secrets:

🔀

Traefik

Ports 80, 443

Cloud-native reverse proxy and load balancer. Handles TLS termination, routing, and automatic service discovery via Docker labels.

TLS Termination Auto Discovery Load Balancing

📨

Kafka

Port 9092

Distributed event streaming platform. Enables async communication between services, event sourcing, and real-time data pipelines.

Event Bus Pub/Sub Audit Events

🔐

OpenBao (Vault)

Port 8200

Secrets management and encryption service. Stores API keys, database credentials, and signing keys with automatic rotation.

Secret Storage Key Rotation Encryption

Event-Driven Architecture with Kafka

flowchart LR subgraph Producers ["Event Producers"] IdP[🔐 IdP] CRUD[📊 CRUD] PDP[⚖️ PDP] end subgraph Kafka ["📨 Kafka Topics"] T1[auth.login.success] T2[entity.created] T3[access.denied] end subgraph Consumers ["Event Consumers"] Audit[📋 Audit Service] Analytics[📈 Analytics] Notify[🔔 Notifications] end IdP -->|login event| T1 CRUD -->|mutation event| T2 PDP -->|decision event| T3 T1 --> Audit T1 --> Analytics T2 --> Audit T2 --> Notify T3 --> Audit T3 --> Analytics style Kafka fill:#10b981,color:#fff

🚀 Advanced Services

These services provide advanced capabilities for workflow automation and AI orchestration:

⚙️

Workflow / Automate

automate.self.empowernow.ai

Visual workflow designer for building approval chains, provisioning flows, and automated business processes. Drag-and-drop interface with conditional logic.

Visual Designer Approval Chains Provisioning Scheduling

🤖

Agent Studio

agentstudio.self.empowernow.ai

Visual designer for creating and configuring AI agents. Define agent capabilities, tool access, and delegation relationships.

Agent Design Tool Config Testing

🤖

AI-First Platform

EmpowerNow is designed as an AI-first platform. Agents are first-class citizens with their own identities (ARNs), authentication mechanisms, and fine-grained permissions. Agent Studio enables organizations to safely deploy AI agents that can act on behalf of users.

Service Dependencies Map

How Services Depend on Each Other

flowchart TB subgraph External ["🌐 External"] Browser[Browser/Client] end subgraph Gateway ["Gateway Layer"] Traefik[🔀 Traefik] BFF[🚪 BFF] end subgraph Identity ["Identity & Auth"] IdP[🔐 IdP] PDP[⚖️ PDP] end subgraph Services ["Application Services"] Membership[👥 Membership] CRUD[📊 CRUD] Workflow[⚙️ Workflow] end subgraph Data ["Data Stores"] Postgres[(🐘 Postgres)] Redis[(🔴 Redis)] Neo4j[(🕸️ Neo4j)] Kafka[📨 Kafka] end subgraph Infra ["Infrastructure"] OpenBao[🔐 OpenBao] end Browser --> Traefik Traefik --> BFF BFF --> IdP BFF --> PDP BFF --> CRUD BFF --> Workflow IdP --> Postgres IdP --> Redis IdP --> OpenBao PDP --> Neo4j PDP --> Membership PDP --> Redis Membership --> Neo4j CRUD --> Postgres CRUD --> Kafka Workflow --> CRUD Workflow --> Kafka style Browser fill:#3b82f6,color:#fff style BFF fill:#00d9ff,color:#000 style IdP fill:#a855f7,color:#fff style PDP fill:#10b981,color:#fff

🛡️ Zero-Trust Security Model

EmpowerNow implements a comprehensive zero-trust architecture where every request is treated as potentially hostile until verified. This model is fundamental to how all services interact.

Request Authentication Flow

Request Arrives at BFF

All external requests enter through the BFF gateway. The BFF checks for valid session cookies or Bearer tokens.

Token Validation with IdP

The BFF sends the token to IdP for validation via introspection. IdP verifies signature, expiration, and revocation status.

Authorization Check with PDP

For protected resources, BFF sends an evaluation request to PDP with subject, action, and resource context.

PDP Policy Evaluation

PDP evaluates policies, potentially fetching additional attributes from PIPs (Membership, custom sources).

Decision Returned

PDP returns PERMIT, DENY, or INDETERMINATE with optional obligations and advice for the calling service.

Request Fulfilled or Rejected

Based on the decision, BFF either proxies the request to the target service or returns a 403 Forbidden response.

⚠️

Important: Internal Service Communication

Even internal service-to-service communication uses token-based authentication. Services use the On-Behalf-Of (OBO) flow or client credentials for inter-service calls, never bypassing security checks.

🛡️

Preview: ARIA Shield Seven Controls

EmpowerNow's security is governed by the ARIA Shield framework with seven controls: Authentication, Authorization, Attestation, Audit, Anomaly Detection, Accountability, and Archive. Every sensitive operation generates a tamper-evident receipt with hash chains for integrity. You'll explore this in depth in Week 5, Day 25.

💾 Data Layer

EmpowerNow uses a polyglot persistence strategy, choosing the right database for each use case:

🐘

PostgreSQL

Port 5432

Primary relational database for structured data. Stores user accounts, client configurations, audit logs, and transactional data. Uses schema-per-tenant isolation.

IdP Data Audit Logs Clients

🔴

Redis

Port 6379

High-performance caching and session storage. Handles session data, policy cache, rate limiting counters, and real-time pub/sub for notifications.

Sessions Cache Pub/Sub

🕸️

Neo4j

Port 7687

Graph database for relationship-heavy data. Powers the Membership service's role hierarchies, organizational structures, and complex permission queries.

Roles Hierarchies Relationships

🔌 Plugin Architecture

EmpowerNow uses a micro-frontend architecture where the Experience platform hosts dynamically loaded plugins. Each plugin is a self-contained React application with its own routes, state, and API calls.

Plugin Loading Architecture

Plugin Types in EmpowerNow:

🛒

IT Shop

Request & Provision Access

Self-service portal for requesting application access, roles, and entitlements with approval workflows.

👤

My Identity

Profile Management

View and manage personal profile, delegations, and access certifications.

✅

Access Reviews

Certification Campaigns

Periodic access certification for compliance and governance requirements.

Plugin Manifest Example

{
  "name": "@empowernow/it-shop",
  "version": "1.2.0",
  "type": "experience-plugin",
  "entry": "dist/index.esm.js",
  "routes": [
    { "path": "/shop", "component": "ShopPage" },
    { "path": "/shop/cart", "component": "CartPage" },
    { "path": "/shop/requests", "component": "RequestsPage" }
  ],
  "permissions": ["itshop.view", "itshop.request"],
  "navigation": {
    "label": "IT Shop",
    "icon": "ShoppingCart",
    "order": 1
  }
}
                

🏢 Deployment Architecture

EmpowerNow uses a single-tenant deployment model - each customer receives their own complete, isolated stack deployed either on-premises or in the cloud. This provides maximum security, customization flexibility, and data sovereignty.

Single-Tenant Deployment Model

flowchart TB subgraph Customer1 ["🏢 Customer A (On-Prem)"] direction TB A1[Complete EmpowerNow Stack] A2[(PostgreSQL)] A3[(Neo4j)] A4[(Redis)] A1 --> A2 A1 --> A3 A1 --> A4 end subgraph Customer2 ["☁️ Customer B (AWS)"] direction TB B1[Complete EmpowerNow Stack] B2[(PostgreSQL)] B3[(Neo4j)] B4[(Redis)] B1 --> B2 B1 --> B3 B1 --> B4 end subgraph Customer3 ["☁️ Customer C (Azure)"] direction TB C1[Complete EmpowerNow Stack] C2[(PostgreSQL)] C3[(Neo4j)] C4[(Redis)] C1 --> C2 C1 --> C3 C1 --> C4 end style A1 fill:#3b82f6,color:#fff style B1 fill:#10b981,color:#fff style C1 fill:#a855f7,color:#fff

Why Single-Tenant Deployment?

Benefit	Description
🔒 Complete Isolation	Each customer's data is physically separated - no shared databases, no shared infrastructure, zero risk of cross-customer data leakage.
📍 Data Sovereignty	Customers choose where their data resides: on-premises data centers, specific cloud regions, or air-gapped environments.
⚙️ Customization	Each deployment can be configured, scaled, and upgraded independently based on customer needs.
🛡️ Security Compliance	Easier compliance with regulations (GDPR, HIPAA, SOC2) when infrastructure is dedicated per customer.
🚀 Performance	No "noisy neighbor" issues - each customer gets dedicated resources without contention.

Deployment Options:

🏠

On-Premises

Deploy in customer's own data center with Docker Compose or Kubernetes. Full control over infrastructure, networking, and security policies.

☁️

Cloud (AWS/Azure/GCP)

Managed cloud deployment in customer's cloud account. Uses cloud-native services (RDS, managed Redis) with Kubernetes orchestration.

🔐

Air-Gapped

Fully isolated deployment with no internet connectivity. Ideal for government, defense, and high-security environments.

💡

Deployment Flexibility

The same Docker images and configurations work across all deployment models. ServiceConfigs contains environment-specific overrides for each deployment scenario.

🌐 Service Domains

Each service has a dedicated domain for external access and internal Docker networking:

Host Configuration

# Add to your hosts file (Windows: C:\Windows\System32\drivers\etc\hosts; macOS/Linux: /etc/hosts)
0.0.1    bff.self.empowernow.ai        # BFF Gateway
0.0.1    idp.self.empowernow.ai        # Identity Provider
0.0.1    pdp.self.empowernow.ai        # Policy Decision Point
0.0.1    membership.self.empowernow.ai # Membership Service
0.0.1    authn.self.empowernow.ai      # IdP UI
                

🔄 Complete Request Lifecycle

Let's trace a complete request through the entire system to see how all components work together. This example shows a user accessing a protected document.

End-to-End Request Flow: Accessing a Protected Document

sequenceDiagram autonumber participant U as 👤 User participant B as 🚪 BFF participant R as 🔴 Redis participant I as 🔐 IdP participant P as ⚖️ PDP participant M as 👥 Membership participant C as 📊 CRUD participant D as 🐘 Postgres Note over U,D: Phase 1: Request Reception & Session Validation U->>B: GET /api/documents/456 B->>R: Get session (session_id cookie) R-->>B: {access_token, refresh_token, user_id} Note over U,D: Phase 2: Token Validation B->>I: POST /introspect (access_token) I->>I: Verify signature (JWKS) I->>I: Check expiration & revocation I-->>B: {active: true, sub: "alice", tenant_id: "acme"} Note over U,D: Phase 3: Authorization Decision B->>P: POST /access/v1/evaluation Note right of B: subject: alice
action: read
resource: document/456 P->>M: GET /api/users/alice/roles M-->>P: ["editor", "reviewer"] P->>P: Load policies (Global→Tenant→App→Type→Instance) P->>P: Evaluate: editor CAN read documents P-->>B: {decision: "PERMIT"} Note over U,D: Phase 4: Resource Retrieval B->>C: GET /api/documents/456 (Authorization: Bearer token) C->>C: Extract tenant_id from token C->>D: SELECT * FROM acme.documents WHERE id=456 D-->>C: {id: 456, title: "Q4 Report", ...} C-->>B: 200 OK + document data Note over U,D: Phase 5: Response to User B-->>U: 200 OK + document JSON

What Happens If Authorization Fails?

Authorization Denied Flow

sequenceDiagram participant U as 👤 User (Bob) participant B as 🚪 BFF participant P as ⚖️ PDP participant M as 👥 Membership U->>B: GET /api/documents/456 (confidential HR doc) B->>P: Can bob READ document/456? P->>M: Get bob's roles M-->>P: ["intern"] P->>P: Load resource: document/456 has classification=confidential P->>P: Policy: interns CANNOT read confidential docs P-->>B: {decision: "DENY", reason: "insufficient_clearance"} B-->>U: 403 Forbidden + error details

Timeline of a Typical Request

0ms - Request Arrives

BFF receives HTTP request, extracts session cookie

1-2ms - Session Lookup

Redis returns cached session with tokens (sub-millisecond with local Redis)

3-5ms - Token Introspection

IdP validates token signature and claims (cached JWKS, no DB hit)

5-15ms - Authorization Decision

PDP evaluates policies, potentially calling Membership PIP for roles

15-50ms - Resource Retrieval

Backend service queries database with tenant isolation

50-100ms - Total Response

Full end-to-end latency including network overhead

⚡

Performance Optimization

EmpowerNow uses aggressive caching: JWKS cached for hours, PDP policies cached in Redis, session data kept in Redis. Most requests complete authorization in under 10ms after initial warm-up.

📝 Knowledge Check

Which service is responsible for evaluating authorization decisions?

IdP (Identity Provider)

BFF (Backend-for-Frontend)

PDP (Policy Decision Point)

Membership Service

Which database is used for storing role hierarchies and organizational relationships?

PostgreSQL

Redis

Neo4j

MongoDB

🛠️ Hands-on Exercises

Exercise 1: Decode a JWT Token

Use the sample JWT below to understand token structure. You can decode it at jwt.io:

Sample JWT

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImtleS0yMDI0In0.eyJpc3MiOiJodHRwczovL2lkcC5vY2cubGFicy5lbXBvd2Vybm93LmFpIiwic3ViIjoidXNlcl9hYmMxMjMiLCJhdWQiOiJhcGk6Ly9lbXBvd2Vybm93IiwiZXhwIjoxNzM2Nzc5MjAwLCJpYXQiOjE3MzY3NzU2MDAsInNjb3BlIjoib3BlbmlkIHByb2ZpbGUgYXBpLnJlYWQiLCJjbGllbnRfaWQiOiJzcGEtY2xpZW50IiwidGVuYW50X2lkIjoiYWNtZS1jb3JwIn0.signature_here
                

Questions to answer:

What algorithm is used for signing? (Check the header)
What is the token's audience (aud)?
What scopes were granted?
How long is this token valid for? (Calculate from iat and exp)

Exercise 2: Complete the Service Responsibility Matrix

Fill in the missing cells in this matrix based on what you learned:

Service	Primary Question It Answers	Primary Database	Key Endpoints
BFF	"How do I access the platform?"	Redis (sessions)	`/auth/login`, `/api/*`
IdP	"Who is this user?"	PostgreSQL	`/token`, `/authorize`, `/userinfo`
PDP	??? (Fill this in)	??? (Fill this in)	`/access/v1/evaluation`
Membership	??? (Fill this in)	Neo4j	`/api/roles`, `/api/members`

💡 Show Answers ▼

PDP: "Is this user allowed to do this action?" | Neo4j + Redis (cache)

Membership: "What roles/groups does this user belong to?" | Neo4j

Exercise 3: Trace a Request Through the System

Given this scenario, identify which services are involved and in what order:

📝

Scenario

Alice (a manager) wants to approve Bob's access request to the Finance Reports dashboard. She clicks "Approve" in the IT Shop plugin.

Trace the flow:

Which service receives the initial HTTP request?
How does the system verify Alice is logged in?
How does the system check if Alice CAN approve requests?
What information does PDP need about Alice to make this decision?
Where does PDP get Alice's "manager" role from?

💡 Show Answer Flow ▼

sequenceDiagram participant A as 👤 Alice participant B as 🚪 BFF participant I as 🔐 IdP participant P as ⚖️ PDP participant M as 👥 Membership participant C as 📊 CRUD A->>B: POST /api/requests/123/approve B->>B: Extract session token B->>I: Validate token (introspection) I-->>B: Token valid, user=alice B->>P: Can alice APPROVE request/123? P->>M: Get alice's roles M-->>P: roles=[manager, employee] P->>P: Evaluate policies P-->>B: PERMIT (manager can approve) B->>C: Update request status C-->>B: Success B-->>A: 200 OK - Approved!

Exercise 4: Knowledge Application Quiz

Test your understanding with these scenario-based questions:

📋 Day 1 Summary

✅

Excellent Progress!

You've completed a comprehensive overview of the EmpowerNow platform. You now understand the architecture from user request to database response, including authentication flows, authorization decisions, and the single-tenant deployment model.

Key Takeaways:

BFF Gateway - Single entry point handling auth flows, session management, and API proxying
IdP (Identity Provider) - OIDC-compliant authentication, issues JWTs with RS256 signatures
PDP (Policy Decision Point) - AuthZEN 1.1 authorization with 5-level policy hierarchy
Membership Service - Graph-based role and relationship management in Neo4j
CRUD Service - Generic data operations with tenant isolation and event emission
JWT Anatomy - Three parts: Header (algorithm), Payload (claims), Signature (verification)
PKCE Flow - Secure OAuth2 authorization code exchange preventing interception attacks
Federation & ARNs - External IdP integration with universal identity addressing
Token Exchange (RFC 8693) - Service-to-service authentication with user context
OBO (On-Behalf-Of) - Acting as another user while maintaining audit trail
DPoP & CAEP - Token binding and continuous access evaluation for advanced security
Infrastructure - Traefik (routing), Kafka (events), OpenBao (secrets)
Workflow - Business process automation and approval chains
PIPs - Policy Information Points fetch external data for authorization decisions
Plugin Architecture - Micro-frontends loaded dynamically into Experience shell
Multi-Tenancy - Schema-per-tenant (Postgres), label isolation (Neo4j), key prefix (Redis)
Zero-Trust - Every request authenticated and authorized, including internal service calls

Concepts You Can Now Explain:

🔐 Authentication vs Authorization

IdP answers "who are you?" while PDP answers "what can you do?"

🔑 Token-Based Security

JWTs carry claims, signed cryptographically, verified without calling IdP every time

📊 Polyglot Persistence

Right database for right job: Postgres for transactions, Neo4j for graphs, Redis for cache

Prepare for Tomorrow:

Tomorrow you'll set up your development environment. Make sure you have:

Docker Desktop installed and running
Git configured with SSH keys
Access to the EmpowerNow Azure DevOps repositories
VS Code or Cursor IDE ready