Help us shape the future of Go! Take the 2026 Go Developer Survey

bff

package module
v0.5.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 31, 2026 License: MIT Imports: 38 Imported by: 0

README

Go Reference tests codecov GitHub release (latest SemVer) GitHub go.mod Go version

BFF

BFF is an OpenID Connect Relying Party and OAuth 2.0 client for the Fox router. It provides a set of handlers and middleware to build a Backend For Frontend, the server-side gateway between a browser application and its APIs, as described in OAuth 2.0 for Browser-Based Applications.

Disclaimer

The current API is not yet stabilized. Breaking changes may occur before v1.0.0 and will be noted on the release note.

Getting started

Installation
go get -u github.com/fox-toolkit/bff
Usage
package main

import (
	"context"
	"log"
	"net/http"
	"net/http/httputil"
	"net/url"
	"os"

	"github.com/fox-toolkit/bff"
	"github.com/fox-toolkit/fox"
	"github.com/tink-crypto/tink-go/v2/aead/subtle"
)

func main() {
	provider, err := bff.NewProvider(context.Background(), "https://idp.example.com")
	if err != nil {
		log.Fatal(err)
	}
	
	aead, err := subtle.NewAESGCM([]byte(os.Getenv("BFF_KEY")))
	if err != nil {
		log.Fatal(err)
	}

	fe, err := bff.NewFrontend(bff.Client{
		Provider:              provider,
		ClientID:              "app",
		ClientSecret:          os.Getenv("CLIENT_SECRET"),
		RedirectURL:           "https://app.example.com/bff/callback",
		PostLogoutRedirectURL: "https://app.example.com/",
		Scopes:                []string{"openid", "profile"},
	}, aead)
	if err != nil {
		log.Fatal(err)
	}
	
	api, _ := url.Parse("https://api.example.com")
	proxy := &httputil.ReverseProxy{
		Rewrite:   func(r *httputil.ProxyRequest) { r.SetURL(api) },
		Transport: bff.Transport(nil),
	}

	f := fox.MustRouter()
	f.MustAdd(fox.MethodGet, "/bff/login", fe.LoginHandler())
	f.MustAdd(fox.MethodGet, "/bff/callback", fe.CallbackHandler())
	f.MustAdd([]string{http.MethodGet, http.MethodPost}, "/bff/logout", fe.LogoutHandler())
	f.MustAdd(fox.MethodGet, "/bff/user", fe.UserHandler())
	
	// Proxy to the resource server, with the user's access token.
	f.MustAdd(fox.MethodAny, "/api/*{path}", fox.WrapH(proxy), fox.WithMiddleware(fe.Authenticate()))

	// The browser-based application is served here by the BFF. For other deployments, see
	// https://www.rfc-editor.org/rfc/rfc10017.html#section-6.1.2.5. A cross-origin
	// application requires bff.WithTrustedOrigins and a CORS middleware that allows its origin with credentials.
	f.MustAdd(fox.MethodGet, "/*{filepath}", fox.WrapH(http.FileServer(http.Dir("dist"))))
	
	log.Fatal(http.ListenAndServeTLS(":8443", "cert.pem", "key.pem", f))
}

Open Standards

BFF implements Open Standards set by the IETF:

and the OpenID Foundation:

Conformance

BFF passes the client test plans of the OpenID Foundation conformance suite v5.3.4 (see the conformance module). The FAPI 2.0 Security Profile and FAPI 2.0 Message Signing plans use the configuration below, and the OpenID Connect Basic, Config, refresh token, Back-Channel Logout and RP-Initiated Logout plans use a client secret.

fe, err := bff.NewFrontend(bff.Client{
	Provider:    provider,
	ClientID:    "app",
	ClientKey:   key, // EC P-256, RSA or Ed25519 private key
	RedirectURL: "https://app.example.com/bff/callback",
	Scopes:      []string{"openid"},
}, aead,
	bff.WithPushedAuthorization(bff.PushedAuthorizationRequired),
	bff.WithDPoP(true),
	bff.WithRequestObject(true), // FAPI 2.0 Message Signing only
	bff.WithSigningAlgorithms("PS256", "ES256", "EdDSA"),
)

