oauth

Documentation

Overview

Package oauth implements the browser login of cubecli against the CubePath authorization server: RFC 9728/8414 discovery, RFC 7591 client registration, authorization code + PKCE (RFC 7636) over a loopback redirect (RFC 8252), resource indicators (RFC 8707), refresh and revocation (RFC 7009).

Index

• Constants
• Variables
• func Discover(ctx context.Context, apiURL string) (*ProtectedResource, *ServerMetadata, error)
• func Register(ctx context.Context, meta *ServerMetadata) (string, error)
• func ResourceIsAPI(resource, apiURL string) bool
• func Revoke(ctx context.Context, revocationEndpoint, clientID, token, hint string) error
• type Error
  • func (e *Error) Error() string
• type LoginOptions
• type LoginResult
  • func Login(ctx context.Context, opts LoginOptions) (*LoginResult, error)
• type ProtectedResource
• type ServerMetadata
• type TokenResponse
  • func Exchange(ctx context.Context, ...) (*TokenResponse, error)
  • func RefreshToken(ctx context.Context, tokenEndpoint, clientID, refreshToken, resource string) (*TokenResponse, error)
  • func (t *TokenResponse) ExpiresAt() time.Time
  • func (t *TokenResponse) Scopes() []string
• type TokenSource
  • func NewTokenSource(profile string, creds *config.OAuthCredentials) *TokenSource
  • func (ts *TokenSource) Refresh(stale string) (string, error)
  • func (ts *TokenSource) Token() (string, error)

Constants

const (
	ClientName = "CubePath CLI"
)

Variables

var ErrBrowserLoginUnsupported = errors.New("browser login is not available for this API yet")

ErrBrowserLoginUnsupported means the API does not accept browser-login tokens: its protected resource metadata does not name the API itself.

Functions

func Discover

func Discover(ctx context.Context, apiURL string) (*ProtectedResource, *ServerMetadata, error)

Discover resolves the authorization server of the API at apiURL.

func Register

func Register(ctx context.Context, meta *ServerMetadata) (string, error)

Register creates a public client for this machine's loopback redirect URIs.

func ResourceIsAPI

func ResourceIsAPI(resource, apiURL string) bool

ResourceIsAPI reports whether an OAuth resource identifier is the API at apiURL, i.e. whether tokens issued for it are accepted by the API.

func Revoke

func Revoke(ctx context.Context, revocationEndpoint, clientID, token, hint string) error

Revoke invalidates the grant behind a token (RFC 7009).

Types

type Error

type Error struct {
	StatusCode  int
	Code        string `json:"error"`
	Description string `json:"error_description"`
}

Error is an OAuth error response (RFC 6749 section 5.2).

func (*Error) Error

func (e *Error) Error() string

type LoginOptions

type LoginOptions struct {
	APIURL string
	// LookupClient returns the client_id this machine previously registered on the
	// given issuer, or "". Empty, or unknown to the server, triggers a new
	// registration.
	LookupClient func(issuer string) string
	// NoBrowser prints the URL instead of opening it, and asks for the URL the
	// browser ended up on. For machines without a browser (SSH sessions).
	NoBrowser bool
	In        io.Reader
	Out       io.Writer
	// ClientRegistered is called when a new client is registered.
	ClientRegistered func(issuer, clientID string)
}

LoginOptions configures an interactive browser login.

type LoginResult

type LoginResult struct {
	Meta     *ServerMetadata
	Resource string
	ClientID string
	Token    *TokenResponse
}

LoginResult is the outcome of a successful login.

func Login

func Login(ctx context.Context, opts LoginOptions) (*LoginResult, error)

Login runs the authorization code + PKCE flow through the user's browser.

type ProtectedResource

type ProtectedResource struct {
	Resource             string   `json:"resource"`
	AuthorizationServers []string `json:"authorization_servers"`
}

ProtectedResource is the RFC 9728 document served by the API.

type ServerMetadata

type ServerMetadata struct {
	Issuer                string   `json:"issuer"`
	AuthorizationEndpoint string   `json:"authorization_endpoint"`
	TokenEndpoint         string   `json:"token_endpoint"`
	RegistrationEndpoint  string   `json:"registration_endpoint"`
	RevocationEndpoint    string   `json:"revocation_endpoint"`
	ScopesSupported       []string `json:"scopes_supported"`
}

ServerMetadata is the RFC 8414 document served by the authorization server.

type TokenResponse

type TokenResponse struct {
	AccessToken  string `json:"access_token"`
	TokenType    string `json:"token_type"`
	ExpiresIn    int    `json:"expires_in"`
	RefreshToken string `json:"refresh_token"`
	Scope        string `json:"scope"`
}

TokenResponse is a successful token endpoint response.

func Exchange

func Exchange(ctx context.Context, tokenEndpoint, clientID, code, redirect, verifier, resource string) (*TokenResponse, error)

Exchange trades an authorization code for tokens.

func RefreshToken

func RefreshToken(ctx context.Context, tokenEndpoint, clientID, refreshToken, resource string) (*TokenResponse, error)

RefreshToken obtains a new access token. The server rotates the refresh token: the returned one replaces the old, which must never be presented again.

func (*TokenResponse) ExpiresAt

func (t *TokenResponse) ExpiresAt() time.Time

ExpiresAt converts expires_in to an absolute time, relative to now.

func (*TokenResponse) Scopes

func (t *TokenResponse) Scopes() []string

Scopes returns the granted scopes as a list.

type TokenSource

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

TokenSource serves the access token of an OAuth profile, refreshing it when it is about to expire or the API rejects it.

func NewTokenSource

func NewTokenSource(profile string, creds *config.OAuthCredentials) *TokenSource

NewTokenSource returns a token source for the named profile.

func (*TokenSource) Refresh

func (ts *TokenSource) Refresh(stale string) (string, error)

Refresh replaces the access token `stale`. It re-reads the profile under the config lock, so if another cubecli process already refreshed, its tokens are used instead of refreshing again.

func (*TokenSource) Token

func (ts *TokenSource) Token() (string, error)

Token returns a valid access token, refreshing it first if needed.