OAuth Identity Chaining SDK (oauth-identity-chaining-sdk)

A Python client library implementing cross-application authentication, dynamic permission downscoping, and call chain tracking conforming to draft-ietf-oauth-identity-chaining (OAuth Identity and Authorization Chaining Across Domains) and RFC 8693 (Token Exchange).

This SDK allows autonomous AI agents and microservices to pass credentials downstream under the Principle of Least Privilege, preserving tamper-proof actor provenance (Principal ──> Agent A ──> Agent B) via nested JWT act (actor) claims.

⚡ Installation

Install the library using pip:

pip install oauth-identity-chaining-sdk

🚀 Key Features

• 🔄 RFC 8693 Token Exchange: Exchange a broad subject token for a narrow downstream token using exchange_token.
• 🛡️ Permission Narrowing: Intersection check ensures delegated tokens hold a strict subset of delegator rights.
• 🔍 Multi-Hop Actor Provenance: Parse and traverse nested act claims to verify call chain lineages.
• 🛑 Least Privilege Guards: Enforce audience matches, expiration timestamps, and strict delegation depth limits.
• 💡 Mock Mode Fallback: Bypasses external server requests during local development or offline simulations.

📖 Quick Start

1. Fetching a Root Delegation Token

import os
from oauth_identity_chaining import ChainingClient, ChainingConfig

# Setup client. Automatically falls back to mock mode if env variables are missing.
client = ChainingClient()

# Get the initial delegation token for Agent A
root_token = client.get_root_token()
print(f"Root Token: {root_token[:30]}...")

2. Performing a Scoped Token Exchange (Delegation Chain)

Agent A delegates users:read authority to Agent B (AGENT_B_CLIENT_ID):

agent_b_id = "c7f3a2b1-5d4e-4f8a-9c6b-2e1d0f7a8b3c"

exchange_res = client.exchange_token(
    subject_token=root_token,
    target_client_id=agent_b_id,
    permissions=["users:read"],
    ttl=300,
    audience=["authsec-secure-vault"]
)

chained_token = exchange_res["token"]
print(f"Chained Token: {chained_token[:30]}...")

3. Parsing and Rendering Actor Provenance

Upstream services or resource servers can verify the token's lineage and print the visual actor tree:

from oauth_identity_chaining import verify_token_provenance

# Verify claims and extract provenance chain
chain = verify_token_provenance(
    chained_token,
    expected_audience="authsec-secure-vault",
    max_depth=1,
    verify_signature=False  # Set to True and provide jwks_client in production
)

# Print visual chain tree
print("Actor Call Chain Lineage:")
print(chain.render_tree())
# Output:
# [Principal User]
#   └── spiffe://localhost/ns/default/sa/crewai (Client ID: 6656be3a-b687-4f2e-9e83-11abe5eaec26)
#         └── spiffe://localhost/ns/default/sa/agent-b (Client ID: c7f3a2b1-5d4e-4f8a-9c6b-2e1d0f7a8b3c)  <-- ACTIVE BEARER

print(f"Delegation Depth: {chain.depth}")
print(f"Active Bearer: {chain.active_bearer.sub}")
print(f"Root Delegator: {chain.root_subject.sub}")

4. Downstream API Call

Agent B calls the Secure Vault using the chained token:

vault_response = client.request_secure_api(
    endpoint="http://localhost:7469/secure-vault/metrics",
    token=chained_token,
    method="GET"
)
print(vault_response)

🛠️ Offline Mock Fallback

If AUTHSEC_BASE_URL or AUTHSEC_AGENT_CLIENT_ID are not configured:

• The client runs in offline simulation mode automatically.
• Token endpoints return locally-generated HS256 tokens carrying valid act claims.
• Downstream endpoints (secure-vault/metrics and secure-vault/records) return pre-defined mock JSON structures.