oauth

package
v1.184.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 13, 2026 License: Apache-2.0 Imports: 16 Imported by: 0

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

View Source
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"
)
View Source
const DefaultLoginTimeout = 5 * time.Minute

DefaultLoginTimeout bounds how long the login flow waits for the user to finish authorizing in their browser.

Variables

View Source
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.

View Source
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.

func RevokeToken

func RevokeToken(ctx context.Context, client *http.Client, revocationEndpoint, accessToken string) error

RevokeToken invalidates an access token. The authorization server requires the token both as a bearer credential and as a form value.

Types

type AuthorizationError

type AuthorizationError struct {
	Code        string
	Description string
}

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.

func ExchangeCode

func ExchangeCode(ctx context.Context, client *http.Client, tokenEndpoint, clientID, code, codeVerifier, redirectURI string) (*Token, error)

ExchangeCode exchanges an authorization code for a token grant, proving possession of the PKCE code verifier in place of a client secret.

func RefreshToken

func RefreshToken(ctx context.Context, client *http.Client, tokenEndpoint, clientID, refreshToken string) (*Token, error)

RefreshToken trades a refresh token for a new token grant. Refresh tokens are single use: the response carries the replacement refresh token.

type TokenInfo

type TokenInfo struct {
	Name     string `json:"name"`
	Email    string `json:"email"`
	UUID     string `json:"uuid"`
	TeamUUID string `json:"team_uuid"`
	TeamName string `json:"team_name"`
}

TokenInfo identifies the user and team a token was issued for.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL