overlay

package
v0.0.19 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 20, 2026 License: MIT Imports: 16 Imported by: 0

Documentation

Overview

Package overlay renders the Hydra configuration file backplane-hydra owns: the settings an operator edits in the console, the consent and logout endpoints it serves, and the token hook while it is bound. Hydra loads it after the deployment's base file (`hydra serve all -c base.yml -c overlay.yml`) and reloads it when it changes.

Index

Constants

View Source
const (
	ConsentHook     = "Consent"
	TokenClaimsHook = "TokenClaims"
)

Hooks backplane-hydra declares.

View Source
const Header = "# Written by backplane-hydra from the installation's settings; edits here are overwritten.\n"

Header opens the file: a reader learns who writes it.

View Source
const KeyHeader = "X-Backplane-Hydra-Key"

KeyHeader carries Wiring.Key on the token hook.

View Source
const SchemaVersion = "v26.2.0"

SchemaVersion is the Hydra release whose configuration schema validates the overlay.

Variables

View Source
var (
	ErrOverrides = errors.New("overrides")
	ErrConflict  = errors.New("is set by the settings or backplane-hydra; change it there")
)

Errors of Render.

View Source
var ErrInvalid = errors.New("hydra would refuse the configuration")

ErrInvalid: Hydra would refuse the overlay.

Functions

func Encode

func Encode(doc map[string]any) ([]byte, error)

Encode is the overlay file's content.

func Render

func Render(s Settings, sec Secrets, w Wiring) (map[string]any, error)

Render is the overlay document for s and w.

func Validate

func Validate(doc map[string]any) error

Validate checks doc against Hydra's configuration schema, merged over a stand-in base file.

func Write

func Write(path string, content []byte, mode os.FileMode) (bool, error)

Write replaces path with content atomically (a rename in its directory, which Hydra's file watcher follows) unless it holds content already; changed reports a write. mode must let the Hydra container read it; the file holds client secrets, so it belongs on a pod-private volume.

Types

type Claims

type Claims struct {
	// MirrorTopLevel copies top-level access token claims under ext.
	MirrorTopLevel bool `json:"mirror_top_level,omitempty" schemapb:"default=true"`
	// AllowedTopLevel are the access token claims allowed at the top level.
	AllowedTopLevel []string `json:"allowed_top_level,omitempty"`
	// ClientCredentialsDefaultScope grants a client credentials request
	// every allowed scope when it asks for none.
	ClientCredentialsDefaultScope bool `json:"client_credentials_default_scope,omitempty" schemapb:"default=false"`
	ExposeInternalErrors          bool `json:"expose_internal_errors,omitempty"           schemapb:"default=false"`
}

Claims of tokens.

type Consent struct {
	// UIURL takes consent that is not skipped; empty: such requests are
	// rejected with consent_required.
	UIURL string `json:"ui_url,omitempty" schemapb:"description=A consent UI for non-trusted clients (empty: refuse them)"`
	// RememberFor is how long an automatic consent is remembered; zero:
	// for ever.
	RememberFor time.Duration `json:"remember_for,omitempty" schemapb:"default=0s"`
}

Consent served by backplane-hydra when the hook hydra.Consent is unbound.

type OIDC

type OIDC struct {
	DynamicClientRegistration bool     `json:"dynamic_client_registration,omitempty" schemapb:"default=false"`
	SubjectTypes              []string `json:"subject_types,omitempty"               schemapb:"description=public, pairwise"`
}

OIDC options.

type PKCE

type PKCE struct {
	Enforced                 bool `json:"enforced,omitempty"                    schemapb:"default=false"`
	EnforcedForPublicClients bool `json:"enforced_for_public_clients,omitempty" schemapb:"default=true"`
}

PKCE enforcement.

type Refresh

type Refresh struct {
	RotationGracePeriod time.Duration `json:"rotation_grace_period,omitempty"      schemapb:"default=0s"`
	RotationGraceReuse  int64         `json:"rotation_grace_reuse_count,omitempty" schemapb:"default=0"`
}

Refresh token rotation.

type Secrets added in v0.0.2

type Secrets struct {
	// PairwiseSalt salts pairwise subject identifiers.
	PairwiseSalt string
}

Secrets the overlay needs, kept apart from Settings (their own Live paths): the console writes a secret only when the operator enters one.

type Settings

type Settings struct {
	// Issuer is the public issuer URL of tokens.
	Issuer string `json:"issuer,omitempty" schemapb:"description=Public URL tokens name as their issuer"`
	// LoginURL is the login UI (Kratos's login page when Kratos is the
	// login provider).
	LoginURL        string `json:"login_url,omitempty"        schemapb:"description=The login UI Hydra sends users to"`
	RegistrationURL string `json:"registration_url,omitempty"`
	ErrorURL        string `json:"error_url,omitempty"`
	// PostLogoutRedirect is where a logout without a client's URI lands.
	PostLogoutRedirect string `json:"post_logout_redirect,omitempty"`

	TTL     TTL     `json:"ttl,omitempty"`
	Tokens  Tokens  `json:"tokens,omitempty"`
	PKCE    PKCE    `json:"pkce,omitempty"`
	Claims  Claims  `json:"claims,omitempty"`
	Consent Consent `json:"consent,omitempty"`
	OIDC    OIDC    `json:"oidc,omitempty"`
	Refresh Refresh `json:"refresh,omitempty"`

	// Overrides is raw Hydra YAML merged last, for what Settings does not
	// model; it may not set a key Settings or the callbacks set.
	Overrides string `json:"overrides,omitempty" schemapb:"description=Raw Hydra YAML for keys these settings do not model"`
}

Settings are the Hydra settings the overlay owns. Durations and flags are always written (their defaults are Hydra's); an empty string or list is left to the base file.

type TTL

type TTL struct {
	AccessToken           time.Duration `json:"access_token,omitempty"           schemapb:"default=1h"`
	RefreshToken          time.Duration `json:"refresh_token,omitempty"          schemapb:"default=720h"`
	IDToken               time.Duration `json:"id_token,omitempty"               schemapb:"default=1h"`
	AuthCode              time.Duration `json:"auth_code,omitempty"              schemapb:"default=10m"`
	LoginConsentRequest   time.Duration `json:"login_consent_request,omitempty"  schemapb:"default=30m"`
	AuthenticationSession time.Duration `json:"authentication_session,omitempty" schemapb:"default=720h"`
}

TTL of Hydra's artifacts.

type Tokens

type Tokens struct {
	// AccessToken is jwt (services verify it locally with Hydra's keys,
	// pkg/auth) or opaque (services ask Hydra's introspection each time).
	AccessToken string `json:"access_token,omitempty" schemapb:"default={\"stringValue\":\"jwt\"}" validate:"oneof=opaque jwt"`
	// Scope is how requested scopes match the allowed ones.
	Scope string `json:"scope,omitempty" schemapb:"default={\"stringValue\":\"wildcard\"}" validate:"oneof=wildcard exact"`
}

Tokens are the token strategies.

type Wiring

type Wiring struct {
	// PublicURL is backplane-hydra's public API as browsers reach it: the
	// consent and logout endpoints.
	PublicURL string
	// CallbacksURL is the callbacks listener as Hydra reaches it.
	CallbacksURL string
	// Key authenticates Hydra's calls (header KeyHeader).
	Key string
	// Bound reports whether a hook (short name) is bound.
	Bound func(hook string) bool
}

Wiring is how Hydra and browsers reach backplane-hydra and what is bound.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL