Go: package oidc

Generated from the Go source by scripts/gen-docs.sh — do not edit; run it to regenerate. Canonical deep reference: pkg.go.dev/github.com/dnsid-ai/dnsid-go/oidc. Guides and account setup: https://docs.dnsid.ai.

import "github.com/dnsid-ai/dnsid-go/oidc"

Package oidc mints and verifies DNSid OIDC tokens.

The package implements an OIDC federation profile on top of core DNSid identity verification. An agent proves control of its domain-anchored identity by signing a JWT-bearer assertion with its operational key; an OIDC issuer exchanges that assertion for tokens; and a relying party verifies an issued token against the issuer’s published JWKS and, by default, verifies the token subject as a DNSid domain through a dnsid.IdentityResolver.

Profile is the main entry type. Construct one with New, NewFromIdentityManager, or NewFromIdentityManagerKeyProvider, then mint tokens with GetOIDCToken (or CreateOIDCAssertion plus ExchangeOIDCToken) and verify presented tokens with VerifyOIDCToken:

idm, err := config.IdentityManagerFromDnsid(ctx, "", dnsid.Config{}, config.Dependencies{})
if err != nil {
  log.Fatal(err)
}
profile := oidc.NewFromIdentityManagerKeyProvider(idm, oidc.Config{
  AllowedIssuers: []string{"https://issuer.example"},
})

// Agent side: mint a token from an OIDC issuer.
token, err := profile.GetOIDCToken(ctx, oidc.OIDCTokenExchangeOptions{
  Issuer:   "https://issuer.example",
  Audience: "https://api.example",
})

// Relying-party side: verify a presented token. The token's issuer
// must appear in Config.AllowedIssuers.
subject, err := profile.VerifyOIDCToken(ctx, token.AccessToken, oidc.VerifyOIDCTokenOptions{
  Issuer:   "https://issuer.example",
  Audience: "https://api.example",
})

All issuer traffic uses SSRF-safe transport, never follows redirects, caps response sizes, and requires HTTPS issuers whose discovery endpoints are same-origin with the issuer (Config.AllowHTTPLoopbackIssuer relaxes the HTTPS requirement for loopback issuers during local development).

See https://docs.dnsid.ai for protocol guides and account setup.

Index

• type Config
  • func (c Config) WithAssertionLifetime(d time.Duration) Config
  • func (c Config) WithClockSkew(skew time.Duration) Config
  • func (c Config) WithMaxAssertionLifetime(d time.Duration) Config
• type DiscoveryDocument
• type OIDCAssertionOptions
  • func (o OIDCAssertionOptions) WithExpiry(d time.Duration) OIDCAssertionOptions
• type OIDCTokenExchangeOptions
• type OIDCTokenResponse
• type Profile
  • func New(resolver dnsid.IdentityResolver, localDomain string, kp dnsid.KeyProvider, cfg Config) *Profile
  • func NewFromIdentityManager(manager identityManager, kp dnsid.KeyProvider, cfg Config) *Profile
  • func NewFromIdentityManagerKeyProvider(manager identityManagerWithKeyProvider, cfg Config) *Profile
  • func (p *Profile) CreateOIDCAssertion(opts OIDCAssertionOptions) (string, error)
  • func (p *Profile) DiscoverOIDCIssuer(ctx context.Context, issuer string) (*DiscoveryDocument, error)
  • func (p *Profile) ExchangeOIDCToken(ctx context.Context, opts OIDCTokenExchangeOptions) (*OIDCTokenResponse, error)
  • func (p *Profile) GetOIDCToken(ctx context.Context, opts OIDCTokenExchangeOptions) (*OIDCTokenResponse, error)
  • func (p *Profile) SetHTTPClient(c *http.Client)
  • func (p *Profile) SetUnsafeHTTPClientForTesting(c *http.Client)
  • func (p *Profile) VerifyOIDCToken(ctx context.Context, token string, opts VerifyOIDCTokenOptions) (*VerifiedOIDCSubject, error)
• type TokenExchangeError
  • func (e *TokenExchangeError) Error() string
• type VerifiedOIDCSubject
• type VerifyOIDCTokenOptions

type Config

Config contains OIDC federation profile policy. The zero value applies the documented defaults, requires HTTPS issuers, and allows no issuers for token verification.

type Config struct {
    // DefaultScope is the scope requested during token exchange when
    // OIDCTokenExchangeOptions.Scope is empty. When both are empty the
    // profile requests "openid".
    DefaultScope string

    // AssertionLifetime is the default validity window of assertions
    // created by CreateOIDCAssertion. Zero means omitted (5 minutes).
    AssertionLifetime time.Duration

    // MaxAssertionLifetime caps the assertion lifetime, including any
    // per-call OIDCAssertionOptions.Expiry override. Zero means omitted
    // (15 minutes). Negative lifetimes are invalid.
    MaxAssertionLifetime time.Duration

    // ClockSkew is the tolerance applied to time claims during token
    // verification. Zero means omitted (30 seconds); WithClockSkew(0)
    // specifies zero tolerance. Negative skew is invalid; expiration is strict.
    ClockSkew time.Duration

    // AllowedIssuers lists the exact issuer URLs VerifyOIDCToken accepts.
    // An empty list rejects every issuer.
    AllowedIssuers []string

    // AllowedTokenAlgorithms is the policy allowlist of JWS algorithms for
    // verified tokens. An empty list means RS256 only. This binding
    // currently verifies RS256 only; other allowed algorithms are rejected
    // as not implemented.
    AllowedTokenAlgorithms []string

    // AllowHTTPLoopbackIssuer permits http:// issuers on localhost and
    // loopback addresses, as a test/local-development escape hatch. All
    // other issuers must use https.
    AllowHTTPLoopbackIssuer bool
    // contains filtered or unexported fields
}

func (Config) WithAssertionLifetime

func (c Config) WithAssertionLifetime(d time.Duration) Config

WithAssertionLifetime specifies a positive default assertion lifetime.

func (Config) WithClockSkew

func (c Config) WithClockSkew(skew time.Duration) Config

WithClockSkew specifies tolerance, including explicit zero.

func (Config) WithMaxAssertionLifetime

func (c Config) WithMaxAssertionLifetime(d time.Duration) Config

WithMaxAssertionLifetime specifies a positive maximum assertion lifetime.

type DiscoveryDocument

DiscoveryDocument is the subset of OIDC discovery metadata (/.well-known/openid-configuration) this profile uses.

type DiscoveryDocument struct {
    Issuer        string `json:"issuer"`
    TokenEndpoint string `json:"token_endpoint"`
    JWKSURI       string `json:"jwks_uri"`
}

type OIDCAssertionOptions

OIDCAssertionOptions configures CreateOIDCAssertion.

type OIDCAssertionOptions struct {
    // Issuer is the OIDC issuer URL the assertion is addressed to; it
    // becomes the assertion's sole audience. Required.
    Issuer string

    // Expiry overrides Config.AssertionLifetime for this assertion when
    // positive. Zero means omitted; WithExpiry records explicit presence and
    // rejects zero. Negative values and values above the maximum are invalid.
    Expiry time.Duration

    // AdditionalClaims are extra claims to embed in the assertion. They
    // must not override the reserved claims iss, sub, aud, iat, exp, jti,
    // or fqdn.
    AdditionalClaims map[string]any
    // contains filtered or unexported fields
}

func (OIDCAssertionOptions) WithExpiry

func (o OIDCAssertionOptions) WithExpiry(d time.Duration) OIDCAssertionOptions

WithExpiry specifies an explicit positive assertion lifetime.

type OIDCTokenExchangeOptions

OIDCTokenExchangeOptions configures ExchangeOIDCToken and GetOIDCToken.

type OIDCTokenExchangeOptions struct {
    // Issuer is the OIDC issuer URL to exchange the assertion with.
    // Required.
    Issuer string

    // Audience is the audience requested for the issued token. Required.
    Audience string

    // Scope is the requested scope. Empty means Config.DefaultScope, or
    // "openid" if that is also empty.
    Scope string

    // Assertion is an optional pre-built JWT-bearer assertion. Its
    // audience must be exactly the issuer. When empty, ExchangeOIDCToken
    // mints a fresh assertion; GetOIDCToken always ignores this field.
    Assertion string
}

type OIDCTokenResponse

OIDCTokenResponse is a successful response from an OIDC token endpoint.

