Credenza

OIDC Relying Party and Narrow OAuth 2.1 Authorization Server

Credenza is a RESTful web service that functions as both an OIDC Relying Party (RP) and a narrow OAuth 2.1 Authorization Server (AS). It handles OAuth2/OIDC login/logout/device flows to upstream OIDC Identity Providers (IdPs) and caches OIDC userinfo, identity claims, and tokens in a persistent session storage layer. It then issues opaque, audience-bound access tokens for protected resource servers — validated via RFC 7662 token introspection.

Credenza also supports machine-to-machine (M2M) authentication via the OAuth 2.0 client_credentials grant. Clients prove identity via configured adapters (e.g., AWS STS presigned GetCallerIdentity, client secret), and receive opaque bearer tokens bound to configured scopes and resource audiences.

Features:

• Supports multiple OIDC Identity Providers via configuration profiles (Keycloak, Okta, Cognito, Globus, etc.)
• Persistent session storage with lifecycle management and session encryption
• All OAuth2/OIDC flows use the Python authlib module with PKCE enabled whenever applicable
• OAuth 2.1 Authorization Server capabilities:
  • RFC 8414 Authorization Server Metadata discovery
  • RFC 7662 Token Introspection with per-client resource gating
  • RFC 8693 Token Exchange with default-deny exchange policy
  • RFC 7009 Token Revocation
  • Authorization Code + PKCE flow for registered clients
  • Client Credentials grant for M2M / service authentication
  • RFC 8628 Device Authorization Grant (fully spec-compliant)
• Client authentication via extensible adapter interface:
  • client_secret (HTTP Basic or form post)
  • aws_presigned (AWS STS presigned GetCallerIdentity — no shared secrets)
  • Custom adapters (mTLS, workload identity, etc.) via @register_adapter
• Unified client registry with per-client grant type, scope, resource, and lifetime policy
• Opaque bearer tokens backed by server-side sessions (instantly revocable, auditable)
• Secure background token refresh for device sessions
• Audit logging
• Prometheus metrics

Why Credenza?

Modern applications delegate authentication to external identity providers, but identity providers solve authentication and token issuance — they do not automatically solve the internal identity-management problem inside a deployment. Backends still need normalized principals, policy-aware token disclosure, consistent session state across browser, device, and service workflows, downstream credential brokerage, and centralized revocation and audit.

Credenza addresses this as a deployment-local broker: a first-party service that translates upstream identity artifacts into a stable, policy-aware internal abstraction that backends can consume uniformly, regardless of how the identity was established.

Key properties:

• Opaque, server-side tokens — Credenza issues opaque access tokens backed by server-side sessions, not self-contained JWTs. Sessions can be revoked instantly. Token contents can differ by the resource server calling introspect, enabling controlled per-caller disclosure without distributing that policy across services.
• Unified session model — browser (Authorization Code + PKCE), device (RFC 8628), and M2M service identities (client credentials) are all represented through one internal session model. Device sessions perform background upstream token refresh; no other grant type holds or uses long-lived upstream credentials.
• Token exchange for downstream brokerage — RFC 8693 token exchange allows services to obtain audience-scoped derived tokens for downstream APIs under explicit, default-deny policy. Services do not need to implement delegation logic themselves.
• Per-client introspection gating — resource servers retrieve only the session claims they are authorized to see, enforced at the broker rather than distributed across applications.

As recent security analyses have highlighted, modernization without coherent identity and session oversight can create more surface area for compromise — not less. Credenza provides a governed, auditable control plane for identity and token lifecycle across the deployment.

Further Reading

• Deployment-Local Identity and Session Brokerage — whitepaper describing the architectural pattern Credenza implements

• Application identity modernization poses significant risks – Help Net Security

• Session Management in Microservices – GeeksforGeeks

Authentication Flows

• User Auth (OIDC) Documentation

• Client Auth (M2M) Documentation

• Authentication Flow Diagrams

Further Documentation

• Configuration Reference — credenza.env, oidc_idp_profiles.json, and client_registry.json

• OAuth & OIDC Profile — supported RFCs, grant types, and token characteristics

• Security Model — threat model, trust boundaries, and operational assumptions

• ADR-0001: Narrow OAuth AS Profile — architecture decision record for AS functionality

• ADR-0002: Delegation Consent — optional consent UI and delegation transparency

• ADR-0003: mTLS Client Authentication — RFC 8705 mutual TLS adapter

• ADR-0004: private_key_jwt Client Authentication — RFC 7523 asymmetric JWT adapter (blue-sky)

• ADR-0005: NIH-RAS Integration — NIH RAS IDP support and GA4GH Passport/Visa session augmentation for controlled-access biomedical data

• ADR-0006: Dependent Token Vending — secure client retrieval of upstream auxiliary tokens (e.g., Globus dependent tokens) via token exchange

• ADR-0007: Refreshable Derived Sessions — opt-in refresh tokens for derived sessions with three-tier wall-clock cap; enables long-running API workloads against IDPs without offline_access (e.g., NIH RAS)

• ADR-0008: Cross-Credenza Federation — peer introspection fallback for split deployments where tokens issued by one Credenza instance must be validated by another

Project Status

This project is being actively developed and should be considered Alpha quality. It is a functional prototype but is also subject to change at any point without notice.