OIDC, OAuth & Vault Integrations
Relevant source files
The following files were used as context for generating this wiki page:
Forze provides a robust identity plane that integrates external Identity Providers (IdPs) and secure secret management into its Hexagonal Architecture. The system is designed around a verify-then-resolve pipeline, ensuring that regardless of whether a user authenticates via OpenID Connect (OIDC), OAuth2 with PKCE, or local credentials, the application logic interacts with a canonical, UUID-native AuthnIdentity.
Integration with HashiCorp Vault extends these capabilities by providing secure backends for the Forze SecretsPort and offloading cryptographic operations, such as JWT signing, to secure hardware or managed services.
Sources: skills/forze-auth-tenancy-secrets/SKILL.md:12-25, skills/forze-wiring/SKILL.md:20-35
Authentication Pipeline Architecture
The authentication system is split into two distinct seams to maintain provider agnosticism within the domain and application layers.
1. Verifiers and Assertions
Verifiers are vendor-specific components (e.g., OidcTokenVerifier) that prove the validity of a credential. Upon successful verification, they emit a VerifiedAssertion. This assertion contains the issuer, subject, and claims, but does not yet represent a Forze-internal identity.
2. Principal Resolvers
Resolvers are vendor-agnostic components that transform a VerifiedAssertion into a canonical AuthnIdentity. This ensures that external subject strings (e.g., email or OIDC sub) are mapped to internal principal_id UUIDs.
The diagram above shows the data flow from an external credential to a bound Forze identity.
Sources: skills/forze-auth-tenancy-secrets/SKILL.md:27-45
OIDC & OAuth2 Integration
Forze supports OpenID Connect through the forze_identity.oidc package. This integration relies on standard JWT verification and claims mapping.
Key Components
| Component | Description |
|---|---|
OidcTokenVerifier | Implements TokenVerifierPort to validate OIDC-compliant JWTs. |
JwksKeyProvider | Dynamically fetches public keys from an IdP's JWKS endpoint for signature verification. |
OidcClaimMapper | Maps OIDC standard claims (e.g., sub, tid) to Forze assertion fields. |
PkceUtil | Provides helpers for Proof Key for Code Exchange (PKCE) used in secure OAuth2 flows. |
PKCE Implementation
Forze includes utilities for OAuth2 PKCE to secure the authorization code flow, particularly for public clients. It supports the S256 code challenge method.
# Verification of PKCE challenge
from forze_identity.oauth.pkce import verify_pkce
is_valid = verify_pkce(
code_verifier="...",
code_challenge="...",
method="S256"
)
Sources: src/forze_identity/oauth/pkce.py:1-20, skills/forze-auth-tenancy-secrets/SKILL.md:103-120
Vault & Secret Management
The forze_vault integration provides a secure implementation for the SecretsPort. This allows applications to resolve logical secret paths to sensitive values stored in HashiCorp Vault's KV v2 engine.
JWT Signing with Vault
Beyond simple secret storage, Forze can offload JWT signing to Vault. This ensures that the private keys used for issuing internal tokens never leave the secure Vault environment.
The sequence diagram illustrates the offloading of JWT signing to Vault's transit engine.
Sources: src/forze_vault/adapters/jwt_signer.py:10-45, skills/forze-auth-tenancy-secrets/SKILL.md:195-210
Vault Wiring
Vault is integrated into the application via VaultDepsModule, which registers the SecretsDepKey automatically.
from forze_vault import VaultClient, VaultConfig, VaultDepsModule
vault_module = VaultDepsModule(
client=VaultClient(config=VaultConfig(
url="https://vault:8200",
token="..."
)),
)
Sources: skills/forze-auth-tenancy-secrets/SKILL.md:212-220
Configuration Summary
The following table details the primary configuration elements for OIDC and Vault integrations.
| Config Element | Type | Description |
|---|---|---|
issuer | str | The expected iss claim in OIDC tokens. |
audience | str | The expected aud claim in OIDC tokens. |
jwks_url | str | Endpoint for fetching public keys. |
transit_key | str | Vault Transit engine key name for JWT signing. |
mount_point | str | The path where the Vault KV engine is mounted. |
Sources: src/forze_identity/oidc/verifier.py:5-30, src/forze_vault/adapters/jwt_signer.py:15
Conclusion
OIDC, OAuth, and Vault integrations in Forze provide a secure, scalable identity solution. By decoupling verification from principal resolution and leveraging Vault for both secrets and cryptographic operations, Forze maintains a strict separation of concerns while supporting complex enterprise authentication requirements.