Documentation
¶
Overview ¶
Package hydra is a thin admin-API client for Ory Hydra. We use it to drive the four endpoints that a custom login/consent UI must hit during an OAuth2/OIDC flow:
GET /admin/oauth2/auth/requests/login — read challenge PUT /admin/oauth2/auth/requests/login/accept — finish login GET /admin/oauth2/auth/requests/consent — read challenge PUT /admin/oauth2/auth/requests/consent/accept — finish consent
The package is a no-op when not configured (NewFromEnv returns a nil client when HYDRA_ADMIN_URL is unset). Callers must check Enabled() before relying on it.
We deliberately do not pull in github.com/ory/hydra-client-go: the surface we need is tiny, and the upstream client adds a transitive dependency tree larger than the rest of internal/* combined. The raw structs below cover only the fields we read.
Index ¶
- Variables
- type AcceptConsentRequest
- type AcceptLoginRequest
- type Client
- func (c *Client) AcceptConsentRequest(ctx context.Context, challenge string, body AcceptConsentRequest) (*Redirect, error)
- func (c *Client) AcceptLoginRequest(ctx context.Context, challenge string, body AcceptLoginRequest) (*Redirect, error)
- func (c *Client) Enabled() bool
- func (c *Client) GetConsentRequest(ctx context.Context, challenge string) (*ConsentRequest, error)
- func (c *Client) GetLoginRequest(ctx context.Context, challenge string) (*LoginRequest, error)
- type ClientInfo
- type Config
- type ConsentRequest
- type LoginRequest
- type OIDCContext
- type Redirect
- type Session
Constants ¶
This section is empty.
Variables ¶
var ErrBadChallenge = errors.New("hydra: unknown or used challenge")
ErrBadChallenge wraps the error for a login or consent challenge Hydra does not accept: unknown, expired or already used.
Functions ¶
This section is empty.
Types ¶
type AcceptConsentRequest ¶
type AcceptConsentRequest struct {
GrantScope []string `json:"grant_scope"`
GrantAccessTokenAudience []string `json:"grant_access_token_audience,omitempty"`
Remember bool `json:"remember"`
RememberFor int64 `json:"remember_for,omitempty"`
Session *Session `json:"session,omitempty"`
}
AcceptConsentRequest is the body for PUT /admin/oauth2/auth/requests/consent/accept.
type AcceptLoginRequest ¶
type AcceptLoginRequest struct {
Subject string `json:"subject"`
Remember bool `json:"remember"`
RememberFor int64 `json:"remember_for,omitempty"`
ACR string `json:"acr,omitempty"`
AMR []string `json:"amr,omitempty"`
Context map[string]any `json:"context,omitempty"`
}
AcceptLoginRequest is the body for PUT /admin/oauth2/auth/requests/login/accept.
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client is the Hydra admin client. nil is safe — Enabled() returns false and all calls return an error rather than panic.
func NewFromEnv ¶
NewFromEnv builds a Client from environment variables. Returns (nil, nil) when HYDRA_ADMIN_URL is unset so callers can wire it up unconditionally.
Recognised env vars:
HYDRA_ADMIN_URL — required to enable HYDRA_TIMEOUT — Go duration; default 10s
func (*Client) AcceptConsentRequest ¶
func (c *Client) AcceptConsentRequest(ctx context.Context, challenge string, body AcceptConsentRequest) (*Redirect, error)
AcceptConsentRequest finishes the consent phase. For a first-party app every requested scope is auto-granted by the caller.
func (*Client) AcceptLoginRequest ¶
func (c *Client) AcceptLoginRequest(ctx context.Context, challenge string, body AcceptLoginRequest) (*Redirect, error)
AcceptLoginRequest finishes the login phase and returns the URL the user-agent must be redirected to (typically on to consent).
func (*Client) GetConsentRequest ¶
GetConsentRequest fetches the consent challenge from Hydra.
func (*Client) GetLoginRequest ¶
GetLoginRequest fetches the login challenge from Hydra.
type ClientInfo ¶
type ClientInfo struct {
ClientID string `json:"client_id"`
ClientName string `json:"client_name"`
Scope string `json:"scope"`
GrantTypes []string `json:"grant_types"`
}
ClientInfo is the subset of the OAuth2 client metadata we surface to the login UI (mostly the display name).
type Config ¶
type Config struct {
// AdminURL is the Hydra admin API base, e.g.
// http://ory-hydra-admin.ory.svc:4445. Required.
AdminURL string
// Timeout for individual HTTP calls. Default 10s.
Timeout time.Duration
// HTTPClient is optional; one is constructed from Timeout when nil.
HTTPClient *http.Client
}
Config holds runtime knobs for the Hydra admin client.
type ConsentRequest ¶
type ConsentRequest struct {
Challenge string `json:"challenge"`
Subject string `json:"subject"`
Skip bool `json:"skip"`
Client ClientInfo `json:"client"`
RequestedScope []string `json:"requested_scope"`
RequestedAccessTokenAudience []string `json:"requested_access_token_audience"`
OIDCContext OIDCContext `json:"oidc_context"`
Context map[string]any `json:"context"`
Acr string `json:"acr"`
Amr []string `json:"amr"`
GrantedScope []string `json:"granted_scope"`
IdentityClaims map[string]any `json:"-"`
LoginChallenge string `json:"login_challenge"`
LoginSessionID string `json:"login_session_id"`
IDTokenHintClaims map[string]any `json:"id_token_hint_claims"`
}
ConsentRequest is the subset of the Hydra consent challenge we read.
type LoginRequest ¶
type LoginRequest struct {
Challenge string `json:"challenge"`
Subject string `json:"subject"`
Skip bool `json:"skip"`
RequestURL string `json:"request_url"`
RequestedScope []string `json:"requested_scope"`
Client ClientInfo `json:"client"`
OIDCContext OIDCContext `json:"oidc_context"`
SessionID string `json:"session_id"`
}
LoginRequest is the subset of the Hydra login challenge we read. See https://www.ory.com/docs/hydra/reference/api for the full list.
type OIDCContext ¶
type OIDCContext struct {
ACRValues []string `json:"acr_values"`
UILocales []string `json:"ui_locales"`
Display string `json:"display"`
IDTokenHintClaims map[string]any `json:"id_token_hint_claims"`
LoginHint string `json:"login_hint"`
}
OIDCContext is the OIDC parameters set on the original auth request — `id_token_hint`, `display`, `login_hint`, `ui_locales`.
type Redirect ¶
type Redirect struct {
RedirectTo string `json:"redirect_to"`
}
Redirect is the response shape from any /accept endpoint.
type Session ¶
type Session struct {
IDToken map[string]any `json:"id_token,omitempty"`
AccessToken map[string]any `json:"access_token,omitempty"`
}
Session is the optional id_token / access_token claim payload returned to the client. We send the bare minimum (sub claim is implicit) and let downstream apps query Kratos for richer profile.
Source Files