oauth2

Documentation

Index

• Variables
• type AccessTokenClaims
• type AccessTokenConfigClaims
• type AccessTokenType
• type Authenticator
  • func New(options *Options, namespace string, client client.Client, ...) *Authenticator
  • func (a *Authenticator) Authorization(w http.ResponseWriter, r *http.Request)
  • func (a *Authenticator) Callback(w http.ResponseWriter, r *http.Request)
  • func (a *Authenticator) InvalidateToken(ctx context.Context, token string)
  • func (a *Authenticator) Issue(ctx context.Context, info *IssueInfo) (*Tokens, error)
  • func (a *Authenticator) Login(w http.ResponseWriter, r *http.Request)
  • func (a *Authenticator) Token(w http.ResponseWriter, r *http.Request) (*openapi.Token, error)
  • func (a *Authenticator) TokenAuthorizationCode(w http.ResponseWriter, r *http.Request) (*openapi.Token, error)
  • func (a *Authenticator) TokenClientCredentials(w http.ResponseWriter, r *http.Request) (*openapi.Token, error)
  • func (a *Authenticator) TokenRefreshToken(w http.ResponseWriter, r *http.Request) (*openapi.Token, error)
  • func (a *Authenticator) Verify(ctx context.Context, info *VerifyInfo) (*AccessTokenClaims, error)
• type Code
• type CustomAccessTokenClaims
• type CustomRefreshTokenClaims
• type Error
• type Federated
• type IssueInfo
• type LoginStateClaims
• type Options
  • func (o *Options) AddFlags(f *pflag.FlagSet)
• type RefreshTokenClaims
• type Scope
  • func NewScope(s string) Scope
  • func (l *Scope) MarshalJSON() ([]byte, error)
  • func (l *Scope) UnmarshalJSON(value []byte) error
• type ServiceAccount
• type State
• type Tokens
• type VerifyInfo

Variables

var (
	ErrUnsupportedProviderType = goerrors.New("unhandled provider type")
	ErrReference               = goerrors.New("resource reference error")
	ErrUserNotDomainMapped     = goerrors.New("user is not domain mapped to an organization")
)

var (
	// ErrKeyFormat is raised when something is wrong with the
	// encryption keys.
	ErrKeyFormat = errors.New("key format error")

	// ErrTokenVerification is raised when token verification fails.
	ErrTokenVerification = errors.New("failed to verify token")
)

Types

type AccessTokenClaims

type AccessTokenClaims struct {
	jwt.Claims `json:",inline"`

	Config *AccessTokenConfigClaims `json:"cnf,omitempty"`

	// Custom claims are application specific extensions.
	Custom *CustomAccessTokenClaims `json:"cat,omitempty"`
}

AccessTokenClaims is an application specific set of claims. TODO: this technically isn't conformant to oauth2 in that we don't specify the client_id claim, and there are probably others.

type AccessTokenConfigClaims

type AccessTokenConfigClaims struct {
	//nolint: tagliatelle
	X509Thumbprint *string `json:"x5t@S256,omitempty"`
}

type AccessTokenType

type AccessTokenType string

const (
	AccessTokenTypeFederated AccessTokenType = "fed"

	AccessTokenTypeServiceAccount AccessTokenType = "sa"
)

type Authenticator

type Authenticator struct {
	// contains filtered or unexported fields
}

Authenticator provides Keystone authentication functionality.

func New

func New(options *Options, namespace string, client client.Client, issuer *jose.JWTIssuer, rbac *rbac.RBAC) *Authenticator

New returns a new authenticator with required fields populated. You must call AddFlags after this.

func (*Authenticator) Authorization

func (a *Authenticator) Authorization(w http.ResponseWriter, r *http.Request)

Authorization redirects the client to the OIDC autorization endpoint to get an authorization code. Note that this function is responsible for either returning an authorization grant or error via a HTTP 302 redirect, or returning a HTML fragment for errors that cannot follow the provided redirect URI.

func (*Authenticator) Callback

func (a *Authenticator) Callback(w http.ResponseWriter, r *http.Request)

OIDCCallback is called by the authorization endpoint in order to return an authorization back to us. We then exchange the code for an ID token, and refresh token. Remember, as far as the client is concerned we're still doing the code grant, so return errors in the redirect query.

func (*Authenticator) InvalidateToken

func (a *Authenticator) InvalidateToken(ctx context.Context, token string)

InvalidateToken immediately invalidates the token so it's unusable again. TODO: this only considers caching in the identity service, it's still usable.

