TrueNamePath Documentation

Context-Aware Identity Management API

View on GitHub

Technical Details

OAuth implementation comparison and academic project technical specifications

Academic Project Context

This implementation is an academic proof-of-concept demonstrating the feasibility of context-aware identity management. Technical simplifications were made to focus on the core innovation—user-controlled, context-specific name presentation—rather than reimplementing standard OAuth infrastructure. All design decisions reflect conscious trade-offs for academic demonstration, not limitations in technical understanding. The system includes 85 database migrations and comprehensive OIDC-compliant claims resolution.

OAuth Implementation Comparison

Side-by-side comparison of production OAuth systems versus our academic implementation. Note: Our opaque Bearer token approach follows RFC 6750 and is a valid production pattern used by many OAuth 2.0 providers.

Aspect	Production OAuth	TrueNamePath Academic	Production Gap
Token Type	JWT with cryptographic signing	Opaque Bearer tokens `tnp_[32 hex]`	JWT optional enhancement
Token Expiration	Enforced cryptographically	2-hour database expiry	Optional JWT enhancement
Refresh Tokens	Full refresh token flow	Not implemented (Token reusability within 2-hour validity)	Long-term refresh token implementation
Client Authentication	Client secret validation	Public client pattern	Confidential client support
Scope Management	Fine-grained scopes	Context-based permissions	Scope standardization
PKCE	Required for public clients	Not implemented	PKCE flow implementation
Token Format	JWT (RS256/HS256)	`tnp_[a-f0-9]{32}`	JWT structure needed

Opaque Bearer Token Implementation

Our implementation uses opaque Bearer tokens following RFC 6750 OAuth 2.0 Bearer Token Usage specification. This is a legitimate production pattern offering enhanced security and revocation control:

Format: tnp_[32 hexadecimal characters]
Generation: Cryptographically secure random generation via database function
Validation: Regex pattern matching ^tnp_[a-f0-9]{32}$ plus database session lookup for comprehensive verification
Expiry: 2-hour database-enforced expiry with server-side validation (expires_at timestamp checks)
Usage: Authorization: Bearer tnp_xxx
Performance: Optimized for fast response times with indexed database lookups and session reusability
Security: Immediate revocation capability, domain-based client registry, and CSRF protection via state parameter

OIDC Claims Implementation

Our system implements comprehensive OIDC-compliant claims following OpenID Connect Core 1.0 specification. Claims are returned via the /oauth/resolve endpoint with full validation:

Mandatory OIDC Claims (RFC Required)