Documentation

Overview

Package bff provides the building blocks of a Backend for Frontend (BFF) for Fox.

Index

Constants

View Source 
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

View Source 
var ErrInvalidConfig = errors.New("invalid config")

Functions

func AccessToken 

func AccessToken(ctx context.Context) (*oauth2.Token, bool)

AccessToken returns the access token of a request authenticated by Frontend.Authenticate. It reports 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 pass the requests without a session to the next handler. For these requests, AccessToken and ResourceAccessToken report false, and Transport and ResourceTransport do not add an access token.

func DefaultUnauthorized 

func DefaultUnauthorized(c *fox.Context)

DefaultUnauthorized responds with 401 Unauthorized.

func ForResource added in v0.5.0 

func ForResource(resources ...string) fox.RouteOption

ForResource returns a fox.RouteOption that lets Frontend.Authenticate obtain the access tokens of the resources for the next handler, as defined by RFC 8707. The resources must be declared with WithResources. When a route has several ForResource options, the last one applies.

func ResourceAccessToken 

func ResourceAccessToken(ctx context.Context, resource string) (*oauth2.Token, bool)

ResourceAccessToken returns the access token of the resource for a request authenticated by Frontend.Authenticate, as defined by RFC 8707. It reports 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 

func UserClaims(ctx context.Context) (map[string]any, bool)

UserClaims returns the claims about the user of a request authenticated by Frontend.Authenticate, as returned by Frontend.UserHandler. It reports 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 ...Option) (*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 Option 

type Option interface {
	// contains filtered or unexported methods
}

Option configures a Frontend.

func WithAbsoluteTimeout 

func WithAbsoluteTimeout(d time.Duration) Option

WithAbsoluteTimeout sets the maximum lifetime of a session. The default is DefaultAbsoluteTimeout.

func WithCSRFHeader 

func WithCSRFHeader(name, value string) Option

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 WithDPoP 

func WithDPoP(enable bool) Option

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 

func WithIdleTimeout(d time.Duration) Option

WithIdleTimeout sets the duration of inactivity after which a session ends. The default is DefaultIdleTimeout.

func WithLogHandler 

func WithLogHandler(h slog.Handler) Option

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 

func WithRequestObject(enable bool) Option

WithRequestObject sends the authorization parameters in a request object signed with the client key, as defined by RFC 9101. NewFrontend fails if the client has no key or if the authorization requests are not pushed to the provider. It also fails if the provider requires request objects and this option is disabled.

func WithResources 

func WithResources(resources ...string) Option

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 

func WithSigningAlgorithms(algs ...string) Option

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 

func WithStore(s store.Store) Option

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 requires a store.

func WithTrustedOrigins 

func WithTrustedOrigins(origins ...string) Option

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.

func WithUnauthorizedHandler 

func WithUnauthorizedHandler(handler fox.HandlerFunc) Option

WithUnauthorizedHandler sets the handler called for the requests without a valid session. The default is DefaultUnauthorized.

func WithUserInfo 

func WithUserInfo(enable bool) Option

WithUserInfo requests the UserInfo endpoint at login and adds its claims to the claims returned by Frontend.UserHandler and 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 

func NewProvider(ctx context.Context, issuer string, opts ...ProviderOption) (*Provider, error)

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 added in v0.2.0 

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 added in v0.2.0 

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 PushedAuthorization 

type PushedAuthorization uint8

PushedAuthorization defines when a Frontend 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] fails if the provider has no pushed
	// authorization request endpoint.
	PushedAuthorizationRequired
	// PushedAuthorizationDisabled never pushes the authorization requests. [NewFrontend] fails if the provider requires
	// pushed authorization requests.
	PushedAuthorizationDisabled
)

Source Files

View all 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

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.