oauth2

Documentation

Overview

Package oauth2 contains functionality to work with OAuth2.

Index

• Constants
• type AccessDeviceTokenOption
  • func AccessDeviceTokenWithPollingInterval(pollingInterval time.Duration) AccessDeviceTokenOption
• type Client
  • func NewClient(baseURL string, client *http.Client) *Client
  • func (c *Client) AccessDeviceToken(ctx context.Context, deviceAccessTokenRequest *DeviceAccessTokenRequest, ...) (*DeviceAccessTokenResponse, error)
  • func (c *Client) AuthorizeDevice(ctx context.Context, deviceAuthorizationRequest *DeviceAuthorizationRequest) (_ *DeviceAuthorizationResponse, retErr error)
  • func (c *Client) RegisterDevice(ctx context.Context, deviceRegistrationRequest *DeviceRegistrationRequest) (_ *DeviceRegistrationResponse, retErr error)
• type DeviceAccessTokenRequest
  • func (d *DeviceAccessTokenRequest) FromValues(values url.Values) error
  • func (d *DeviceAccessTokenRequest) ToValues() url.Values
• type DeviceAccessTokenResponse
• type DeviceAuthorizationRequest
  • func (d *DeviceAuthorizationRequest) FromValues(values url.Values) error
  • func (d *DeviceAuthorizationRequest) ToValues() url.Values
• type DeviceAuthorizationResponse
• type DeviceRegistrationRequest
• type DeviceRegistrationResponse
• type Error
  • func (e *Error) Error() string
• type ErrorCode

Constants

const (
	// DeviceRegistrationPath is the path for the device registration endpoint.
	DeviceRegistrationPath = "/oauth2/device/registration"
	// DeviceAuthorizationPath is the path for the device authorization endpoint.
	DeviceAuthorizationPath = "/oauth2/device/authorization"
	// DeviceTokenPath is the path for the device token endpoint.
	DeviceTokenPath = "/oauth2/device/token"
)

const (
	// DeviceAuthorizationGrantType is the grant type for the device authorization flow.
	DeviceAuthorizationGrantType = "urn:ietf:params:oauth:grant-type:device_code"
)

Types

type AccessDeviceTokenOption

type AccessDeviceTokenOption func(*accessDeviceTokenOptions)

AccessDeviceTokenOption is an option for AccessDeviceToken.

func AccessDeviceTokenWithPollingInterval

func AccessDeviceTokenWithPollingInterval(pollingInterval time.Duration) AccessDeviceTokenOption

AccessDeviceTokenWithPollingInterval returns a new AccessDeviceTokenOption that sets the polling interval.

The default is 5 seconds. Polling may not be longer than 30 seconds.

type Client

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

Client is an OAuth 2.0 client that can register a device, authorize a device, and poll for the device access token.

func NewClient

func NewClient(baseURL string, client *http.Client) *Client

NewClient returns a new Client with the given base URL and HTTP client.

func (*Client) AccessDeviceToken

func (c *Client) AccessDeviceToken(
	ctx context.Context,
	deviceAccessTokenRequest *DeviceAccessTokenRequest,
	options ...AccessDeviceTokenOption,
) (*DeviceAccessTokenResponse, error)

AccessDeviceToken polls the authorization server for the device access token. The interval parameter specifies the polling interval in seconds.

func (*Client) AuthorizeDevice

func (c *Client) AuthorizeDevice(
	ctx context.Context,
	deviceAuthorizationRequest *DeviceAuthorizationRequest,
) (_ *DeviceAuthorizationResponse, retErr error)

AuthorizeDevice authorizes a device with the authorization server. The authorization server will return a device code and a user code that the user must use to authorize the device.

func (*Client) RegisterDevice

func (c *Client) RegisterDevice(
	ctx context.Context,
	deviceRegistrationRequest *DeviceRegistrationRequest,
) (_ *DeviceRegistrationResponse, retErr error)

