Documentation
¶
Overview ¶
Package rp provides an OpenID Connect Relying Party to build authentication gateways with Fox, such as Backend for Frontend (BFF) with Frontend or Identity-Aware Proxy (IAP) with Proxy.
Index ¶
- Constants
- Variables
- func AccessToken(ctx context.Context) (*oauth2.Token, bool)
- func AllowAnonymous() fox.RouteOption
- func DefaultForbidden(c *fox.Context)
- func DefaultUnauthorized(c *fox.Context)
- func ForResource(resources ...string) fox.RouteOption
- func Require(rules ...Rule) fox.RouteOption
- func ResourceAccessToken(ctx context.Context, resource string) (*oauth2.Token, bool)
- func ResourceTransport(base http.RoundTripper, resource string) http.RoundTripper
- func Transport(base http.RoundTripper) http.RoundTripper
- func UserClaims(ctx context.Context) (map[string]any, bool)
- type AEAD
- type Client
- type Frontend
- func (fe *Frontend) Authenticate() fox.MiddlewareFunc
- func (fe *Frontend) BackchannelHandler() fox.HandlerFunc
- func (fe *Frontend) CallbackHandler() fox.HandlerFunc
- func (fe *Frontend) LoginHandler() fox.HandlerFunc
- func (fe *Frontend) LogoutHandler() fox.HandlerFunc
- func (fe *Frontend) UserHandler() fox.HandlerFunc
- type FrontendOption
- type Option
- func WithAbsoluteTimeout(d time.Duration) Option
- func WithDPoP(enable bool) Option
- func WithIdleTimeout(d time.Duration) Option
- func WithLogHandler(h slog.Handler) Option
- func WithPushedAuthorization(mode PushedAuthorization) Option
- func WithRequestObject(enable bool) Option
- func WithResources(resources ...string) Option
- func WithSigningAlgorithms(algs ...string) Option
- func WithStore(s store.Store) Option
- func WithUnauthorizedHandler(handler fox.HandlerFunc) Option
- func WithUserInfo(enable bool) Option
- type Provider
- type ProviderOption
- type Proxy
- type ProxyOption
- type PushedAuthorization
- type Rule
Constants ¶
const ( // DefaultIdleTimeout is the default idle timeout of a session. DefaultIdleTimeout = 30 * time.Minute // DefaultAbsoluteTimeout is the default absolute timeout of a session. DefaultAbsoluteTimeout = 8 * time.Hour )
Variables ¶
var ErrInvalidConfig = errors.New("invalid config")
Functions ¶
func AccessToken ¶
AccessToken returns the access token of a request authenticated by Frontend.Authenticate or Proxy.Authenticate. It returns false for an anonymous request and for a request not handled by the middleware. A DPoP-bound access token must be sent with Transport.
func AllowAnonymous ¶
func AllowAnonymous() fox.RouteOption
AllowAnonymous returns a fox.RouteOption that lets Frontend.Authenticate and Proxy.Authenticate pass the requests without a session to the next handler. For these requests, AccessToken and ResourceAccessToken return false, and Transport and ResourceTransport do not add an access token.
func DefaultForbidden ¶ added in v0.7.0
DefaultForbidden responds with 403 Forbidden.
func DefaultUnauthorized ¶
DefaultUnauthorized responds with 401 Unauthorized.
func ForResource ¶
func ForResource(resources ...string) fox.RouteOption
ForResource returns a fox.RouteOption that lets Frontend.Authenticate and Proxy.Authenticate obtain the access tokens of the resources for the next handler, as defined by RFC 8707. The resources must be declared with WithResources.
func Require ¶
func Require(rules ...Rule) fox.RouteOption
Require returns a fox.RouteOption that lets Proxy.Authenticate respond with 403 Forbidden to a user who is not granted access by all the rules, in addition to the rules of WithAccessRule. Frontend.Authenticate responds with 500 Internal Server Error to a route with rules. It panics if a rule is nil.
func ResourceAccessToken ¶
ResourceAccessToken returns the access token of the resource for a request authenticated by Frontend.Authenticate or Proxy.Authenticate, as defined by RFC 8707. It returns false for an anonymous request, for a request not handled by the middleware and for a resource that the route does not declare with ForResource. A DPoP-bound access token must be sent with ResourceTransport.
func ResourceTransport ¶
func ResourceTransport(base http.RoundTripper, resource string) http.RoundTripper
ResourceTransport returns an http.RoundTripper that sets the Authorization header with the access token of the resource, as returned by ResourceAccessToken. For a DPoP-bound access token, it also adds a DPoP proof. It does not add an access token to an anonymous request or to a request for a resource that the route does not declare with ForResource. A nil base uses http.DefaultTransport.
func Transport ¶
func Transport(base http.RoundTripper) http.RoundTripper
Transport returns an http.RoundTripper that sets the Authorization header with the access token of the request, as returned by AccessToken. For a DPoP-bound access token, it also adds a DPoP proof. It does not add an access token to an anonymous request. A nil base uses http.DefaultTransport.
func UserClaims ¶
UserClaims returns the claims about the user of a request authenticated by Frontend.Authenticate or Proxy.Authenticate, as returned by Frontend.UserHandler. It returns false for an anonymous request and for a request not handled by the middleware.
Types ¶
type AEAD ¶
type AEAD interface {
Encrypt(plaintext, associatedData []byte) ([]byte, error)
Decrypt(ciphertext, associatedData []byte) ([]byte, error)
}
AEAD provides authenticated encryption with associated data. A Frontend uses it to encrypt its sessions. Key rotation is the responsibility of the implementation.
type Client ¶
type Client struct {
// Provider is the OpenID Provider the client is registered with.
Provider *Provider
// ClientID is the client identifier.
ClientID string
// ClientSecret is the client secret, sent with client_secret_basic.
ClientSecret string
// ClientKey is the private key that authenticates the client with private_key_jwt. It must be an ECDSA P-256 key,
// an RSA key of at least 2048 bits or an Ed25519 key. A client has either a secret or a key.
ClientKey crypto.Signer
// ClientKeyID is the optional ID of the client key, sent in the assertions.
ClientKeyID string
// RedirectURL is the URL the provider redirects the user to after login, where [Frontend.CallbackHandler] is served.
RedirectURL string
// PostLogoutRedirectURL is the optional URL the provider redirects the user to after logout.
PostLogoutRedirectURL string
// Scopes specifies the requested scopes. It must include openid.
Scopes []string
}
Client is the configuration of an OpenID Connect Relying Party, a confidential OAuth 2.0 client registered with the provider. Its URLs must use https, except for a loopback host.
type Frontend ¶
type Frontend struct {
// contains filtered or unexported fields
}
Frontend is the BFF of a browser-based application, with its own OpenID Connect client and user sessions.
func NewFrontend ¶
func NewFrontend(client Client, aead AEAD, opts ...FrontendOption) (*Frontend, error)
NewFrontend returns a Frontend for the OpenID Connect client.
The aead encrypts the data the frontend stores in cookies and in its store, such as the access, refresh and ID tokens. When the frontend is served by several replicas, they must all use the same keys.
func (*Frontend) Authenticate ¶
func (fe *Frontend) Authenticate() fox.MiddlewareFunc
Authenticate returns a middleware that authenticates the requests with the session cookie and refreshes the access tokens before they expire, including the tokens of the route resources (see ForResource). A request without a valid session is handled by the unauthorized handler (see WithUnauthorizedHandler), unless the route has AllowAnonymous. Use AccessToken or ResourceAccessToken to retrieve the tokens in the next handler.
To prevent cross-site request forgery, the middleware responds with 403 Forbidden to a cross-origin request with an unsafe method, except from the trusted origins (see WithTrustedOrigins), and to a request without the header configured with WithCSRFHeader.
func (*Frontend) BackchannelHandler ¶
func (fe *Frontend) BackchannelHandler() fox.HandlerFunc
BackchannelHandler returns a handler that ends the sessions designated by a logout token, as defined by OpenID Connect Back-Channel Logout. The provider must call it with a POST request. It panics if the frontend has no store.
func (*Frontend) CallbackHandler ¶
func (fe *Frontend) CallbackHandler() fox.HandlerFunc
CallbackHandler returns the handler of the redirect URL. It completes the login, creates a new session and redirects to the return URL. If the provider returns an error, such as login_required for prompt=none, it redirects to the return URL without a new session.
func (*Frontend) LoginHandler ¶
func (fe *Frontend) LoginHandler() fox.HandlerFunc
LoginHandler returns a handler that starts the authorization code flow with the provider. The browser must open it with a top-level navigation, because the flow redirects the browser to the provider. After login, the browser is redirected to the URL in the returnUrl query parameter, or to "/" if it is absent. The return URL must be a local URL or a URL of a trusted origin (see WithTrustedOrigins), of at most 1024 bytes once encoded as JSON. The optional prompt, max_age and acr_values query parameters are passed to the provider, such as prompt=none for a silent login.
When Pushed Authorization Requests (PAR, RFC 9126) are used, each login sends a request to the pushed authorization request endpoint of the provider, so the route should be rate limited. If this request fails, the handler responds with 502 Bad Gateway.
func (*Frontend) LogoutHandler ¶
func (fe *Frontend) LogoutHandler() fox.HandlerFunc
LogoutHandler returns a handler that ends the session, revokes its refresh token and redirects to the end session endpoint of the provider, as defined by OpenID Connect RP-Initiated Logout. The browser navigates to it with the csrf_token query parameter or form field, set to the logoutCsrfToken returned by Frontend.UserHandler.
func (*Frontend) UserHandler ¶
func (fe *Frontend) UserHandler() fox.HandlerFunc
UserHandler returns a handler that responds with a JSON object describing the session of the user, such as
{
"claims": {"sub": "248289761001", "name": "Jane Doe", "email": "janedoe@example.com"},
"logoutCsrfToken": "pNmKN2uL7x0Hbf3Sx9VTq2nqZ2bJ1ws6Zx1cA5tDqKE",
"expiresIn": 1800
}
The logoutCsrfToken member is the CSRF token expected by Frontend.LogoutHandler, and expiresIn is the number of seconds before the session ends. The application calls it from JavaScript, with the header of WithCSRFHeader when this option is set. A request without a session gets the response of the unauthorized handler.
type FrontendOption ¶
type FrontendOption interface {
// contains filtered or unexported methods
}
FrontendOption configures a Frontend.
func WithCSRFHeader ¶
func WithCSRFHeader(name, value string) FrontendOption
WithCSRFHeader requires the header with the given value on the requests handled by Frontend.Authenticate and Frontend.UserHandler. A browser sends a cross-origin request with a custom header only after a CORS preflight, which prevents cross-site request forgery (RFC 10017, Section 6.1.3.3.2).
func WithTrustedOrigins ¶
func WithTrustedOrigins(origins ...string) FrontendOption
WithTrustedOrigins accepts the requests from the given origins, for a browser-based application that is cross-origin with the BFF, and lets a login return to a URL of these origins. An origin has the form "scheme://host[:port]" sent in the Origin header, in lowercase and without the default port, with https or, on a loopback host, http. The application and the BFF must be same site, such as https://app.example.com and https://bff.example.com, as the session cookie is SameSite=Strict. NewFrontend fails if an origin is not same site with the redirect URL of the client. A CORS middleware must allow only these origins, with credentials. The BFF should also require the header of WithCSRFHeader, as recommended by RFC 10017.
type Option ¶
type Option interface {
FrontendOption
ProxyOption
}
Option configures a Frontend or a Proxy.
func WithAbsoluteTimeout ¶
WithAbsoluteTimeout sets the maximum lifetime of a session. The default is DefaultAbsoluteTimeout.
func WithDPoP ¶
WithDPoP binds the access tokens to a key generated for each session, as defined by RFC 9449. The remote APIs must accept DPoP-bound access tokens. Changing this option ends the existing sessions.
func WithIdleTimeout ¶
WithIdleTimeout sets the duration of inactivity after which a session ends. The default is DefaultIdleTimeout.
func WithLogHandler ¶
WithLogHandler sets the handler of the logs written when a request is rejected or fails. By default, nothing is logged.
func WithPushedAuthorization ¶
func WithPushedAuthorization(mode PushedAuthorization) Option
WithPushedAuthorization sets when the authorization requests are pushed to the provider. The default is PushedAuthorizationIfAvailable.
func WithRequestObject ¶
WithRequestObject sends the authorization parameters in a request object signed with the client key, as defined by RFC 9101. NewFrontend and NewProxy fail if the client has no key or if the authorization requests are not pushed to the provider. They also fail if the provider requires request objects and this option is disabled.
func WithResources ¶
WithResources declares the protected resources the frontend requests access tokens for, as defined by RFC 8707. Each resource is an absolute URI without fragment, usually the base URI of an API. The resources are requested at login, and a route obtains the access tokens of its resources with ForResource.
func WithSigningAlgorithms ¶
WithSigningAlgorithms restricts the algorithms accepted for the signature of the ID tokens and logout tokens. They should include the algorithm registered for the client at the provider. By default, the algorithms advertised by the provider are accepted.
func WithStore ¶
WithStore enables stateful sessions, stored in s. The session cookie then contains only the session ID. By default, sessions are stateless and stored in the cookie. Frontend.BackchannelHandler and Proxy.BackchannelHandler require a store.
func WithUnauthorizedHandler ¶
func WithUnauthorizedHandler(handler fox.HandlerFunc) Option
WithUnauthorizedHandler sets the handler called for the requests without a valid session. A Proxy calls it only for the requests that are not navigations. The default is DefaultUnauthorized.
func WithUserInfo ¶
WithUserInfo requests the UserInfo endpoint at login and after each refresh, and adds its claims to the claims of the user, such as the ones returned by UserClaims.
type Provider ¶
type Provider struct {
// contains filtered or unexported fields
}
Provider is an OpenID Provider configured from its metadata. A Provider can be shared by several clients.
func NewProvider ¶
NewProvider retrieves the provider metadata of the issuer with OpenID Connect Discovery. The issuer must use https, except for a loopback host.
type ProviderOption ¶
type ProviderOption interface {
// contains filtered or unexported methods
}
ProviderOption configures a Provider.
func WithEndSessionEndpoint ¶
func WithEndSessionEndpoint(endpoint string) ProviderOption
WithEndSessionEndpoint sets the end session endpoint of OpenID Connect RP-Initiated Logout, for a provider that supports it without publishing it. It replaces the endpoint of the provider metadata.
func WithHTTPClient ¶
func WithHTTPClient(client *http.Client) ProviderOption
WithHTTPClient sets the HTTP client used for the requests to the provider. The default client uses http.DefaultTransport with a timeout of 10 seconds.
func WithRevocationEndpoint ¶
func WithRevocationEndpoint(endpoint string) ProviderOption
WithRevocationEndpoint sets the token revocation endpoint (RFC 7009), for a provider that supports it without publishing it. It replaces the endpoint of the provider metadata.
type Proxy ¶
type Proxy struct {
// contains filtered or unexported fields
}
Proxy authenticates the users of the upstream servers it is put in front of, with its own OpenID Connect client and user sessions.
func NewProxy ¶
func NewProxy(client Client, aead AEAD, opts ...ProxyOption) (*Proxy, error)
NewProxy returns a Proxy for the OpenID Connect client. A proxy serves the host of the redirect URL of the client, or the hosts of its cookie domain (see WithCookieDomain).
The aead encrypts the data the proxy stores in cookies and in its store, such as the access, refresh and ID tokens. When the proxy is served by several replicas, they must all use the same keys.
func (*Proxy) Authenticate ¶
func (p *Proxy) Authenticate() fox.MiddlewareFunc
Authenticate returns a middleware that authenticates the requests with the session cookie and refreshes the access tokens before they expire, including the tokens of the route resources (see ForResource). A GET or HEAD request without a valid session, with the Sec-Fetch-Mode header set to navigate and the Sec-Fetch-Dest header set to document, starts the login, which then returns to the URL of the request. The other requests without a valid session are handled by the unauthorized handler (see WithUnauthorizedHandler), unless the route has AllowAnonymous.
The middleware calls the forbidden handler (see WithForbiddenHandler) when a rule of WithAccessRule or Require denies access to the user, and responds with 403 Forbidden to a cross-origin request with an unsafe method and a session. On a route with AllowAnonymous, a user denied access by a rule is handled as a request without a session. The middleware sets the headers of WithIdentityHeader on the request passed to the next handler.
When Pushed Authorization Requests (PAR, RFC 9126) are used, each login sends a request to the pushed authorization request endpoint of the provider. If this request fails, the middleware responds with 502 Bad Gateway.
func (*Proxy) BackchannelHandler ¶
func (p *Proxy) BackchannelHandler() fox.HandlerFunc
BackchannelHandler returns a handler that ends the sessions designated by a logout token, as defined by OpenID Connect Back-Channel Logout. The provider must call it with a POST request. It panics if the proxy has no store.
func (*Proxy) CallbackHandler ¶
func (p *Proxy) CallbackHandler() fox.HandlerFunc
CallbackHandler returns the handler of the redirect URL. It completes the login, creates a new session and redirects to the URL of the request that started the login. It calls the forbidden handler (see WithForbiddenHandler) without a session if the provider returns an error, such as access_denied, or if a rule of WithAccessRule denies access to the user.
func (*Proxy) LogoutHandler ¶
func (p *Proxy) LogoutHandler() fox.HandlerFunc
LogoutHandler returns a handler that ends the session, revokes its refresh token and redirects to the end session endpoint of the provider, as defined by OpenID Connect RP-Initiated Logout. The browser must navigate to it from the same origin, with any method.
type ProxyOption ¶
type ProxyOption interface {
// contains filtered or unexported methods
}
ProxyOption configures a Proxy.
func WithAccessRule ¶
func WithAccessRule(rule Rule) ProxyOption
WithAccessRule requires the rule to grant access to the user, at login and on each request handled by Proxy.Authenticate. The rules of several calls must all grant access.
func WithCookieDomain ¶
func WithCookieDomain(domain string) ProxyOption
WithCookieDomain shares the sessions of the proxy between the hosts of the domain, such as apps.example.com for app1.apps.example.com and app2.apps.example.com. The login completes on the host of the redirect URL, which must be in the domain. NewProxy fails if the domain is a public suffix. The proxy responds with 500 Internal Server Error to a request for a host outside the domain.
func WithForbiddenHandler ¶ added in v0.7.0
func WithForbiddenHandler(handler fox.HandlerFunc) ProxyOption
WithForbiddenHandler sets the handler called when a Proxy denies access to the user, by a rule of WithAccessRule or Require, or by an error of the provider at the callback. The default is DefaultForbidden.
func WithIdentityHeader ¶
func WithIdentityHeader(name, claim string) ProxyOption
WithIdentityHeader sets the header of the given name on the requests passed to the next handler of Proxy.Authenticate, with the value of a claim of the user. A string claim is sent as is, a number or a boolean is formatted as in JSON, and an array of strings is joined with commas. The header is omitted when the request has no session, when the claim has another type and when its value has characters invalid in a header. The middleware always removes the header from the incoming request, including its form with underscores in place of dashes.
type PushedAuthorization ¶
type PushedAuthorization uint8
PushedAuthorization defines when a Frontend or a Proxy pushes its authorization requests to the provider, as defined by RFC 9126.
const ( // PushedAuthorizationIfAvailable pushes the authorization requests when the provider has a pushed authorization // request endpoint. PushedAuthorizationIfAvailable PushedAuthorization = iota // PushedAuthorizationRequired pushes the authorization requests. [NewFrontend] and [NewProxy] fail if the provider // has no pushed authorization request endpoint. PushedAuthorizationRequired // PushedAuthorizationDisabled never pushes the authorization requests. [NewFrontend] and [NewProxy] fail if the // provider requires pushed authorization requests. PushedAuthorizationDisabled )
type Rule ¶
Rule reports whether the user with the given claims has access. The claims are the ones of UserClaims.
func Claim ¶
Claim returns a Rule that grants access to a user whose claim is one of the values, or an array that contains one of the values.
func Email ¶
Email returns a Rule that grants access to a user with one of the verified email addresses.
func EmailDomain ¶
EmailDomain returns a Rule that grants access to a user with a verified email address of one of the domains.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
internal
|
|
|
oidctest
Package oidctest provides an OpenID Connect provider for tests.
|
Package oidctest provides an OpenID Connect provider for tests. |
|
Package store defines the interface between stateful frontends and their session storage.
|
Package store defines the interface between stateful frontends and their session storage. |
|
memory
Package memory provides a store.Store that keeps the sessions in memory.
|
Package memory provides a store.Store that keeps the sessions in memory. |
|
storetest
Package storetest tests implementations of store.Store.
|
Package storetest tests implementations of store.Store. |
|
redis
module
|