oidcx

Documentation

Overview

Package oidcx provides provider-neutral OIDC/JWKS JWT verification.

It is intentionally independent from Casdoor's SDK. Gateway and backend services can use this package to verify Casdoor, Keycloak, Logto or any OIDC provider that exposes discovery + JWKS. Provider-specific behavior is handled by configurable claim names and a PrincipalMapper.

Index

• type Config
  • func (c Config) Normalized() Config
• type Verifier
  • func New(cfg Config) (*Verifier, error)
  • func (v *Verifier) Authenticate(ctx context.Context, credential authn.Credential) (authn.Principal, error)
  • func (v *Verifier) VerifyToken(ctx context.Context, req authn.VerifyTokenRequest) (authn.Principal, error)

Types

type Config

type Config struct {
	// Provider is copied to authn.Principal.Provider. Use "casdoor" for
	// Casdoor-backed deployments. Defaults to "oidc".
	Provider string `json:"provider" yaml:"provider"`

	// Issuer is the trusted issuer expected in the JWT iss claim. When
	// DiscoveryURL is set and Issuer is empty, the discovery issuer is used.
	Issuer string `json:"issuer" yaml:"issuer"`

	// DiscoveryURL is the OIDC discovery endpoint, for example
	// https://casdoor.example.com/.well-known/openid-configuration.
	DiscoveryURL string `json:"discovery_url" yaml:"discovery_url"`

	// JWKSURL is the public key endpoint. It can be provided directly or read
	// from discovery_url.jwks_uri.
	JWKSURL string `json:"jwks_url" yaml:"jwks_url"`

	// Audience lists accepted aud values. At least one must match when non-empty.
	Audience []string `json:"audience" yaml:"audience"`

	// AllowedAlgs restricts accepted JWT signing algorithms.
	// Defaults to RS256, RS512, ES256, ES512.
	AllowedAlgs []string `json:"allowed_algs" yaml:"allowed_algs"`

	// AllowedOwners optionally restricts an owner/organization claim. Casdoor
	// uses owner. Other providers can map this via OwnerClaim.
	AllowedOwners []string `json:"allowed_owners" yaml:"allowed_owners"`

	// Claim mapping. Defaults are Casdoor-compatible while remaining generic.
	SubjectIDClaim string `json:"subject_id_claim" yaml:"subject_id_claim"`
	UsernameClaim  string `json:"username_claim" yaml:"username_claim"`
	NameClaim      string `json:"name_claim" yaml:"name_claim"`
	EmailClaim     string `json:"email_claim" yaml:"email_claim"`
	OwnerClaim     string `json:"owner_claim" yaml:"owner_claim"`
	GroupsClaim    string `json:"groups_claim" yaml:"groups_claim"`
	RolesClaim     string `json:"roles_claim" yaml:"roles_claim"`
	ScopesClaim    string `json:"scopes_claim" yaml:"scopes_claim"`

	// CacheTTL controls in-process JWKS cache lifetime.
	JWKSCacheTTL time.Duration `json:"jwks_cache_ttl_ns" yaml:"jwks_cache_ttl_ns"`

	// ClockSkew is the accepted leeway for exp/nbf/iat validation.
	ClockSkew time.Duration `json:"clock_skew_ns" yaml:"clock_skew_ns"`

	HTTPClient *http.Client `json:"-" yaml:"-"`
	Logger     logx.Logger  `json:"-" yaml:"-"`
}

Config controls OIDC/JWKS token verification.

func (Config) Normalized

func (c Config) Normalized() Config

type Verifier

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

Verifier verifies OIDC JWTs using configured issuer/audience and JWKS.

func New

func New(cfg Config) (*Verifier, error)

func (*Verifier) Authenticate

func (v *Verifier) Authenticate(ctx context.Context, credential authn.Credential) (authn.Principal, error)

func (*Verifier) VerifyToken

func (v *Verifier) VerifyToken(ctx context.Context, req authn.VerifyTokenRequest) (authn.Principal, error)