go-usertoken/docs/api.md

API

Generated from the package comment and every exported declaration. Do not edit. Regenerate with UPDATE_API_DOCS=1 go test -run TestAPIDoc -count=1.

Package usertoken

Package usertoken mints and checks the short-lived RS256 user token an ExApp sends to Microservices.

An ExApp calls NewSignerFromEnv and Signer.Mint after AppAPI has named the user. A Microservice calls FromEnv and Auth.Middleware or Auth.UnaryServerInterceptor. One process trusts either a static public key or an OIDC issuer, not both.

The procedure, claims, and environment variables are in knowledge/platforms/nextcloud/exapps/authentication.md.

Variables

ErrUnauthorized

var ErrUnauthorized = errors.New("unauthorized")

ErrUnauthorized is wrapped by every failed token check. Startup and configuration failures do not wrap it.

Functions

BearerFromContext

func BearerFromContext(ctx context.Context) (string, bool)

BearerFromContext returns the raw JWT Auth.Middleware stored, without the "Bearer " prefix. Outbound calls send "Bearer " plus this string.

Types

Auth

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

Auth verifies bearers for one Microservice process.

FromEnv

func FromEnv(ctx context.Context) (*Auth, error)

FromEnv reads the process environment and builds an Auth. Set USER_TOKEN_PUBLIC_KEY_FILE or OIDC_ISSUER, not both and not neither. Static mode also reads USER_TOKEN_ISSUER and USER_TOKEN_AUDIENCE. OIDC mode reads OIDC_AUDIENCE and optional OIDC_GROUPS_CLAIM. Optional USER_TOKEN_SKEW is a time.Duration; empty uses 1 minute. It returns an error when the mode is ambiguous, the key file is unreadable, USER_TOKEN_SKEW cannot be parsed, or OIDC discovery fails. ctx is used for OIDC discovery.

New

func New(ctx context.Context, cfg Config) (*Auth, error)

New builds an Auth from explicit configuration. ctx is used for OIDC discovery.

Auth.Middleware

func (a *Auth) Middleware() func(http.Handler) http.Handler

Middleware requires a bearer on every path except /health. Success stores the Caller and the raw JWT on the request context.

Auth.UnaryServerInterceptor

func (a *Auth) UnaryServerInterceptor() grpc.UnaryServerInterceptor

UnaryServerInterceptor requires a bearer on every RPC. Success stores the Caller and the raw JWT on the handler context, same as Auth.Middleware. Native clients send metadata key "authorization". The HTTP gateway's forwarded header is "grpcgateway-authorization".

Auth.Verify

func (a *Auth) Verify(ctx context.Context, raw string) (Caller, error)

Verify checks a raw JWT. raw has no "Bearer " prefix. A failed check wraps ErrUnauthorized. Startup and configuration failures do not.

Caller

type Caller struct {
	Subject		string
	Username	string
	Groups		[]string
}

Caller is the user a verified token names. Groups is nil when the token omitted the claim, and non-nil (possibly empty) when the claim was present.

CallerFromContext

func CallerFromContext(ctx context.Context) (Caller, bool)

CallerFromContext returns the user Auth.Middleware stored.

Config

type Config struct {
	PublicKey	*rsa.PublicKey
	Issuer		string
	Audience	string
	OIDCIssuer	string
	OIDCAudience	string
	GroupsClaim	string
	Skew		time.Duration
}

Config selects one verify mode. Set PublicKey for static RS256, or OIDCIssuer for discovery. Not both. Skew of zero uses 1 minute. GroupsClaim empty uses "groups" (OIDC only). Audience empty is allowed only for OIDC, where it skips the audience check.

MintInput

type MintInput struct {
	Subject	string
	Groups	*[]string
}

MintInput is one user token. Groups nil omits the claim. A non-nil pointer includes it, including an empty list.

SignConfig

type SignConfig struct {
	PrivateKey	*rsa.PrivateKey
	Issuer		string
	Audience	string
	TTL		time.Duration
}

SignConfig is the ExApp mint configuration. TTL of zero uses 5 minutes.

Signer

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

Signer mints RS256 user tokens. Only the ExApp should hold one.

NewSigner

func NewSigner(cfg SignConfig) (*Signer, error)

NewSigner checks the key, issuer, and audience. It returns an error when PrivateKey is nil or issuer or audience is empty. A TTL of zero or less uses 5 minutes.

NewSignerFromEnv

func NewSignerFromEnv() (*Signer, error)

NewSignerFromEnv reads USER_TOKEN_PRIVATE_KEY_FILE, USER_TOKEN_ISSUER, USER_TOKEN_AUDIENCE, and optional USER_TOKEN_TTL. It returns an error when the private-key path is empty, the PEM is not an RSA key, USER_TOKEN_TTL is set and is not a time.Duration, or issuer or audience is empty. An empty USER_TOKEN_TTL uses 5 minutes.

Signer.Mint

func (s *Signer) Mint(now time.Time, in MintInput) (string, error)

Mint signs one RS256 token at now. Subject becomes both sub and preferred_username. It returns an error when Subject is empty or the key cannot sign.