func (*Authenticator) Issue

func (a *Authenticator) Issue(ctx context.Context, info *IssueInfo) (*Tokens, error)

Issue issues a new JWT access token.

func (*Authenticator) Login

func (a *Authenticator) Login(w http.ResponseWriter, r *http.Request)

Login handles the response from the user login prompt.

func (*Authenticator) Token

func (a *Authenticator) Token(w http.ResponseWriter, r *http.Request) (*openapi.Token, error)

Token issues an OAuth2 access token from the provided authorization code.

func (*Authenticator) TokenAuthorizationCode

func (a *Authenticator) TokenAuthorizationCode(w http.ResponseWriter, r *http.Request) (*openapi.Token, error)

TokenAuthorizationCode issues a token based on whether the provided code is correct and the client code verifier (PKCS) matches.

func (*Authenticator) TokenClientCredentials

func (a *Authenticator) TokenClientCredentials(w http.ResponseWriter, r *http.Request) (*openapi.Token, error)

TokenClientCredentials issues a token if the client credentials are valid. We only support mTLS based authentication.

func (*Authenticator) TokenRefreshToken

func (a *Authenticator) TokenRefreshToken(w http.ResponseWriter, r *http.Request) (*openapi.Token, error)

TokenRefreshToken issues a token if the provided refresh token is valid.

func (*Authenticator) Verify

func (a *Authenticator) Verify(ctx context.Context, info *VerifyInfo) (*AccessTokenClaims, error)

Verify checks the access token parses and validates.

type Code

type Code struct {
	// ClientID is the client identifier.
	ClientID string `json:"cid"`
	// ClientRedirectURI is the redirect URL requested by the client.
	ClientRedirectURI string `json:"cri"`
	// ClientCodeChallenge records the client code challenge so we can
	// authenticate we are handing the authorization token back to the
	// correct client.
	ClientCodeChallenge string `json:"ccc"`
	// ClientScope records the requested client scope.
	ClientScope Scope `json:"csc,omitempty"`
	// ClientNonce is injected into a OIDC id_token.
	ClientNonce string `json:"cno,omitempty"`
	// AccessToken is the user's access token.
	AccessToken string `json:"at"`
	// RefreshToken is the users's refresh token.
	RefreshToken string `json:"rt"`
	// IDToken is the full set of claims returned by the provider.
	IDToken *oidc.IDToken `json:"idt"`
	// AccessTokenExpiry tells us how long the token will last for.
	AccessTokenExpiry time.Time `json:"ate"`
	// OAuth2Provider is the name of the provider configuration in
	// use, this will reference the issuer and allow discovery.
	OAuth2Provider string `json:"oap"`
}

Code is an authorization code to return to the client that can be exchanged for an access token. Much like how we client things in the oauth2 state during the OIDC exchange, to mitigate problems with horizonal scaling and sharing stuff, we do the same here. WARNING: Don't make this too big, the ingress controller will barf if the headers are too hefty.

type CustomAccessTokenClaims

type CustomAccessTokenClaims struct {
	// Type is the type of access token this is.
	Type AccessTokenType `json:"typ"`
	// Provider is the provider name for the token (federated tokens only).
	Provider string `json:"pr"`
	// AccessToken as defined for the IdP (federated tokens only).
	AccessToken string `json:"at"`
	// OrganizationID is the identifier of the organization (service accounts only).
	OrganizationID string `json:"oid"`
	// ClientID is the oauth2 client that the user is using.
	ClientID string `json:"cid"`
}

CustomAccessTokenClaims contains all application specific claims in a single top-level claim that won't clash with the ones defined by IETF.

type CustomRefreshTokenClaims

type CustomRefreshTokenClaims struct {
	// Provider is the provider name for the token.
	Provider string
	// RefreshToken as defined for the IdP.
	RefreshToken string `json:"rt"`
	// ClientID is the oauth2 client that the user is using.
	ClientID string `json:"cid"`
}

CustomRefreshTokenClaims contains all application specific claims in a single top-level claim that won't clash with the ones defined by IETF.

type Error

type Error string

const (
	ErrorInvalidRequest          Error = "invalid_request"
	ErrorUnauthorizedClient      Error = "unauthorized_client"
	ErrorAccessDenied            Error = "access_denied"
	ErrorUnsupportedResponseType Error = "unsupported_response_type"
	ErrorInvalidScope            Error = "invalid_scope"
	ErrorServerError             Error = "server_error"
)

type Federated

