oauth

package
v0.1.2 Latest Latest
Warning

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

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

Documentation

Overview

Package oauth is the CLI's client for the auth service: discovery, the device authorization grant (RFC 8628) for `kapten login`, refresh tokens that rotate on every use, and the client credentials grant for OAuth applications. Every token request carries a DPoP proof (RFC 9449).

Index

Constants

View Source
const (
	GrantDeviceCode        = "urn:ietf:params:oauth:grant-type:device_code"
	GrantRefreshToken      = "refresh_token"
	GrantClientCredentials = "client_credentials"
)

Grant types.

View Source
const (
	ErrorAuthorizationPending = "authorization_pending"
	ErrorSlowDown             = "slow_down"
	ErrorAccessDenied         = "access_denied"
	ErrorExpiredToken         = "expired_token"
)

Device token errors (RFC 8628 section 3.5).

View Source
const ClientAssertionType = "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"

ClientAssertionType is the client_assertion_type of private_key_jwt (RFC 7523).

View Source
const RequestTimeout = 30 * time.Second

RequestTimeout bounds each request to auth.

Variables

View Source
var ErrUnavailable = errors.New("the auth service is unavailable")

ErrUnavailable marks a request that did not reach the auth service, or that it answered with a gateway or availability error: retrying later may succeed.

Functions

func IsCode

func IsCode(err error, code string) bool

IsCode reports whether err is an OAuth error with this code.

func IsTransient

func IsTransient(err error) bool

IsTransient reports whether err is worth retrying later.

func ParsePrivateKey

func ParsePrivateKey(raw []byte) (jwk.Key, error)

ParsePrivateKey reads an OAuth application's private key, a JWK or PEM.

Types

type Claims

type Claims struct {
	Subject        string `json:"sub"`
	ClientID       string `json:"client_id"`
	OrganizationID string `json:"org_id"`
	Email          string `json:"email"`
	ClientName     string `json:"client_name"`
	Scope          string `json:"scope"`
	ExpiresAt      int64  `json:"exp"`
}

Claims are the access token claims the CLI shows and keys contexts by.

func ReadClaims

func ReadClaims(accessToken string) (Claims, error)

ReadClaims decodes an access token without verifying it. The CLI got the token straight from the token endpoint; the Engine verifies it.

type Client

type Client struct {
	HTTP *http.Client
	// Now overrides the clock of DPoP proofs and expiries in tests.
	Now func() time.Time
	// Sleep waits between device polls; tests replace it.
	Sleep func(context.Context, time.Duration) error
}

Client talks to one auth service.

func (*Client) ClientAssertionToken

func (c *Client) ClientAssertionToken(ctx context.Context, metadata Metadata, clientID string, private jwk.Key, scope string, key *dpop.Key) (Token, error)

ClientAssertionToken authenticates an OAuth application with a client assertion signed by its private key (private_key_jwt, RFC 7523). With a DPoP key the token is DPoP-bound.

func (*Client) ClientCredentials

func (c *Client) ClientCredentials(ctx context.Context, metadata Metadata, clientID, clientSecret, scope string, key *dpop.Key) (Token, error)

ClientCredentials authenticates an OAuth application with its secret (client_secret_post). With a key the token is DPoP-bound.

func (*Client) Discover

func (c *Client) Discover(ctx context.Context, issuer string) (Metadata, error)

Discover reads the issuer's metadata at /.well-known/openid-configuration.

func (*Client) PollDevice

func (c *Client) PollDevice(ctx context.Context, metadata Metadata, clientID string, device DeviceAuthorization, key *dpop.Key) (Token, error)

PollDevice polls the token endpoint until the user approves, denies, or the device code expires. It waits interval seconds between polls and five more after each slow_down.

func (*Client) Refresh

func (c *Client) Refresh(ctx context.Context, metadata Metadata, clientID, refreshToken string, key *dpop.Key) (Token, error)

Refresh redeems a refresh token. auth rotates it: the response carries the next one and the old one is spent.

func (*Client) StartDevice

func (c *Client) StartDevice(ctx context.Context, metadata Metadata, clientID, scope string, key *dpop.Key) (DeviceAuthorization, error)

StartDevice asks for a device code bound to key (dpop_jkt).

type DeviceAuthorization

type DeviceAuthorization struct {
	DeviceCode              string `json:"device_code"`
	UserCode                string `json:"user_code"`
	VerificationURI         string `json:"verification_uri"`
	VerificationURIComplete string `json:"verification_uri_complete"`
	ExpiresIn               int    `json:"expires_in"`
	Interval                int    `json:"interval"`
}

DeviceAuthorization is a started device authorization (RFC 8628 section 3.2).

type Error

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

Error is an OAuth error response.

func (*Error) Error

func (e *Error) Error() string

type Metadata

type Metadata struct {
	Issuer                      string `json:"issuer"`
	TokenEndpoint               string `json:"token_endpoint"`
	DeviceAuthorizationEndpoint string `json:"device_authorization_endpoint"`
}

Metadata is the part of the authorization server metadata the CLI uses.

type Token

type Token struct {
	AccessToken  string
	TokenType    string
	RefreshToken string
	Scope        string
	// OrganizationID is the organization the access token is scoped to,
	// empty while the user belongs to none.
	OrganizationID string
	// Expiry is zero when the server sent no expires_in.
	Expiry time.Time
}

Token is a token endpoint response.

Directories

Path Synopsis
Package oauthtest serves the fake auth service of package mockauth for the duration of a test.
Package oauthtest serves the fake auth service of package mockauth for the duration of a test.

Jump to

Keyboard shortcuts

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