oidc

Documentation

Overview

Package oidc contains common OIDC functionality needed by FederationDomains to implement downstream OIDC functionality.

Index

• Constants
• func DefaultOIDCTimeoutsConfiguration() timeouts.Configuration
• func FositeErrorForLog(err error) []any
• func FositeOauth2Helper(oauthStore any, issuer string, hmacSecretOfLengthAtLeast32Func func() []byte, ...) fosite.OAuth2Provider
• func GrantScopeIfRequested(authorizeRequester fosite.AuthorizeRequester, scopeName string)
• func PerformAuthcodeRedirect(r *http.Request, w http.ResponseWriter, oauthHelper fosite.OAuth2Provider, ...)
• func ScopeWasRequested(authorizeRequester fosite.AuthorizeRequester, scopeName string) bool
• func WriteAuthorizeError(r *http.Request, w http.ResponseWriter, oauthHelper fosite.OAuth2Provider, ...)
• type Codec
• type Decoder
• type Encoder
• type UpstreamStateParamData
  • func ReadStateParamAndValidateCSRFCookie(r *http.Request, cookieDecoder Decoder, stateDecoder Decoder) (stateparam.Encoded, *UpstreamStateParamData, error)

Constants

const (
	WellKnownEndpointPath     = "/.well-known/openid-configuration"
	AuthorizationEndpointPath = "/oauth2/authorize"
	TokenEndpointPath         = "/oauth2/token" //nolint:gosec // ignore lint warning that this is a credential
	CallbackEndpointPath      = "/callback"
	ChooseIDPEndpointPath     = "/choose_identity_provider"
	JWKSEndpointPath          = "/jwks.json"
	PinnipedIDPsPathV1Alpha1  = "/v1alpha1/pinniped_identity_providers"
	PinnipedLoginPath         = "/login"
)

const (
	// UpstreamStateParamFormatVersion exists just in case we need to make a breaking change to the format of the
	// upstream state param, we are including a format version number. This gives the opportunity for a future version
	// of Pinniped to have the consumer of this format decide to reject versions that it doesn't understand.
	//
	// Version 1 was the original version.
	// Version 2 added the UpstreamType field to the UpstreamStateParamData struct.
	UpstreamStateParamFormatVersion = "2"

	// UpstreamStateParamEncodingName is the `name` passed to the encoder for encoding the upstream state param value.
	// This name is short because it will be encoded into the upstream state param value, and we're trying to keep that
	// small.
	UpstreamStateParamEncodingName = "s"

	// CSRFCookieName is the name of the browser cookie which shall hold our CSRF value.
	// The `__Host` prefix has a special meaning. See:
	// https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies#Cookie_prefixes.
	CSRFCookieName = "__Host-pinniped-csrf"

	// CSRFCookieEncodingName is the `name` passed to the encoder for encoding and decoding the CSRF
	// cookie contents.
	CSRFCookieEncodingName = "csrf"

	// CSRFCookieLifespan is the length of time that the CSRF cookie is valid. After this time, the
	// Supervisor's authorization endpoint should give the browser a new CSRF cookie. We set it to
	// a week so that it is unlikely to expire during a login.
	CSRFCookieLifespan = time.Hour * 24 * 7
)

Functions

func DefaultOIDCTimeoutsConfiguration

func DefaultOIDCTimeoutsConfiguration() timeouts.Configuration

DefaultOIDCTimeoutsConfiguration returns the default timeouts for the Supervisor server.

func FositeErrorForLog

func FositeErrorForLog(err error) []any

FositeErrorForLog generates a list of information about the provided Fosite error that can be passed to a plog function (e.g., plog.Info()).

Sample usage:

err := someFositeLibraryFunction()
if err != nil {
    plog.Info("some error", FositeErrorForLog(err)...)
    ...
}

func FositeOauth2Helper

func FositeOauth2Helper(
	oauthStore any,
	issuer string,
	hmacSecretOfLengthAtLeast32Func func() []byte,
	jwksProvider jwks.DynamicJWKSProvider,
	timeoutsConfiguration timeouts.Configuration,
) fosite.OAuth2Provider

func GrantScopeIfRequested

func GrantScopeIfRequested(authorizeRequester fosite.AuthorizeRequester, scopeName string)

func PerformAuthcodeRedirect

func PerformAuthcodeRedirect(
	r *http.Request,
	w http.ResponseWriter,
	oauthHelper fosite.OAuth2Provider,
	authorizeRequester fosite.AuthorizeRequester,
	openIDSession *psession.PinnipedSession,
	isBrowserless bool,
)

PerformAuthcodeRedirect successfully completes a downstream login by creating a session and writing the authcode redirect response as it should be returned by the authorization endpoint and other similar endpoints that are the end of the downstream authcode flow.

func ScopeWasRequested

func ScopeWasRequested(authorizeRequester fosite.AuthorizeRequester, scopeName string) bool

func WriteAuthorizeError

func WriteAuthorizeError(r *http.Request, w http.ResponseWriter, oauthHelper fosite.OAuth2Provider, authorizeRequester fosite.AuthorizeRequester, err error, isBrowserless bool)

WriteAuthorizeError writes an authorization error as it should be returned by the authorization endpoint and other similar endpoints that are the end of the downstream authcode flow. Errors responses are written in the usual fosite style.

Types

type Codec

type Codec interface {
	Encoder
	Decoder
}

Codec is both the encoding and decoding sides of the securecookie.Codec interface. It is interface'd here so that we properly wrap the securecookie dependency.

type Decoder

type Decoder interface {
	Decode(name, value string, into any) error
}

Decoder is the decoding side of the securecookie.Codec interface.

type Encoder

type Encoder interface {
	Encode(name string, value any) (string, error)
}

Encoder is the encoding side of the securecookie.Codec interface.

type UpstreamStateParamData

type UpstreamStateParamData struct {
	AuthParams    string              `json:"p"`
	UpstreamName  string              `json:"u"`
	UpstreamType  string              `json:"t"`
	Nonce         nonce.Nonce         `json:"n"`
	CSRFToken     csrftoken.CSRFToken `json:"c"`
	PKCECode      pkce.Code           `json:"k"`
	FormatVersion string              `json:"v"`
}

UpstreamStateParamData is the format of the state parameter that we use when we communicate to an upstream OIDC provider.

Keep the JSON to a minimal size because the upstream provider could impose size limitations on the state param.

func ReadStateParamAndValidateCSRFCookie

func ReadStateParamAndValidateCSRFCookie(r *http.Request, cookieDecoder Decoder, stateDecoder Decoder) (stateparam.Encoded, *UpstreamStateParamData, error)