RegisterDevice registers a new device with the authorization server.

type DeviceAccessTokenRequest

type DeviceAccessTokenRequest struct {
	// ClientID is the client identifier issued to the client during the registration process.
	ClientID string `json:"client_id"`
	// ClientSecret is the client secret. May be empty.
	ClientSecret string `json:"client_secret,omitempty"`
	// DeviceCode is the device verification code.
	DeviceCode string `json:"device_code"`
	// GrantType is the grant type for the device authorization flow. Must be
	// set to "urn:ietf:params:oauth:grant-type:device_code".
	GrantType string `json:"grant_type"`
}

DeviceAccessTokenRequest describes an RFC 8628 Device Token Request. https://datatracker.ietf.org/doc/html/rfc8628#section-3.4

func (*DeviceAccessTokenRequest) FromValues

func (d *DeviceAccessTokenRequest) FromValues(values url.Values) error

FromValues converts the url.Values to a DeviceTokenRequest.

func (*DeviceAccessTokenRequest) ToValues

func (d *DeviceAccessTokenRequest) ToValues() url.Values

ToValues converts the DeviceTokenRequest to url.Values.

type DeviceAccessTokenResponse

type DeviceAccessTokenResponse struct {
	// AccessToken is the access token that can be used to access the protected resources.
	AccessToken string `json:"access_token"`
	// TokenType is the type of the token issued as described in RFC 6749 Section 7.1.
	// https://datatracker.ietf.org/doc/html/rfc6749#section-7.1
	TokenType string `json:"token_type"`
	// ExpiresIn is the lifetime in seconds of the access token.
	ExpiresIn int `json:"expires_in,omitempty"`
	// RefreshToken may be used to obtain new access tokens using the same authoization
	// grant. May be empty.
	RefreshToken string `json:"refresh_token,omitempty"`
	// Scope is the scope of the access token as described in RFC 6749 Section 3.3.
	// https://datatracker.ietf.org/doc/html/rfc6749#section-3.3
	Scope string `json:"scope,omitempty"`
}

DeviceAccessTokenResponse describes a successful RFC 8628 Device Token Response. https://datatracker.ietf.org/doc/html/rfc8628#section-3.5

type DeviceAuthorizationRequest

type DeviceAuthorizationRequest struct {
	// ClientID is the unique client identifier.
	ClientID string `json:"client_id"`
	// ClientSecret is the client secret. May be empty.
	ClientSecret string `json:"client_secret,omitempty"`
}

DeviceAuthorizationRequest describes an RFC 8628 Device Authorization Request. https://datatracker.ietf.org/doc/html/rfc8628#section-3.1

func (*DeviceAuthorizationRequest) FromValues

func (d *DeviceAuthorizationRequest) FromValues(values url.Values) error

FromValues converts the url.Values to a DeviceAuthorizationRequest.

func (*DeviceAuthorizationRequest) ToValues

func (d *DeviceAuthorizationRequest) ToValues() url.Values

ToValues converts the DeviceAuthorizationRequest to url.Values.

type DeviceAuthorizationResponse

type DeviceAuthorizationResponse struct {
	// DeviceCode is the device verification code.
	DeviceCode string `json:"device_code"`
	// UserCode is the end-user verification code.
	UserCode string `json:"user_code"`
	// VerificationURI is the verification URI that the end user should visit to
	// enter the user_code.
	VerificationURI string `json:"verification_uri"`
	// VerificationURIComplete is the verification URI that includes the user_code.
	VerificationURIComplete string `json:"verification_uri_complete,omitempty"`
	// ExpiresIn is the lifetime in seconds of the "device_code" and "user_code".
	ExpiresIn int `json:"expires_in"`
	// Interval is the minimum amount of time in seconds that the client SHOULD wait
	// between polling requests to the token endpoint.
	Interval int `json:"interval,omitempty"`
}

