ory

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: 12 Imported by: 0

Documentation

Overview

Package ory is a small client of an Ory Hydra installation: its admin API (clients, consent and login requests and sessions, tokens, keys, trusted issuers). Payloads Hydra owns the shape of (metadata, claims, sessions) stay JSON.

Index

Constants

This section is empty.

Variables

View Source
var ErrBaseURL = errors.New("must be an absolute http(s) URL")

ErrBaseURL: a base URL must be absolute http(s).

Functions

func IsNotFound

func IsNotFound(err error) bool

IsNotFound reports a 404 from Hydra.

func Temporary

func Temporary(err error) bool

Temporary reports a failure worth retrying: Hydra unreachable, timed out, rate limited or failing on its side.

Types

type AcceptConsent

type AcceptConsent struct {
	GrantScope    []string       `json:"grant_scope"`
	GrantAudience []string       `json:"grant_access_token_audience,omitempty"`
	Remember      bool           `json:"remember,omitempty"`
	RememberFor   int64          `json:"remember_for,omitempty"`
	Session       ConsentSession `json:"session"`
}

AcceptConsent is Hydra's acceptOAuth2ConsentRequest.

type AcceptLogin

type AcceptLogin struct {
	Subject     string          `json:"subject"`
	Remember    bool            `json:"remember,omitempty"`
	RememberFor int64           `json:"remember_for,omitempty"`
	ACR         string          `json:"acr,omitempty"`
	AMR         []string        `json:"amr,omitempty"`
	Context     json.RawMessage `json:"context,omitempty"`
	// IdentityProviderSessionID is the login provider's own session (a Kratos
	// session id): Hydra keeps it with the login session and hands it on.
	IdentityProviderSessionID string `json:"identity_provider_session_id,omitempty"`
	// ExtendSessionLifespan resets the remembered login session's lifespan
	// (remember_for) from now.
	ExtendSessionLifespan bool `json:"extend_session_lifespan,omitempty"`
}

AcceptLogin is Hydra's acceptOAuth2LoginRequest.

type Client

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

Client of one Hydra installation. It holds no state of its own: share it by value.

func New

func New(o Options) (Client, error)

New creates the client.

func (Client) AcceptConsentRequest

func (c Client) AcceptConsentRequest(ctx context.Context, challenge string, a AcceptConsent) (string, error)

AcceptConsentRequest accepts it: the redirect that resumes the flow.

func (Client) AcceptDeviceRequest added in v0.0.2

func (c Client) AcceptDeviceRequest(ctx context.Context, challenge, userCode string) (string, error)

AcceptDeviceRequest accepts a device flow's user code: the redirect.

func (Client) AcceptLoginRequest

func (c Client) AcceptLoginRequest(ctx context.Context, challenge string, a AcceptLogin) (string, error)

AcceptLoginRequest accepts it.

func (Client) AcceptLogoutRequest

func (c Client) AcceptLogoutRequest(ctx context.Context, challenge string) (string, error)

AcceptLogoutRequest accepts it.

func (Client) AdminURL

func (c Client) AdminURL() string

AdminURL and PublicURL are the configured bases.

func (Client) CreateClient

func (c Client) CreateClient(ctx context.Context, body json.RawMessage) (OAuth2Client, error)

CreateClient creates one from Hydra's client JSON; the answer carries the generated secret (the only time Hydra shows it).

func (Client) CreateKey

func (c Client) CreateKey(ctx context.Context, set, alg, use, kid string) ([]JWK, error)

CreateKey adds a generated key to a set (a rotation: the newest key signs, the older ones still verify).

func (Client) DeleteClient

func (c Client) DeleteClient(ctx context.Context, id string) error

DeleteClient deletes one.

func (Client) DeleteKey

func (c Client) DeleteKey(ctx context.Context, set, kid string) error

DeleteKey removes one key from a set.

func (Client) DeleteKeySet added in v0.0.2

func (c Client) DeleteKeySet(ctx context.Context, set string) error

DeleteKeySet removes a whole key set.

func (Client) DeleteTokens

func (c Client) DeleteTokens(ctx context.Context, clientID string) error

DeleteTokens deletes every token issued to a client.

func (Client) DeleteTrustedIssuer

