Skip to main content

oidc

OIDC workload identity for Webda — secretless, auditable trust between applications. Publish an OIDC discovery document, mint short-lived audience-scoped tokens, verify tokens from trusted issuers (other Webda apps, Kubernetes, GitHub Actions, GCP) and authorize the caller through IAM as app:<name>.

When to use it​

  • Two Webda applications must call each other and you do not want to share an API key or a secret.
  • A Kubernetes workload, a GitHub Actions workflow or a GCP service account must call your application.
  • You want the callers to be IAM principals (app:orders) that policies can allow or deny.

User login stays with @webda/auth; this package is about applications.

Install​

pnpm add @webda/oidc

Configuration​

// App A (orders): issues tokens and calls other applications
"services": {
  "CryptoService": { "url": "/jwks", "jwt": { "algorithm": "RS256" } },
  "OIDCIssuer": { "type": "Webda/OIDCIssuer", "issuer": "https://orders.example.com", "name": "orders" },
  "OIDCClient": { "type": "Webda/OIDCClient", "source": "self" }
}
// App B (billing): trusts orders
"services": {
  "OIDCVerifier": {
    "type": "Webda/OIDCVerifier",
    "audience": "https://billing.example.com",
    "trustedIssuers": [{ "issuer": "https://orders.example.com", "claims": { "sub": "app:orders" } }]
  }
}
ServiceMain parameters
Webda/OIDCIssuerissuer (required), name, tokenTtl (300), algorithm (RS256), audiences (["*"])
Webda/OIDCVerifieraudience, trustedIssuers (issuer, claims, principal, groups, audiences, algorithms, jwksUri, maxTokenAge), clockTolerance (30), maxTokenAge (3600), jwksCacheTtl (600)
Webda/OIDCClientsource (self, file, gcp-metadata, github-actions), tokenFile, refreshMargin (60)

Usage​

import { useOIDCClient } from "@webda/oidc";

// App A: the Bearer token is added, its audience defaults to the url origin
const res = await useOIDCClient().fetch("https://billing.example.com/invoices", { method: "POST", body: "{}" });

On App B, the SessionManager hands the Bearer token to the OIDCVerifier: a valid token gives a stateless application session (session.application, no user) and @webda/iam sees the principals app:orders, app-issuer:https://orders.example.com, authenticated-app:

"attachments": { "app:orders": ["InvoiceWriter"] }

Reference​

Classes​

Interfaces​

Type Aliases​

Functions​