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
- Variables
- func Encode(doc map[string]any) ([]byte, error)
- func Render(s Settings, sec Secrets, w Wiring) (map[string]any, error)
- func Validate(doc map[string]any) error
- func Write(path string, content []byte, mode os.FileMode) (bool, error)
- type Claims
- type Consent
- type OIDC
- type PKCE
- type Refresh
- type Secrets
- type Settings
- type TTL
- type Tokens
- type Wiring
Constants ¶
const ( ConsentHook = "Consent" TokenClaimsHook = "TokenClaims" )
Hooks backplane-hydra declares.
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.
const KeyHeader = "X-Backplane-Hydra-Key"
KeyHeader carries Wiring.Key on the token hook.
const SchemaVersion = "v26.2.0"
SchemaVersion is the Hydra release whose configuration schema validates the overlay.
Variables ¶
var ( ErrOverrides = errors.New("overrides") ErrConflict = errors.New("is set by the settings or backplane-hydra; change it there") )
Errors of Render.
var ErrInvalid = errors.New("hydra would refuse the configuration")
ErrInvalid: Hydra would refuse the overlay.
Functions ¶
func Validate ¶
Validate checks doc against Hydra's configuration schema, merged over a stand-in base file.
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 ¶
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.