type OIDCTokenResponse struct {
    AccessToken string `json:"access_token"`
    IDToken     string `json:"id_token,omitempty"`
    TokenType   string `json:"token_type"`
    ExpiresIn   int64  `json:"expires_in,omitempty"`
    Scope       string `json:"scope,omitempty"`

    // Raw is the full decoded JSON response body, including fields not
    // mapped above. It is excluded when the response is re-serialized.
    Raw map[string]any `json:"-"`
}

type Profile

Profile implements OIDC federation helpers on top of DNSid identity verification.

type Profile struct {
    // contains filtered or unexported fields
}

func New

func New(resolver dnsid.IdentityResolver, localDomain string, kp dnsid.KeyProvider, cfg Config) *Profile

New constructs an OIDC federation profile. localDomain and kp are required for CreateOIDCAssertion and token exchange; resolver is required by VerifyOIDCToken when it verifies the token subject as a DNSid domain. localDomain is normalized to a canonical FQDN when possible.

func NewFromIdentityManager

func NewFromIdentityManager(manager identityManager, kp dnsid.KeyProvider, cfg Config) *Profile

NewFromIdentityManager constructs an OIDC profile from an IdentityManager-like core manager, using the manager as the resolver and its Domain as the local domain. kp supplies the signing key.

func NewFromIdentityManagerKeyProvider

func NewFromIdentityManagerKeyProvider(manager identityManagerWithKeyProvider, cfg Config) *Profile

NewFromIdentityManagerKeyProvider constructs an OIDC profile from a manager that exposes its KeyProvider, such as one loaded with config.IdentityManagerFromDnsid.

func (*Profile) CreateOIDCAssertion

func (p *Profile) CreateOIDCAssertion(opts OIDCAssertionOptions) (string, error)

CreateOIDCAssertion signs a JWT-bearer assertion with the profile’s active operational key. The assertion’s iss, sub, and fqdn claims are the profile’s local domain, its sole audience is the issuer, and it carries iat, exp, and a random jti. It returns an error if the profile has no local identity or KeyProvider, the issuer is invalid, the requested lifetime exceeds Config.MaxAssertionLifetime, or AdditionalClaims override a reserved claim or are not JSON-serializable.

func (*Profile) DiscoverOIDCIssuer

func (p *Profile) DiscoverOIDCIssuer(ctx context.Context, issuer string) (*DiscoveryDocument, error)

DiscoverOIDCIssuer fetches the issuer’s OIDC discovery document from issuer + “/.well-known/openid-configuration”. It returns an error unless the document’s issuer exactly matches the requested issuer and both token_endpoint and jwks_uri are same-origin with it. Redirects are rejected and responses are capped at 1 MiB.

func (*Profile) ExchangeOIDCToken

func (p *Profile) ExchangeOIDCToken(ctx context.Context, opts OIDCTokenExchangeOptions) (*OIDCTokenResponse, error)

ExchangeOIDCToken performs an OAuth 2.0 JWT-bearer grant (urn:ietf:params:oauth:grant-type:jwt-bearer) against the issuer’s token endpoint. When opts.Assertion is empty it mints one with CreateOIDCAssertion; otherwise the pre-built assertion must be a valid JWT whose sole audience is exactly the discovered issuer. The response must contain an access_token with token_type Bearer. opts.Audience is required.

func (*Profile) GetOIDCToken

func (p *Profile) GetOIDCToken(ctx context.Context, opts OIDCTokenExchangeOptions) (*OIDCTokenResponse, error)

GetOIDCToken mints a DNSid OIDC token: it signs a fresh JWT-bearer assertion with the profile’s operational key and exchanges it at the issuer’s token endpoint. It is ExchangeOIDCToken with opts.Assertion always ignored.

Example

ExampleProfile_GetOIDCToken mints a DNSid OIDC token: the profile signs a JWT-bearer assertion with the agent’s operational key and exchanges it at the issuer’s token endpoint.

It requires an agent identity on disk (created with `dnsid auth login` and `dnsid init`, see QUICKSTART.md) and a reachable OIDC issuer, so it has no Output and is compiled but not run by go test.

package main

import (
  "context"
  "fmt"
  "log"
  "time"

  dnsid "github.com/dnsid-ai/dnsid-go"
  "github.com/dnsid-ai/dnsid-go/config"
  "github.com/dnsid-ai/dnsid-go/oidc"
)