func (c Client) DeleteTrustedIssuer(ctx context.Context, id string) error

DeleteTrustedIssuer stops trusting one.

func (Client) Discovery

func (c Client) Discovery(ctx context.Context) (map[string]any, error)

Discovery reads the issuer's OpenID configuration (public API).

func (Client) GetClient

func (c Client) GetClient(ctx context.Context, id string) (OAuth2Client, error)

GetClient reads one client.

func (Client) GetConsentRequest

func (c Client) GetConsentRequest(ctx context.Context, challenge string) (ConsentRequest, error)

GetConsentRequest reads a pending consent.

func (Client) GetKeySet

func (c Client) GetKeySet(ctx context.Context, set string) ([]JWK, error)

GetKeySet reads a key set's public keys.

func (Client) GetLoginRequest

func (c Client) GetLoginRequest(ctx context.Context, challenge string) (LoginRequest, error)

GetLoginRequest reads a pending login.

func (Client) GetLogoutRequest

func (c Client) GetLogoutRequest(ctx context.Context, challenge string) (LogoutRequest, error)

GetLogoutRequest reads a pending logout.

func (Client) ImportKey added in v0.0.2

func (c Client) ImportKey(ctx context.Context, set, kid string, jwk json.RawMessage) (JWK, error)

ImportKey stores a key the operator brings (with its private part to sign, public only to verify) under set; Hydra answers it.

func (Client) Introspect

func (c Client) Introspect(ctx context.Context, token, scope string) (Introspection, error)

Introspect reports a token's state (RFC 7662 on the admin API).

func (Client) ListClients

func (c Client) ListClients(ctx context.Context, f ClientFilter) (Page[OAuth2Client], error)

ListClients pages through the clients.

func (Client) ListConsentSessions

func (c Client) ListConsentSessions(ctx context.Context, subject, pageToken string) (Page[ConsentGrant], error)

ListConsentSessions lists a subject's remembered consents.

func (Client) ListTrustedIssuers

func (c Client) ListTrustedIssuers(ctx context.Context) ([]TrustedIssuer, error)

ListTrustedIssuers lists them.

func (Client) PatchClient

func (c Client) PatchClient(ctx context.Context, id string, patch json.RawMessage) (OAuth2Client, error)

PatchClient applies a JSON Patch to one.

func (Client) PublicURL

func (c Client) PublicURL() string

func (Client) Ready

func (c Client) Ready(ctx context.Context) error

Ready is Hydra's readiness (/health/ready on the admin API).

func (Client) RejectConsentRequest

func (c Client) RejectConsentRequest(ctx context.Context, challenge string, r Reject) (string, error)

RejectConsentRequest rejects it: the redirect that ends the flow.

func (Client) RejectLoginRequest

func (c Client) RejectLoginRequest(ctx context.Context, challenge string, r Reject) (string, error)

RejectLoginRequest rejects it.

func (Client) RejectLogoutRequest added in v0.0.2

func (c Client) RejectLogoutRequest(ctx context.Context, challenge string) error

RejectLogoutRequest refuses a pending logout.

func (Client) RevokeConsentSessions

func (c Client) RevokeConsentSessions(ctx context.Context, subject, clientID string) error

RevokeConsentSessions revokes a subject's consents: of one client, or all; tokens issued under them stop working.

func (Client) RevokeLoginSessions

func (c Client) RevokeLoginSessions(ctx context.Context, subject, sid string) error

RevokeLoginSessions ends a subject's (or one session id's) login sessions: the next authorization asks to log in again.

func (Client) SetClient

func (c Client) SetClient(ctx context.Context, id string, body json.RawMessage) (OAuth2Client, error)

SetClient replaces one with Hydra's client JSON.

func (Client) SetClientLifespans added in v0.0.2

func (c Client) SetClientLifespans(ctx context.Context, id string, lifespans map[string]string) (OAuth2Client, error)

SetClientLifespans sets a client's token lifespans per grant (Hydra's durations like "1h"; absent: the global TTL).

func (Client) TrustIssuer

func (c Client) TrustIssuer(ctx context.Context, body json.RawMessage) (TrustedIssuer, error)

TrustIssuer trusts one: body is Hydra's trustOAuth2JwtGrantIssuer.

func (Client) Version

