🌐 Language: English Version | 中文版
TL;DR
This article presents a production-grade identity governance architecture that bridges upstream Identity Providers with internal business systems through a protocol-agnostic identity relay layer. Key highlights:
- Clean separation of concerns: Upstream IdP handles identity assertion, internal IAM handles access control and profile distribution
- Identity relay pattern: OIDC federation with standardized JWT issuance and gateway-based header injection
- SID-based session management: Embedding Session IDs in stateless JWTs for instant revocation and global logout
- Permission versioning: Minute-level propagation of access policy changes through version consistency checks
1. Background & Challenges
In enterprise environments with multiple business systems running in parallel (OA, CRM, Project Management, Finance, etc.), centralized identity governance is critical to solving data silos. Common challenges include:
- Scattered access control logic: Each business system implements access control independently, leading to multi-point refactoring when policies change
- Inconsistent identity identifiers: Different services use conflicting identification rules (Email, Subject ID) for the same user
- Duplicated attribute management: Organization architecture exists in multiple copies without a single source of truth
Mature identity sources (Upstream IdP) primarily handle identity authenticity assertions. This architecture builds an identity relay layer based on standard OAuth2/OIDC protocols to achieve unified access decisions and identity profile aggregation across systems.
2. Logical Architecture Design
Core principle: Upstream Identity Provider is responsible for identity authenticity, while internal identity system handles access decisions and attribute distribution.
2.1 Architecture Overview
graph TB
subgraph U["User Layer"]
EU["Enterprise Employee"]
AD["System Admin"]
end
subgraph A["External Identity Source (Upstream IdP)"]
IDP["OIDC Provider"]
end
subgraph I["Identity Governance Layer (Internal IAM)"]
IAS["Identity Access Service (IAS) - Access Decision Engine + Session Management"]
IMA["Identity Management API (IMA) - Read/Write Management Backend"]
IDS["Identity Data Service (IDS) - Identity Profile Query (Read-Only)"]
ISJ["Identity Sync Job (ISJ) - Mirror Data Sync"]
end
subgraph G["API Gateway Layer"]
GW["API Gateway - Identity Pass-through + Unified Authentication"]
end
subgraph B["Business System Layer"]
APP1["Business System A"]
APP2["Business System B"]
APP3["Business System C"]
end
EU -->|OIDC SSO| IDP
EU -.->|OIDC SSO| IAS
IDP -->|OIDC Federation| IAS
AD -->|Email/Password| IAS
IAS -->|Issue Internal Standard JWT| GW
GW -->|Header Injection X-User-Id| APP1
GW -->|Header Injection| APP2
GW -->|Header Injection| APP3
APP1 -->|Query User Profile| IDS
APP2 -->|Query User Profile| IDS
APP3 -->|Query User Profile| IDS
IMA -.->|Config Distribution| IAS
ISJ -->|Incremental Sync| IDP
2.2 Interaction Flow Analysis (Identity Flows)
A. Federated Login Flow (OIDC Federation)
This flow implements identity relay based on standard OAuth2 protocol, supporting seamless integration with any standard OIDC Provider:
sequenceDiagram
participant Browser as User Browser
participant GW as API Gateway
participant IAS as Identity Access Service (IAS)
participant IdP as Upstream IdP
Browser->>GW: Access Restricted System URL
GW->>IAS: Forward-Auth (JWT Validation)
IAS-->>GW: Unauthenticated (302 Redirect)
GW-->>Browser: 302 → Redirect to Login Page
Browser->>IAS: Select "Enterprise Account Login"
IAS-->>Browser: 302 → Redirect to Upstream IdP
Browser->>IdP: Submit Identity Assertion (MFA/SSO)
IdP-->>Browser: Callback IAS (Authorization Code)
Browser->>IAS: /oauth2/callback?code=xxxx
IAS->>IdP: Exchange Code for Token & UserInfo
IAS->>IAS: Internal Identity Aggregation (Ext ID → UID)
IAS->>IAS: Create Session (SID)
IAS-->>Browser: Issue Internal JWT (with UID, SID) + Set Auth Cookie
Browser->>GW: Re-access with JWT
GW->>IAS: Forward-Auth Decision Passed
GW->>Browser: Forward to Downstream Business System
B. Transparent Authentication & Access Flow (Decision Engine)
The gateway layer performs real-time fine-grained control through the access decision engine:
sequenceDiagram
participant Browser as User Browser
participant GW as API Gateway
participant IAS as Identity Access Service (IAS)
participant Backend as Business System
Browser->>GW: Access Business API with JWT
GW->>IAS: Forward-Auth Call
IAS->>IAS: 1. JWT Signature Validation
IAS->>IAS: 2. Permission Version Validation (Permission Consistency)
IAS->>IAS: 3. Active Session Validation (Check SID in Cache)
IAS->>IAS: 4. Application-level Access Decision (Access Level Check)
alt Access Granted
IAS-->>GW: 200 OK + Header (X-User-Id, X-Sid)
GW->>Backend: Map Identity Context to Request
Backend-->>Browser: Return Data
else Access Denied
IAS-->>GW: 403 Forbidden
GW-->>Browser: 403 Forbidden
end
3. Key Design Decisions (Rationale)
3.1 Decoupling Boundary: Access Control vs. Business Permissions
- Access Control: Determined by the identity system — whether this user has permission to enter this application
- Feature Permission: Determined internally by the application using attributes provided by IAM
Decision rationale: In this architecture design, the identity system serves as an Attribute Provider, while business systems remain Rule Definers, preventing the central identity system from over-penetrating business details.
3.2 Technology Selection: Protocol Neutrality
The architecture chooses Spring Authorization Server to build the IAS core:
- Advantage: Its pure OAuth2 implementation supports abstracting any third-party Identity Provider as an “identity source”
- Comparison: Compared to Keycloak, it provides more flexible API-level extensions for inserting custom “access decision chains”
3.3 Balance Between Stateless and Stateful (SID Design)
To support “instant permission revocation” and “global logout”:
- Design point: Embed Session ID (SID) in JWT, maintained by backend Redis cluster
- Decision rationale: OAuth2 protocol itself doesn’t include session invalidation semantics. The SID mechanism supplements real-time session logout capability to meet enterprise-level management precision requirements
3.4 Instant Permission Effect: Version Consistency Validation
To achieve “minute-level response” to changes:
- User-permission mapping holds
permission_version - Gateway access performs version matching validation
- Once administrators modify access policies, the version number increments, causing all active tokens to immediately fail and triggering re-authentication logic
4. Identity Aggregation: UID-Driven Unified Profile
The architecture converts heterogeneous account identifiers to globally unique UID through “identity federation mapping”:
1 | ┌──────────────────────────────────────┐ |
The core design achieves IDP-Agnostic (identity source independence), ensuring that upstream account changes (e.g., Email domain changes due to corporate renaming) don’t affect data associations in business systems.
5. Collaboration Boundaries
Standardized protocols clarify collaboration between the identity governance system and upstream IdP:
| Responsibility Party | Core Capabilities |
|---|---|
| Upstream IdP | Identity Assertion, MFA/SSO, Lifecycle Sync (HR System Integration) |
| Internal Governance Layer | Access Decisions, Session Consistency Management, Enterprise Profile Enrichment, Global Operation Audit |
6. Key Takeaways
This architecture aims to establish a protocol-neutral, clearly-responsible identity governance bridge:
- Protocol-neutral: Based on standard protocols, not bound to specific vendors, supporting any OIDC Provider
- Consistent governance: Global trusted identity distribution through gateway injection
- Controlled management: Combining stateless protocol flexibility with stateful management security through SID and versioning mechanisms