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
- Variables
- func IsCode(err error, code string) bool
- func IsTransient(err error) bool
- func ParsePrivateKey(raw []byte) (jwk.Key, error)
- type Claims
- type Client
- func (c *Client) ClientAssertionToken(ctx context.Context, metadata Metadata, clientID string, private jwk.Key, ...) (Token, error)
- func (c *Client) ClientCredentials(ctx context.Context, metadata Metadata, clientID, clientSecret, scope string, ...) (Token, error)
- func (c *Client) Discover(ctx context.Context, issuer string) (Metadata, error)
- func (c *Client) PollDevice(ctx context.Context, metadata Metadata, clientID string, ...) (Token, error)
- func (c *Client) Refresh(ctx context.Context, metadata Metadata, clientID, refreshToken string, ...) (Token, error)
- func (c *Client) StartDevice(ctx context.Context, metadata Metadata, clientID, scope string, key *dpop.Key) (DeviceAuthorization, error)
- type DeviceAuthorization
- type Error
- type Metadata
- type Token
Constants ¶
const ( GrantDeviceCode = "urn:ietf:params:oauth:grant-type:device_code" GrantRefreshToken = "refresh_token" GrantClientCredentials = "client_credentials" )
Grant types.
const ( ErrorAuthorizationPending = "authorization_pending" ErrorSlowDown = "slow_down" ErrorAccessDenied = "access_denied" ErrorExpiredToken = "expired_token" )
Device token errors (RFC 8628 section 3.5).
const ClientAssertionType = "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"
ClientAssertionType is the client_assertion_type of private_key_jwt (RFC 7523).
const RequestTimeout = 30 * time.Second
RequestTimeout bounds each request to auth.
Variables ¶
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 IsTransient ¶
IsTransient reports whether err is worth retrying later.
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 ¶
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 ¶
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.
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.
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.