oidcclient

Documentation

Overview

Package oidcclient implements a CLI OIDC login flow.

Index

• func Login(issuer string, clientID string, opts ...Option) (*oidctypes.Token, error)
• type Logger
• type Option
  • func WithCLISendingCredentials() Option
  • func WithClient(httpClient *http.Client) Option
  • func WithContext(ctx context.Context) Option
  • func WithListenPort(port uint16) Option
  • func WithLogger(logger logr.Logger) Option
  • func WithLoginFlow(loginFlow idpdiscoveryv1alpha1.IDPFlow, flowSource string) Option
  • func WithLoginLogger(logger Logger) Option
  • func WithRequestAudience(audience string) Option
  • func WithScopes(scopes []string) Option
  • func WithSessionCache(cache SessionCache) Option
  • func WithSkipBrowserOpen() Option
  • func WithSkipListen() Option
  • func WithSkipPrintLoginURL() Option
  • func WithUpstreamIdentityProvider(upstreamName, upstreamType string) Option
• type SessionCache
• type SessionCacheKey

Functions

func Login

func Login(issuer string, clientID string, opts ...Option) (*oidctypes.Token, error)

Login performs an OAuth2/OIDC authorization code login using a localhost listener.

Types

type Logger

type Logger interface {
	Error(msg string, err error, keysAndValues ...any)
	Info(msg string, keysAndValues ...any)
}

type Option

type Option func(*handlerState) error

Option is an optional configuration for Login().

func WithCLISendingCredentials

func WithCLISendingCredentials() Option

WithCLISendingCredentials causes the login flow to use CLI-based prompts for username and password and causes the call to the Issuer's authorize endpoint to be made directly (no web browser) with the username and password on custom HTTP headers. This is only intended to be used when the issuer is a Pinniped Supervisor and the upstream identity provider type supports this style of authentication. Currently, this is supported by LDAPIdentityProviders, ActiveDirectoryIdentityProviders, and by OIDCIdentityProviders which optionally enable the resource owner password credentials grant flow. This should never be used with non-Supervisor issuers because it will send the user's password to the authorization endpoint as a custom header, which would be ignored but could potentially get logged somewhere by the issuer.

Deprecated: this option will be removed in a future version of Pinniped. See the WithLoginFlow() option instead. If this option is used along with the WithLoginFlow() option, it will cause an error.

func WithClient

func WithClient(httpClient *http.Client) Option

WithClient sets the HTTP client used to make CLI-to-provider requests.

func WithContext

func WithContext(ctx context.Context) Option

WithContext specifies a specific context.Context under which to perform the login. If this option is not specified, login happens under context.Background().

func WithListenPort

func WithListenPort(port uint16) Option

WithListenPort specifies a TCP listen port on localhost, which will be used for the redirect_uri and to handle the authorization code callback. By default, a random high port will be chosen which requires the authorization server to support wildcard port numbers as described by https://tools.ietf.org/html/rfc8252#section-7.3:

The authorization server MUST allow any port to be specified at the time of the request for loopback IP redirect URIs, to accommodate clients that obtain an available ephemeral port from the operating system at the time of the request.

func WithLogger

func WithLogger(logger logr.Logger) Option

WithLogger specifies a PLogger to use with the login. If not specified this will default to a no-op logger.

Deprecated: Use WithLoginLogger instead. This option will be removed in a future version of Pinniped. If this option is used along with WithLoginLogger, it will cause an error.

func WithLoginFlow

func WithLoginFlow(loginFlow idpdiscoveryv1alpha1.IDPFlow, flowSource string) Option

WithLoginFlow chooses the login flow. When the argument is equal to idpdiscoveryv1alpha1.IDPFlowCLIPassword, it causes the login flow to use CLI-based prompts for username and password and causes the call to the Issuer's authorize endpoint to be made directly (no web browser) with the username and password on custom HTTP headers. This is only intended to be used when the issuer is a Pinniped Supervisor and the upstream identity provider type supports this style of authentication. Currently, this is supported by LDAPIdentityProviders, ActiveDirectoryIdentityProviders, and by OIDCIdentityProviders which optionally enable the resource owner password credentials grant flow. This should never be used with non-Supervisor issuers because it will send the user's password to the authorization endpoint as a custom header, which would be ignored but could potentially get logged somewhere by the issuer. When the argument is equal to idpdiscoveryv1alpha1.IDPFlowBrowserAuthcode, it will attempt to open a web browser and perform the OIDC authcode flow. When not used, the default when the issuer is a Pinniped Supervisor will be determined automatically, and the default for non-Supervisor issuers will be the browser authcode flow.

func WithLoginLogger

func WithLoginLogger(logger Logger) Option

WithLoginLogger specifies a Logger to use. If not specified this will default to a no-op logger.

func WithRequestAudience

func WithRequestAudience(audience string) Option

WithRequestAudience causes the login flow to perform an additional token exchange using the RFC8693 flow.

func WithScopes

func WithScopes(scopes []string) Option

WithScopes sets the OAuth2 scopes to request during login. If not specified, it defaults to "offline_access openid email profile".

func WithSessionCache

func WithSessionCache(cache SessionCache) Option

WithSessionCache sets the session cache backend for storing and retrieving previously-issued ID tokens and refresh tokens.

func WithSkipBrowserOpen

func WithSkipBrowserOpen() Option

WithSkipBrowserOpen causes the login to only print the authorize URL, but skips attempting to open the user's default web browser.

func WithSkipListen

func WithSkipListen() Option

WithSkipListen causes the login to skip starting the localhost listener, forcing the manual copy/paste login flow.

func WithSkipPrintLoginURL

func WithSkipPrintLoginURL() Option

WithSkipPrintLoginURL causes the login to skip printing the login URL when the browser opens to that URL.

func WithUpstreamIdentityProvider

func WithUpstreamIdentityProvider(upstreamName, upstreamType string) Option

WithUpstreamIdentityProvider causes the specified name and type to be sent as custom query parameters to the issuer's authorize endpoint. This is only intended to be used when the issuer is a Pinniped Supervisor, in which case it provides a mechanism to choose among several upstream identity providers. Other issuers will ignore these custom query parameters.

type SessionCache

type SessionCache interface {
	GetToken(SessionCacheKey) *oidctypes.Token
	PutToken(SessionCacheKey, *oidctypes.Token)
}

type SessionCacheKey

type SessionCacheKey struct {
	Issuer               string   `json:"issuer"`
	ClientID             string   `json:"clientID"`
	Scopes               []string `json:"scopes"`
	RedirectURI          string   `json:"redirect_uri"`
	UpstreamProviderName string   `json:"upstream_provider_name,omitempty"`
}

SessionCacheKey contains the data used to select a valid session cache entry.