func (c Client) Version(ctx context.Context) (string, error)

Version of the installation (/version on the admin API).

type ClientFilter

type ClientFilter struct {
	Name      string
	Owner     string
	PageSize  int
	PageToken string
}

ClientFilter narrows ListClients.

type ConsentGrant

type ConsentGrant struct {
	ConsentRequest ConsentRequest `json:"consent_request"`
	GrantScope     []string       `json:"grant_scope"`
	GrantAudience  []string       `json:"grant_access_token_audience,omitempty"`
	Remember       bool           `json:"remember"`
	RememberFor    int64          `json:"remember_for"`
	HandledAt      *time.Time     `json:"handled_at,omitempty"`
	Session        ConsentSession `json:"session"`
}

ConsentGrant is a remembered consent of a subject.

type ConsentRequest

type ConsentRequest struct {
	Challenge                    string          `json:"challenge"`
	Subject                      string          `json:"subject"`
	Client                       OAuth2Client    `json:"client"`
	RequestedScope               []string        `json:"requested_scope"`
	RequestedAccessTokenAudience []string        `json:"requested_access_token_audience"`
	Skip                         bool            `json:"skip"`
	ACR                          string          `json:"acr,omitempty"`
	AMR                          []string        `json:"amr,omitempty"`
	Context                      json.RawMessage `json:"context,omitempty"`
	OIDCContext                  json.RawMessage `json:"oidc_context,omitempty"`
	LoginSessionID               string          `json:"login_session_id,omitempty"`
	RequestURL                   string          `json:"request_url,omitempty"`
}

ConsentRequest is a pending consent.

type ConsentSession

type ConsentSession struct {
	AccessToken json.RawMessage `json:"access_token,omitempty"`
	IDToken     json.RawMessage `json:"id_token,omitempty"`
}

ConsentSession are the claims a consent puts into tokens.

type Error

type Error struct {
	Status  int
	ID      string // the OAuth error, e.g. "invalid_request"
	Message string
	Reason  string
}

Error is a failed Hydra call: the HTTP status and Hydra's own error body when it sent one.

func (*Error) Error

func (e *Error) Error() string

type Introspection

type Introspection struct {
	Active    bool            `json:"active"`
	Subject   string          `json:"sub,omitempty"`
	ClientID  string          `json:"client_id,omitempty"`
	Scope     string          `json:"scope,omitempty"`
	Audience  []string        `json:"aud,omitempty"`
	ExpiresAt int64           `json:"exp,omitempty"`
	IssuedAt  int64           `json:"iat,omitempty"`
	Issuer    string          `json:"iss,omitempty"`
	TokenType string          `json:"token_type,omitempty"`
	TokenUse  string          `json:"token_use,omitempty"`
	Ext       json.RawMessage `json:"ext,omitempty"`
}

Introspection is a token's state.

type JWK

type JWK struct {
	KID string   `json:"kid"`
	Alg string   `json:"alg"`
	Use string   `json:"use"`
	Kty string   `json:"kty"`
	Crv string   `json:"crv,omitempty"`
	X5C []string `json:"x5c,omitempty"`
}

JWK is a JSON Web Key; private parts are never kept by this package.

type LoginRequest

type LoginRequest struct {
	Challenge      string          `json:"challenge"`
	Subject        string          `json:"subject,omitempty"`
	Skip           bool            `json:"skip"`
	Client         OAuth2Client    `json:"client"`
	RequestedScope []string        `json:"requested_scope,omitempty"`
	OIDCContext    json.RawMessage `json:"oidc_context,omitempty"`
	SessionID      string          `json:"session_id,omitempty"`
	RequestURL     string          `json:"request_url,omitempty"`
}

LoginRequest is a pending login.

type LogoutRequest

type LogoutRequest struct {
	Challenge   string        `json:"challenge"`
	Subject     string        `json:"subject"`
	SID         string        `json:"sid,omitempty"`
	RPInitiated bool          `json:"rp_initiated"`
	Client      *OAuth2Client `json:"client,omitempty"`
	RequestURL  string        `json:"request_url,omitempty"`
}

LogoutRequest is a pending logout.

type OAuth2Client