func main() {
  // Load the agent identity from ~/.dnsid. The manager can both verify
  // domains and sign as the agent.
  ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second)
  defer cancel()

  idm, err := config.IdentityManagerFromDnsid(ctx, "", dnsid.Config{}, config.Dependencies{})
  if err != nil {
    log.Fatal(err)
  }

  profile := oidc.NewFromIdentityManagerKeyProvider(idm, oidc.Config{})

  tok, err := profile.GetOIDCToken(ctx, oidc.OIDCTokenExchangeOptions{
    Issuer:   "https://issuer.example",
    Audience: "https://api.example",
  })
  if err != nil {
    log.Fatal(err)
  }

  fmt.Println("token_type:", tok.TokenType)
  fmt.Println("expires_in:", tok.ExpiresIn)
}

func (*Profile) SetHTTPClient

func (p *Profile) SetHTTPClient(c *http.Client)

SetHTTPClient replaces the profile’s HTTP client with a copy of c hardened for issuer traffic: the transport is wrapped with SSRF and DNS-rebinding protection, and redirects are never followed. Passing nil installs the default safe client.

func (*Profile) SetUnsafeHTTPClientForTesting

func (p *Profile) SetUnsafeHTTPClientForTesting(c *http.Client)

SetUnsafeHTTPClientForTesting installs a copy of c without SSRF protection; redirects are still never followed. It is intended only for tests against local servers — production code should use SetHTTPClient.

func (*Profile) VerifyOIDCToken

func (p *Profile) VerifyOIDCToken(ctx context.Context, token string, opts VerifyOIDCTokenOptions) (*VerifiedOIDCSubject, error)

VerifyOIDCToken verifies an OIDC token issued to this relying party. The issuer must appear in Config.AllowedIssuers and match the token’s iss claim, and the token must carry exactly the single audience opts.Audience. The signature is verified against the issuer’s discovered JWKS: the JWS header may contain only alg, kid, and typ, the algorithm must be allowed by Config.AllowedTokenAlgorithms (RS256 is the only implemented algorithm), and the kid must select exactly one signature-eligible RSA key of at least 2048 bits. Time claims are checked within Config.ClockSkew. Unless opts.VerifyDnsidSubject is explicitly false, the token’s sub claim is then verified as a DNSid domain through the profile’s resolver, and the result is returned in VerifiedOIDCSubject.VerifiedDomain. Errors carry dnsid verification codes describing the first failed check.

type TokenExchangeError

TokenExchangeError is the issuer’s refusal of a token exchange: the token endpoint answered, with a non-200 status and (usually) an RFC 6749 error body. It is distinct from not reaching the endpoint at all, which surfaces as a transport error, so callers can tell “the issuer said no” from “the exchange did not happen” with errors.As.

type TokenExchangeError struct {
    StatusCode  int    // HTTP status from the token endpoint
    Code        string // RFC 6749 "error", e.g. invalid_grant; empty if the body had none
    Description string // RFC 6749 "error_description", if any
}

func (*TokenExchangeError) Error

func (e *TokenExchangeError) Error() string

type VerifiedOIDCSubject

VerifiedOIDCSubject is the result of a successful VerifyOIDCToken call.

type VerifiedOIDCSubject struct {
    Issuer   string
    Subject  string
    Audience string

    // VerifiedDomain is the DNSid verification result for Subject. It is
    // nil when VerifyOIDCTokenOptions.VerifyDnsidSubject disabled subject
    // verification.
    VerifiedDomain *dnsid.VerifiedDomain

    // Claims is the token's full decoded claim set.
    Claims map[string]any
}

type VerifyOIDCTokenOptions

VerifyOIDCTokenOptions configures VerifyOIDCToken.

type VerifyOIDCTokenOptions struct {
    // Issuer is the expected issuer URL. Required; it must also appear in
    // Config.AllowedIssuers.
    Issuer string

    // Audience is the expected audience. Required; the token must carry
    // exactly this single audience.
    Audience string

    // VerifyDnsidSubject controls whether the token's sub claim is
    // verified as a DNSid domain through the profile's resolver. Nil or
    // true verifies; false skips subject verification.
    VerifyDnsidSubject *bool
    // Peer supplies trusted current application-peer evidence for DNSid verification.
    Peer dnsid.VerifyDomainOpts
}

Generated by gomarkdoc