Documentation
¶
Overview ¶
Package oidc provides OIDC token verification for Agentuity services.
It validates JWT access tokens and ID tokens issued by the Agentuity OIDC provider (auth.agentuity.cloud), handling JWKS discovery, key caching, and standard claim validation.
By default, the verifier uses "https://auth.agentuity.cloud" as the issuer. Use WithIssuer to override for custom or local deployments.
Usage:
// Default issuer (auth.agentuity.cloud):
verifier, err := oidc.NewVerifier(
oidc.WithAudience("my-client-id"),
)
// Custom issuer:
verifier, err := oidc.NewVerifier(
oidc.WithIssuer("https://auth.custom.example.com"),
oidc.WithAudience("my-client-id"),
)
if err != nil {
log.Fatal(err)
}
claims, err := verifier.VerifyToken(ctx, tokenString)
if err != nil {
// handle invalid token
}
fmt.Println("User:", claims.Subject)
Index ¶
Constants ¶
const DefaultIssuer = "https://auth.agentuity.cloud"
DefaultIssuer is the default Agentuity OIDC provider issuer URL.
Variables ¶
var ( // ErrTokenExpired indicates the token's exp claim is in the past. ErrTokenExpired = errors.New("oidc: token expired") // ErrTokenNotYetValid indicates the token's nbf claim is in the future. ErrTokenNotYetValid = errors.New("oidc: token not yet valid") // ErrInvalidIssuer indicates the token's iss claim doesn't match the expected issuer. ErrInvalidIssuer = errors.New("oidc: invalid issuer") // ErrInvalidAudience indicates the token's aud claim doesn't match any expected audience. ErrInvalidAudience = errors.New("oidc: invalid audience") // ErrInvalidSignature indicates the token's signature could not be verified. ErrInvalidSignature = errors.New("oidc: invalid signature") // ErrNoMatchingKey indicates no key in the JWKS matched the token's kid header. ErrNoMatchingKey = errors.New("oidc: no matching key found in JWKS") // ErrMalformedToken indicates the token could not be parsed. ErrMalformedToken = errors.New("oidc: malformed token") // ErrDiscoveryFailed indicates the OIDC discovery document could not be fetched. ErrDiscoveryFailed = errors.New("oidc: discovery failed") )
Functions ¶
This section is empty.
Types ¶
type Claims ¶
type Claims struct {
jwt.RegisteredClaims
// Scope is the space-separated scopes string from the token.
// Use Scopes() to get them as a slice.
Scope string `json:"scope,omitempty"`
// ClientID is the OAuth2 client that requested the token.
ClientID string `json:"client_id,omitempty"`
// AuthorizedParty is the party to which the token was issued.
AuthorizedParty string `json:"azp,omitempty"`
// Email is the user's email address (requires "email" scope).
Email string `json:"email,omitempty"`
// EmailVerified indicates whether the email has been verified.
EmailVerified *bool `json:"email_verified,omitempty"`
// Name is the user's full name (requires "profile" scope).
Name string `json:"name,omitempty"`
// GivenName is the user's first name (requires "profile" scope).
GivenName string `json:"given_name,omitempty"`
// FamilyName is the user's last name (requires "profile" scope).
FamilyName string `json:"family_name,omitempty"`
// OrgID is the organization this token is scoped to (Agentuity-specific).
OrgID string `json:"org_id,omitempty"`
// Nonce is the nonce from the original auth request (ID tokens only).
Nonce string `json:"nonce,omitempty"`
// AtHash is the access token hash (ID tokens only).
AtHash string `json:"at_hash,omitempty"`
}
Claims represents the claims extracted from a verified OIDC token. It includes both standard OIDC claims and Agentuity-specific claims.
func (*Claims) IsClientCredentials ¶
IsClientCredentials returns true if this token was issued via the client_credentials grant (subject equals client ID, no user identity).
type Option ¶
type Option func(*Verifier)
Option configures a Verifier.
func WithAudience ¶
WithAudience sets the expected audience(s) for token validation. If multiple audiences are provided, the token must contain at least one. If no audience is set, audience validation is skipped.
func WithCacheTTL ¶
WithCacheTTL sets how long JWKS keys are cached before being refreshed. Default is 5 minutes.
func WithClockSkew ¶
WithClockSkew sets the allowed clock skew for token time validation. Default is 30 seconds.
func WithHTTPClient ¶
WithHTTPClient sets a custom HTTP client for JWKS and discovery requests.
func WithIssuer ¶
WithIssuer overrides the default issuer URL (DefaultIssuer). Use this for custom or local OIDC provider deployments.
func WithJWKSURL ¶
WithJWKSURL overrides the JWKS URL instead of discovering it from the issuer's .well-known/openid-configuration. Useful for testing or non-standard setups.
func WithLogger ¶
WithLogger sets the logger for the verifier.
type Verifier ¶
type Verifier struct {
// contains filtered or unexported fields
}
Verifier validates OIDC tokens issued by an Agentuity auth provider.
It discovers the provider's JWKS endpoint from the OpenID Connect discovery document, caches the keys, and validates both the signature and standard claims (iss, aud, exp, iat, nbf) of incoming tokens.
Key rotation is handled transparently: if a token's kid doesn't match any cached key, the JWKS is refreshed before returning an error.
func NewVerifier ¶
NewVerifier creates a new OIDC token verifier.
By default it uses DefaultIssuer ("https://auth.agentuity.cloud") as the issuer URL. Use WithIssuer to override this for custom or local deployments.
The verifier discovers the JWKS endpoint from {issuer}/.well-known/openid-configuration.
Options can configure issuer, audience validation, HTTP client, logger, and cache settings.
func (*Verifier) VerifyToken ¶
VerifyToken parses and validates a JWT access token or ID token.
It verifies the token's signature against the provider's JWKS keys, and validates the issuer, audience, and expiry claims. On success, it returns the parsed claims.
If the token's key ID (kid) doesn't match any cached key, the JWKS cache is automatically refreshed to handle key rotation.
Source Files