oidcclient

Documentation

Overview

Package oidcclient implements a CLI OIDC login flow.

Index

• func Login(issuer string, clientID string, opts ...Option) (*oidctypes.Token, error)
• type Option
  • func WithBrowserOpen(openURL func(url string) error) 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 WithRequestAudience(audience string) Option
  • func WithScopes(scopes []string) Option
  • func WithSessionCache(cache SessionCache) Option
  • func WithSkipBrowserOpen() Option
  • func WithSkipListen() 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 Option

type Option func(*handlerState) error

Option is an optional configuration for Login().

func WithBrowserOpen

func WithBrowserOpen(openURL func(url string) error) Option

WithBrowserOpen overrides the default "open browser" functionality with a custom callback. If not specified, an implementation using https://github.com/pkg/browser will be used by default.

Deprecated: this option will be removed in a future version of Pinniped. See the WithSkipBrowserOpen() option instead.

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.

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 new 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 skip starting the localhost listener, forcing the manual copy/paste login flow.

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"`
}

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