sub - Subject Identifier (user profile ID)
iss - Issuer (https://truenameapi.demo)
aud - Audience (client application name)
iat - Issued At (current epoch time)
exp - Expiration (iat + 3600 seconds)

Additional Standard Claims

nbf - Not Before (same as iat)
jti - JWT ID (unique token identifier)
email and email_verified - User email with verification status
updated_at - Profile last update timestamp
locale (en-GB) and zoneinfo (Europe/London)

TrueNamePath Innovation Claims

context_name - User-selected context for this session
Dynamic name properties (given_name, family_name, etc.) based on context assignment
client_id and app_name - Application context

Technical Implementation: Claims are generated server-side via the resolve_oauth_oidc_claims() PostgreSQL function with real-time context resolution, maintaining sub-3ms response times for name resolution operations.

System Architecture Flow

The following describes how data flows through the TrueNamePath system during key operations:

User Registration

User creates account → Automatic default context creation → Initial name setup via database triggers

Context Management

User creates custom contexts → Assigns name variants to contexts → Configures context visibility (public/private)

OAuth Authorization

Client application redirects → User selects context for app → Bearer token generation (tnp_xxx format) → Redirect with token

Name Resolution

API call to /oauth/resolve → Bearer token validation → Context-aware name resolution → OIDC-compliant claims response

Session Management

Session tracking with 2-hour expiry → Token reusability → Revocation via /oauth/sessions endpoint

Technical Note: This flow represents the complete end-to-end process from user registration to context-aware name resolution, demonstrating how the Bearer token approach supports the core innovation of user-controlled identity presentation.

OAuth Pattern Choices Explained

Technical rationale behind our OAuth implementation decisions, demonstrating understanding of multiple valid approaches in the OAuth 2.0 ecosystem:

Why Opaque Bearer Tokens?

Immediate Revocation: Database-backed tokens allow instant session termination, crucial for security incidents
Simplified Validation: No cryptographic verification overhead, enabling sub-3ms response times
Industry Standard: Used by GitHub, Discord, and many other production OAuth providers
Privacy Benefits: No user information exposed in token, enhancing GDPR compliance

Domain Registry Security Model

Domain Validation: Client applications must prove domain ownership during registration
Public Client Pattern: Follows OAuth 2.0 guidelines for client-side applications
Reduced Attack Surface: No client secrets to compromise or rotate in demo environments

Context-Based Authorization Innovation

Beyond Traditional Scopes: User-controlled context assignment provides fine-grained identity presentation
GDPR-First Design: Data minimization through purpose-specific identity contexts
Real-World Applicability: Professional vs. personal identity separation matches user expectations

Academic Achievement: This implementation demonstrates mastery of OAuth 2.0 fundamentals while introducing genuine innovation in context-aware identity management. The opaque token approach is not a limitation but a conscious architectural choice supporting the core research contribution.

Security Trade-offs & Academic Choices

The following design decisions balance academic demonstration with production-viable patterns:

Opaque Tokens vs. JWTs

Opaque Bearer tokens provide immediate revocation capability and enhanced security through server-side validation. This follows RFC 6750 and is used by many production OAuth systems. JWT implementation would be an optional enhancement for stateless validation.

Public Client Pattern

Client ID-only authentication follows OAuth 2.0 public client guidelines, appropriate for demo applications and client-side apps. Domain-based registry provides security without secret management complexity. Confidential client support would be added for server-to-server applications.

Scope Management

Context-based permissions replace traditional OAuth scopes, demonstrating innovative approach while maintaining GDPR compliance through privacy-by-design.

GDPR Compliance Priority

Full GDPR compliance implementation (data minimization, consent management, right to erasure) takes precedence over OAuth infrastructure completeness for this academic project.

Production Readiness Roadmap

Optional enhancements for different production scenarios. Note: The current opaque token implementation is production-viable for many use cases.

JWT Enhancement (Optional)

Add JWT support alongside opaque tokens for stateless validation scenarios. Both patterns would coexist for different client types and use cases.

Refresh Token Infrastructure

Implement refresh token rotation with secure storage and proper revocation cascading for enhanced security.

Confidential Client Support

Extend current public client pattern to support confidential clients with secret validation for server-to-server applications.

PKCE Implementation

Implement Proof Key for Code Exchange for public clients (mobile apps, SPAs) following RFC 7636.

Hybrid Scope System

Complement context-based permissions with traditional OAuth scopes for broader ecosystem compatibility while preserving innovation.

Security Hardening

Add rate limiting, request signing, comprehensive audit logging, and security headers for production deployment.

Monitoring & Observability

Implement comprehensive monitoring, metrics collection, and alerting for OAuth flows and context resolution performance.

Performance Metrics & Industry Context

Performance Design Goals

Name Resolution: Optimized database queries with indexed lookups for efficient context-aware identity resolution
Token Operations: Streamlined OAuth token validation with database-backed session management
Dashboard Loading: Efficient data fetching with SWR caching for responsive identity management interface

Academic Note: Specific performance metrics would require production load testing infrastructure not implemented in this proof-of-concept. The system is designed for efficiency with database indexing and caching strategies.

Academic & Technical Achievement

This implementation successfully demonstrates both technical mastery of OAuth 2.0 patterns and genuine innovation in context-aware identity management. The system achieves full OIDC compliance with efficient database design and showcases production-viable engineering patterns, while the context assignment system addresses real-world privacy needs that traditional OAuth scopes cannot handle.