Documentation
¶
Overview ¶
Package flows turns Kratos's callbacks into Backplane hooks and events: the courier's messages (hook Deliver), the before/after points of the self-service flows (hooks Before<Flow>/After<Flow>) and the facts of completed flows (events).
Index ¶
- Constants
- func CredentialTypes() []string
- type DeliverIn
- type DeliverOut
- type Deny
- type FlowEvent
- type FlowIn
- type FlowOut
- type Flows
- func (f *Flows) BindingChanges(ctx context.Context) <-chan struct{}
- func (f *Flows) Bound(name string) bool
- func (f *Flows) DeliverRef() hook.Ref[DeliverIn, DeliverOut]
- func (f *Flows) Event(flow string) event.Ref[FlowEvent]
- func (f *Flows) Handler() http.Handler
- func (f *Flows) Hooks() []string
- func (f *Flows) LoggedOut() event.Ref[FlowEvent]
- func (f *Flows) Logout(public *url.URL, headers map[string]string) http.Handler
- func (f *Flows) Point(name string) hook.Ref[FlowIn, FlowOut]
- func (f *Flows) Public(public *url.URL, headers map[string]string, exchangeMaxAge time.Duration, ...) http.Handler
- func (f *Flows) SessionIssued() hook.Ref[SessionIssuedIn, SessionIssuedOut]
- func (f *Flows) Stats() []Stat
- func (f *Flows) TokenExchange(public *url.URL, headers map[string]string, maxAge time.Duration) http.Handler
- type IdentityPatch
- type Message
- type Outbox
- type Rendered
- type SessionDeny
- type SessionIssuedIn
- type SessionIssuedOut
- type Sessions
- type Stat
Constants ¶
const ( ChangeAdded = "added" ChangeRemoved = "removed" ChangeReplaced = "replaced" )
Changes of a credential.
const ( // SelfServicePath is the prefix of Kratos's self-service endpoints the // deployment routes to Public, all of it: any answer under it may // carry a session, and every one is admitted. SelfServicePath = "/self-service/" // OIDCStartPath is the hop a sign-in with a provider takes on its way // there: it sets the cookie that carries the client's flow to the // callback. It sits under Kratos's OIDC prefix, routed here with it. OIDCStartPath = "/self-service/methods/oidc/backplane/start" )
const ( // ChannelBrowser: a session cookie. ChannelBrowser = "browser" // ChannelAPI: a session token in the flow's answer. ChannelAPI = "api" // ChannelNativeExchange: a session token from /sessions/token-exchange. ChannelNativeExchange = "native_exchange" )
Channels a new session's credential leaves by.
const LogoutPath = "/self-service/logout"
LogoutPath is the prefix of Kratos's self-service logout endpoints the deployment routes to this service instead of Kratos.
const NativeFlowHeader = "X-Kratos-Flow-Id"
NativeFlowHeader names the app's flow on a session token exchange; it reaches SessionIssued unverified.
const RecordMessage = 5000002
RecordMessage is shown when a change is refused because its security event cannot be recorded.
const SessionIssuedHook = "SessionIssued"
SessionIssuedHook admits a stored session before its credential leaves.
const TokenExchangePath = "/sessions/token-exchange"
TokenExchangePath is Kratos's session token exchange, the end of a native app's browser sign-in; the deployment routes it to this service instead of Kratos.
UnavailableMessage is shown when a flow hook fails and is not fail-open.
Variables ¶
This section is empty.
Functions ¶
func CredentialTypes ¶ added in v0.0.47
func CredentialTypes() []string
CredentialTypes are the credentials a settings flow changes, read with their configurations to tell a change from none.
Types ¶
type DeliverIn ¶
type DeliverIn struct {
// Channel is "email" or "sms".
Channel string `json:"channel" validate:"oneof=email sms"`
Recipient string `json:"recipient" schemapb:"description=Address or phone number"`
// TemplateType is Kratos's message kind, e.g. verification_code_valid,
// recovery_code_valid, login_code_valid, registration_code_valid.
TemplateType string `json:"template_type"`
// Code is the one-time code the message carries, if any.
Code string `json:"code,omitempty" schemapb:"secret=true"`
// Link is the link the message carries (verification, recovery), if any.
Link string `json:"link,omitempty" schemapb:"secret=true"`
ExpiresInMinutes int64 `json:"expires_in_minutes,omitempty"`
// Identity the message is about, as Kratos sends it.
Identity json.RawMessage `json:"identity,omitempty"`
// Data is the rest of Kratos's template data.
Data json.RawMessage `json:"data,omitempty"`
// Rendered is Kratos's own rendering of the message.
Rendered Rendered `json:"rendered"`
// TransientPayload the flow carried.
TransientPayload json.RawMessage `json:"transient_payload,omitempty"`
}
DeliverIn is a message Kratos's courier hands over: deliver it.
type DeliverOut ¶
type DeliverOut struct{}
DeliverOut is empty: a returned error makes Kratos retry the message.
type FlowEvent ¶
type FlowEvent = *kratoseventsv1.FlowEvent
FlowEvent is a completed flow: Registered, LoggedIn, SettingsChanged, Recovered, Verified.
type FlowIn ¶
type FlowIn struct {
// Flow is registration, login, settings, recovery or verification.
Flow string `json:"flow"`
// Method is the method the flow completed with (after points); "any"
// where Kratos does not tell.
Method string `json:"method,omitempty"`
// FlowID and FlowType ("api" or "browser").
FlowID string `json:"flow_id,omitempty"`
FlowType string `json:"flow_type,omitempty"`
// ClientFlowID is the flow the client submitted or started, as this
// service's proxy vouches for it. It differs from FlowID only when Kratos
// converted the flow: an OIDC login of an unknown subject completes as a
// new registration flow, an OIDC registration of a known one as a new
// login flow. Empty when the request did not pass the proxy.
ClientFlowID string `json:"client_flow_id,omitempty"`
// Identity of the flow (after points). At AfterRegistration it is not
// stored yet and has no id; AfterRegistrationStored has the final one.
Identity json.RawMessage `json:"identity,omitempty"`
// Session acting in the flow, as Kratos sends it: at BeforeSettings and
// AfterSettings the signed-in one; after login and registration the new
// one, which Kratos stores only after the hooks, so its id (and its
// devices' ids) are empty there. Absent where Kratos sends none. No
// token or cookie.
Session ory.Session `json:"session,omitzero"`
TransientPayload json.RawMessage `json:"transient_payload,omitempty"`
RequestURL string `json:"request_url,omitempty"`
RequestMethod string `json:"request_method,omitempty"`
// RequestHeaders Kratos forwards (its allowlist); never cookies.
RequestHeaders map[string]string `json:"request_headers,omitempty"`
}
FlowIn is a self-service flow at a before or after point.
type FlowOut ¶
type FlowOut struct {
// Deny stops the flow and shows these messages.
Deny *Deny `json:"deny,omitempty"`
// Identity replaces parts of the identity (registration and settings).
Identity *IdentityPatch `json:"identity,omitempty"`
}
FlowOut is the hook's verdict: nothing lets the flow continue.
type Flows ¶
Flows declares the hooks and events and serves Kratos's callbacks.
func New ¶
func New(parent deps.Scope, key string, failOpen config.Live[[]string], sessions Sessions, box Outbox) *Flows
New declares the hooks and events under parent; key authenticates Kratos; hooks named in failOpen let the flow continue when they fail; sessions reads Kratos's sessions and identities; box keeps the security events with what they report.
func (*Flows) BindingChanges ¶
BindingChanges signals when the set of bound hooks changes.
func (*Flows) DeliverRef ¶
func (f *Flows) DeliverRef() hook.Ref[DeliverIn, DeliverOut]
DeliverRef, Point and Event are the declared refs (tests, wiring code).
func (*Flows) Handler ¶
Handler serves the callbacks: /courier/{channel}, /hooks/{when}/{flow}/{method}, /events/{flow}/{method}.
func (*Flows) Logout ¶ added in v0.0.30
Logout serves Kratos's logout endpoints (LogoutPath and below) in front of Kratos at public: Kratos ends the session as always, and when it has, LoggedOut is published with it. Kratos itself has no logout hooks. headers go with every request to Kratos (a proxy's authorization).
func (*Flows) Public ¶ added in v0.0.41
func (f *Flows) Public( public *url.URL, headers map[string]string, exchangeMaxAge time.Duration, settings config.Live[overlay.Settings], ) http.Handler
Public serves Kratos's public API in front of Kratos at public: logout, the session token exchange, the OIDC callbacks and start hop, and every other request, passed on. Every request to Kratos with a client flow carries FlowHeader for it; every session an answer issues is admitted by SessionIssued before its credential leaves. Settings and verification issue none: Kratos sets the cookie of a session that exists already. headers go with every request to Kratos; settings give the flows' lifespans and error page.
func (*Flows) SessionIssued ¶ added in v0.0.41
func (f *Flows) SessionIssued() hook.Ref[SessionIssuedIn, SessionIssuedOut]
SessionIssued is the hook that admits a new session.
func (*Flows) TokenExchange ¶ added in v0.0.41
func (f *Flows) TokenExchange(public *url.URL, headers map[string]string, maxAge time.Duration) http.Handler
TokenExchange serves Kratos's session token exchange in front of Kratos at public. Kratos answers a code pair again and again, at any age, even for a session that has ended; this answers only for an active session authenticated within maxAge, else 404 as for an unknown pair, and only once SessionIssued admitted the session. Answers before the session exists (a polling app) pass unchanged. headers go with every request to Kratos.
type IdentityPatch ¶
type IdentityPatch struct {
Traits json.RawMessage `json:"traits,omitempty"`
MetadataPublic json.RawMessage `json:"metadata_public,omitempty"`
MetadataAdmin json.RawMessage `json:"metadata_admin,omitempty"`
}
IdentityPatch replaces whole parts of an identity; absent parts stay.
type Message ¶
type Message struct {
// Field is the form field, e.g. "traits.email"; empty: the whole form.
Field string `json:"field,omitempty"`
// ID lets a UI translate the message.
ID int64 `json:"id,omitempty"`
Text string `json:"text"`
// Type is error (default), info or success.
Type string `json:"type,omitempty" validate:"omitempty,oneof=error info success"`
Context json.RawMessage `json:"context,omitempty"`
}
Message shown to the user.
type Outbox ¶ added in v0.0.47
type Outbox interface {
Register(topic string, p outbox.Publisher)
Enqueue(ctx context.Context, m outbox.Message) error
}
Outbox keeps the security events until the broker took them (README, Security events).
type Rendered ¶
type Rendered struct {
Subject string `json:"subject,omitempty" schemapb:"secret=true"`
Body string `json:"body,omitempty" schemapb:"secret=true"`
HTML string `json:"html,omitempty" schemapb:"secret=true"`
}
Rendered is a message as Kratos's templates render it; it holds the code.
type SessionDeny ¶ added in v0.0.41
type SessionDeny struct {
// Code is the machine reason the client gets (error.reason).
Code string `json:"code" validate:"required"`
Messages []Message `json:"messages,omitempty"`
}
SessionDeny refuses a new session.
type SessionIssuedIn ¶ added in v0.0.41
type SessionIssuedIn struct {
// Flow is login, registration or recovery: the flow the client
// submitted; empty for an OIDC callback whose start is unknown.
Flow string `json:"flow,omitempty"`
// Method is the session's latest authentication method (password, code,
// oidc, webauthn, passkey, totp, lookup_secret, code_recovery, ...).
Method string `json:"method"`
// FlowID is the client's flow, the ClientFlowID of the after hooks: the
// submit's ?flow=, for an OIDC sign-in the flow that started it, for the
// native exchange the app's X-Kratos-Flow-Id header (unverified). Empty
// when unknown.
FlowID string `json:"flow_id,omitempty"`
// Channel is browser, api or native_exchange.
Channel string `json:"channel"`
// Identity of the session, stored.
Identity ory.Identity `json:"identity"`
// Session as Kratos stored it, without its identity, token or cookie.
Session ory.Session `json:"session"`
// TransientPayload of the submit that issued the session; empty for an
// OIDC callback and the native exchange (the after hooks had it).
TransientPayload json.RawMessage `json:"transient_payload,omitempty"`
}
SessionIssuedIn is a session Kratos has stored whose credential has not left yet.
type SessionIssuedOut ¶ added in v0.0.41
type SessionIssuedOut struct {
Deny *SessionDeny `json:"deny,omitempty"`
}
SessionIssuedOut: nothing lets the credential go; Deny revokes the session and refuses the client.
type Sessions ¶ added in v0.0.17
type Sessions interface {
ListIdentitySessions(ctx context.Context, id string, f ory.SessionFilter) (ory.Page[ory.Session], error)
// WhoAmI is the session of a token or a cookie header.
WhoAmI(ctx context.Context, token, cookie string) (ory.Session, error)
GetSession(ctx context.Context, id string) (ory.Session, error)
// DisableSession revokes a session.
DisableSession(ctx context.Context, id string) error
// GetIdentity reads an identity, with the configurations of the
// credential types named.
GetIdentity(ctx context.Context, id string, includeCredential ...string) (ory.Identity, error)
}
Sessions reads sessions from Kratos.