Documentation
¶
Overview ¶
Package oauth implements the client side of DigitalOcean's OAuth 2.1 authorization code flow with PKCE (RFC 7636) for native applications (RFC 8252).
Index ¶
Constants ¶
const ( // DefaultIssuer is the DigitalOcean authorization server. DefaultIssuer = "https://cloud.digitalocean.com" // DefaultClientID identifies the doctl OAuth application registered with // DigitalOcean. doctl is a public client (RFC 8252): it ships to users' // machines, so it holds no client secret and this identifier is not a // secret either. PKCE, not client authentication, is what binds an // authorization code to the doctl process that requested it. Embedding the // client ID in the binary is the same approach the GitHub CLI, gcloud, and // the Azure CLI take. DefaultClientID = "2446a57f71830bf88511fa3e3920d471124084d06b8befc24a4e406eaaeac170" // CodeChallengeMethodS256 is the only PKCE code challenge method the // authorization server supports. CodeChallengeMethodS256 = "S256" )
const DefaultLoginTimeout = 5 * time.Minute
DefaultLoginTimeout bounds how long the login flow waits for the user to finish authorizing in their browser.
Variables ¶
var ErrInvalidClient = errors.New("the authorization server rejected this client")
ErrInvalidClient is returned when the authorization server rejects the OAuth application doctl signs in as.
var Login = login
Login runs the OAuth 2.1 authorization code flow with PKCE against the configured authorization server and returns the resulting token grant. It is a variable so tests can run the command without opening a browser.
Functions ¶
func RedirectURIs ¶
func RedirectURIs() []string
RedirectURIs are the redirect URIs the doctl OAuth application registers with DigitalOcean. Neither carries a port: the authorization server matches loopback redirects on any port (RFC 8252 section 7.3), which lets doctl bind an ephemeral port at login time.
Types ¶
type AuthorizationError ¶
AuthorizationError is an error the authorization server reported by redirecting back to doctl with an error parameter.
func (*AuthorizationError) Error ¶
func (e *AuthorizationError) Error() string
func (*AuthorizationError) Unwrap ¶
func (e *AuthorizationError) Unwrap() error
Unwrap reports a rejected client as ErrInvalidClient so callers can explain that the doctl application, rather than the user, was turned away.
type LoginOptions ¶
type LoginOptions struct {
// Metadata describes the authorization server endpoints to use.
Metadata *ServerMetadata
// ClientID identifies the dynamically registered public client.
ClientID string
// Scopes are the OAuth scopes to request. An empty list lets the
// authorization server apply its default scope.
Scopes []string
// Port is the local port to listen on for the redirect. Zero picks an
// unused port, which is the recommended behavior for native apps.
Port int
// Timeout bounds how long to wait for the browser redirect. Defaults to
// DefaultLoginTimeout.
Timeout time.Duration
// HTTPClient is used for the token exchange.
HTTPClient *http.Client
// NoBrowser prints the authorization URL instead of opening a browser.
NoBrowser bool
// OnAuthorizationURL, when set, is called with the authorization URL once
// the local redirect server is listening.
OnAuthorizationURL func(authURL string)
// contains filtered or unexported fields
}
LoginOptions configures a single authorization code login.
type ServerMetadata ¶
type ServerMetadata struct {
Issuer string
AuthorizationEndpoint string
TokenEndpoint string
RevocationEndpoint string
}
ServerMetadata describes the authorization server endpoints doctl uses.
func ServerMetadataFor ¶
func ServerMetadataFor(issuer string) *ServerMetadata
ServerMetadataFor returns the endpoints for issuer. DigitalOcean's paths are stable and doctl is only ever pointed at a DigitalOcean authorization server, so the endpoints are derived locally rather than discovered over the network: there is no metadata request to make, fail, or have redirected.
type Token ¶
type Token struct {
AccessToken string
RefreshToken string
TokenType string
Scope string
// Expiry is the absolute time the access token expires. It is the zero
// value when the server does not report an expiration.
Expiry time.Time
Info TokenInfo
}
Token is an access token grant issued by the authorization server.