type Federated struct {
	Provider     string
	Expiry       time.Time
	AccessToken  string
	RefreshToken string
}

Federated is any information required to issue a federated access token.

type IssueInfo

type IssueInfo struct {
	// Issuer should be from the HTTP Host header, as requested by the client.
	Issuer string
	// Audience should be from the HTTP Host header, as only we can decipher the token.
	Audience string
	// Subject is the user, or service account ID, the token is valid for.  This is used
	// for RBAC.
	Subject string
	// Federated is a set of tokens, if defined, for a federated OIDC server.
	Federated *Federated
	// ServiceAccount indicates this is issued for a service account.
	ServiceAccount *ServiceAccount
	// X509Thumbprint is a certificate thumbprint for X.509 based passwordless authentication.
	X509Thumbprint string
	// ClientID is the oauth2 client that the user is using.
	ClientID string
}

IssueInfo controls how the access token is encoded.

type LoginStateClaims

type LoginStateClaims struct {
	Query string `json:"query"`
}

LoginStateClaims are used to encrypt information across the login dialog.

type Options

type Options struct {
	// AccessTokenDuration should be short to prevent long term use.
	AccessTokenDuration time.Duration

	// RefreshTokenDuration should be driven by the signing key rotation
	// period.
	RefreshTokenDuration time.Duration

	// TokenVerificationLeeway tells us how permissive we should or shouldn't
	// be of timing.
	TokenVerificationLeeway time.Duration

	// TokenLeewayDuration allows us to remove a period from the IdP access token
	// lifetime so we can "guarantee" ours will expire before theirs and force
	// a refresh before any errors can come from the IdP.
	TokenLeewayDuration time.Duration

	// TokenCacheSize is used to control the size of the LRU cache for token validation
	// checks.  This bounds the memory use to prevent DoS attacks.
	TokenCacheSize int

	// Bool to indicate whether sign up is allowed
	AuthenticateUnknownUsers bool
}

func (*Options) AddFlags

func (o *Options) AddFlags(f *pflag.FlagSet)

type RefreshTokenClaims

type RefreshTokenClaims struct {
	jwt.Claims `json:",inline"`

	// Custom claims are application specific extensions.
	Custom *CustomRefreshTokenClaims `json:"crt,omitempty"`
}

RefreshTokenClaims is a basic set of JWT claims, plus a wrapper for the IdP's refresh token.

type Scope

type Scope []string

Scope defines a list of scopes.

func NewScope

func NewScope(s string) Scope

NewScope creates a new scopes object.

func (*Scope) MarshalJSON

func (l *Scope) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaller.

func (*Scope) UnmarshalJSON

func (l *Scope) UnmarshalJSON(value []byte) error

UnmarshalJSON implments json.Unmarshaller.

type ServiceAccount

type ServiceAccount struct {
	// OrganizationID is the organization ID used to verify the subject exists
	// and the token is still valid.
	OrganizationID string
	// Duration is the token lifetime.  Please note this should only be used for
	// service account tokens that by definition need to be long lived.
	Duration *time.Duration
}

ServiceAccount is any information required to issue a service account access token.

type State

type State struct {
	// Nonce is the one time nonce used to create the token.
	Nonce string `json:"n"`
	// Code verfier is required to prove our identity when
	// exchanging the code with the token endpoint.
	CodeVerifier string `json:"cv"`
	// OAuth2Provider is the name of the provider configuration in
	// use, this will reference the issuer and allow discovery.
	OAuth2Provider string `json:"oap"`
	// ClientID is the client identifier.
	ClientID string `json:"cid"`
	// ClientRedirectURI is the redirect URL requested by the client.
	ClientRedirectURI string `json:"cri"`
	// Client state records the client's OAuth state while we interact
	// with the OIDC authorization server.
	ClientState string `json:"cst,omitempty"`
	// ClientCodeChallenge records the client code challenge so we can
	// authenticate we are handing the authorization token back to the
	// correct client.
	ClientCodeChallenge string `json:"ccc"`
	// ClientScope records the requested client scope.
	ClientScope Scope `json:"csc,omitempty"`
	// ClientNonce is injected into a OIDC id_token.
	ClientNonce string `json:"cno,omitempty"`
}

State records state across the call to the authorization server. This must be encrypted with JWE.

type Tokens

type Tokens struct {
	Expiry       time.Time
	AccessToken  string
	RefreshToken *string
}

Tokens is the set of tokens and metadata returned by a token issue.

type VerifyInfo

type VerifyInfo struct {
	Issuer   string
	Audience string
	Token    string
}