type OAuth2Client struct {
	ClientID                string          `json:"client_id,omitempty"`
	ClientName              string          `json:"client_name,omitempty"`
	ClientSecret            string          `json:"client_secret,omitempty"              schemapb:"secret=true"`
	ClientSecretExpiresAt   int64           `json:"client_secret_expires_at,omitempty"`
	GrantTypes              []string        `json:"grant_types,omitempty"`
	ResponseTypes           []string        `json:"response_types,omitempty"`
	RedirectURIs            []string        `json:"redirect_uris,omitempty"`
	PostLogoutRedirectURIs  []string        `json:"post_logout_redirect_uris,omitempty"`
	Scope                   string          `json:"scope,omitempty"`
	Audience                []string        `json:"audience,omitempty"`
	TokenEndpointAuthMethod string          `json:"token_endpoint_auth_method,omitempty"`
	AccessTokenStrategy     string          `json:"access_token_strategy,omitempty"`
	SkipConsent             bool            `json:"skip_consent,omitempty"`
	SkipLogoutConsent       *bool           `json:"skip_logout_consent,omitempty"`
	SubjectType             string          `json:"subject_type,omitempty"`
	Owner                   string          `json:"owner,omitempty"`
	Contacts                []string        `json:"contacts,omitempty"`
	ClientURI               string          `json:"client_uri,omitempty"`
	LogoURI                 string          `json:"logo_uri,omitempty"`
	PolicyURI               string          `json:"policy_uri,omitempty"`
	TOSURI                  string          `json:"tos_uri,omitempty"`
	AllowedCORSOrigins      []string        `json:"allowed_cors_origins,omitempty"`
	JWKSURI                 string          `json:"jwks_uri,omitempty"`
	JWKS                    json.RawMessage `json:"jwks,omitempty"`
	FrontchannelLogoutURI   string          `json:"frontchannel_logout_uri,omitempty"`
	BackchannelLogoutURI    string          `json:"backchannel_logout_uri,omitempty"`
	Metadata                json.RawMessage `json:"metadata,omitempty"`
	CreatedAt               *time.Time      `json:"created_at,omitempty"`
	UpdatedAt               *time.Time      `json:"updated_at,omitempty"`

	// Raw is the whole client as Hydra sent it: every field, those above
	// and the rest (lifespans, request objects, signing algorithms).
	Raw json.RawMessage `json:"-"`
}

Client of OAuth 2.0 as Hydra stores it; Hydra owns the JSON, the fields here are what backplane-hydra reads.

func (*OAuth2Client) UnmarshalJSON added in v0.0.2

func (c *OAuth2Client) UnmarshalJSON(b []byte) error

UnmarshalJSON keeps the raw client next to the fields.

func (OAuth2Client) WithoutSecret added in v0.0.2

func (c OAuth2Client) WithoutSecret() json.RawMessage

WithoutSecret is the raw client without its secret.

type Options

type Options struct {
	// Admin and Public are the base URLs of the APIs.
	Admin, Public string
	// Headers go with every request (a proxy's authorization).
	Headers map[string]string
	// Timeout of one request; default 10s.
	Timeout time.Duration
	// Transport overrides the HTTP transport (tests).
	Transport http.RoundTripper
}

Options of New.

type Page

type Page[T any] struct {
	Items []T
	Next  string
}

Page is one page of a listing and the token of the next ("" at the end).

type Reject

type Reject struct {
	Error            string `json:"error"`
	ErrorDescription string `json:"error_description,omitempty"`
	ErrorHint        string `json:"error_hint,omitempty"`
	StatusCode       int    `json:"status_code,omitempty"`
}

Reject is Hydra's rejectOAuth2Request.

type TrustedIssuer

type TrustedIssuer struct {
	ID              string     `json:"id"`
	Issuer          string     `json:"issuer"`
	Subject         string     `json:"subject,omitempty"`
	AllowAnySubject bool       `json:"allow_any_subject,omitempty"`
	Scope           []string   `json:"scope"`
	ExpiresAt       *time.Time `json:"expires_at,omitempty"`
	CreatedAt       *time.Time `json:"created_at,omitempty"`
	PublicKey       struct {
		KID string `json:"kid"`
		Set string `json:"set"`
	} `json:"public_key"`
}

TrustedIssuer may sign JWT bearer grants.

Jump to

Keyboard shortcuts

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