DeviceAuthorizationResponse describes a successful RFC 8628 Device Authorization Response https://datatracker.ietf.org/doc/html/rfc8628#section-3.2

type DeviceRegistrationRequest

type DeviceRegistrationRequest struct {
	// Name of the client to be presented to the end user.
	ClientName string `json:"client_name"`
}

DeviceRegistrationRequest describes an OpenID Connect Dynamic Client Registration 1.0 request for dynamic client registration. It is a subset of the full specification. It does not require a redirect URI or grant types for the device authorization flow. https://openid.net/specs/openid-connect-registration-1_0.html#RegistrationRequest

type DeviceRegistrationResponse

type DeviceRegistrationResponse struct {
	// ClientID is the unique client identifier.
	ClientID string `json:"client_id"`
	// ClientSecret is the client secret. May be empty.
	ClientSecret string `json:"client_secret,omitempty"`
	// ClientIDIssuedAt is the time at which the ClientID was issued in seconds since the Unix epoch.
	ClientIDIssuedAt int `json:"client_id_issued_at"`
	// ClientSecretExpiresAt is the time at which the client_secret will expire in seconds since the Unix epoch.
	ClientSecretExpiresAt int `json:"client_secret_expires_at,omitempty"`
}

Devic describes a successful OpenID Connect Dynamic Client Registration 1.0 response for dynamic client registration.

type Error

type Error struct {
	// ErrorCode is the error code.
	ErrorCode ErrorCode `json:"error"`
	// ErrorDescription is a human-readable description of the error. May be empty.
	ErrorDescription string `json:"error_description,omitempty"`
	// ErrorURI is a URI for the error. May be empty.
	ErrorURI string `json:"error_uri,omitempty"`
}

Error is an OAuth2 error.

func (*Error) Error

func (e *Error) Error() string

Error implements error.

type ErrorCode

type ErrorCode string

ErrorCode is an OAuth2 error code.

const (
	// ErrorCodeAuthorizationPending is a pending device authorization grant as the
	// end user hasn't yet completed the user interaction steps.
	ErrorCodeAuthorizationPending ErrorCode = "authorization_pending"
	// ErrorCodeSlowDown is returned for a pending device authorization grant and
	// polling should continue, but the interval MUST be increased by 5 seconds for
	// all subsequent requests.
	ErrorCodeSlowDown ErrorCode = "slow_down"
	// ErrorCodeAccessDenied is returned when the device authorization request was denied.
	ErrorCodeAccessDenied ErrorCode = "access_denied"
	// ErrorCodeExpiredToken is the device_code has expired, and the device authorization
	// session has concluded. The client MAY commence a new device authorization request but
	// SHOULD wait for user interaction before restarting to avoid unnecessary polling.
	ErrorCodeExpiredToken ErrorCode = "expired_token"
)

The following error codes are defined by RFC 8628 Section 3.5 Device Authorization Response.

const (
	// ErrorCodeInvalidRequest is an invalid or malformed request error.
	ErrorCodeInvalidRequest ErrorCode = "invalid_request"
	// ErrorCodeInvalidClient is a client authentication error.
	ErrorCodeInvalidClient ErrorCode = "invalid_client"
	// ErrorCodeInvalidGrant is an invalid grant error.
	ErrorCodeInvalidGrant ErrorCode = "invalid_grant"
	// ErrorCodeUnauthorizedClient is an unauthorized client error.
	ErrorCodeUnauthorizedClient ErrorCode = "unauthorized_client"
	// ErrorCodeUnsupportedGrantType is an unsupported grant type error.
	ErrorCodeUnsupportedGrantType ErrorCode = "unsupported_grant_type"
	// ErrorCodeInvalidScope is an invalid scope error.
	ErrorCodeInvalidScope ErrorCode = "invalid_scope"
)

The following error codes are defined by RFC 6749 Section 5.2 Error Response.