oauth2dev

README

oauth2dev

This package is an implementation of OAuth 2.0 Device Authorization Grant, described in RFC 8628. It is compatible with golang.org/x/oauth2 package.

Documentation

Overview

Package oauth2dev is an implementation of OAuth 2.0 Device Authorization Grant, described in RFC 8628 https://www.rfc-editor.org/rfc/rfc8628.

Index

• Constants
• func GetToken(ctx context.Context, cfg oauth2.Config, h HandleAuthorizationResponseFunc) (*oauth2.Token, error)
• func PollToken(ctx context.Context, cfg oauth2.Config, ar AuthorizationResponse) (*oauth2.Token, error)
• func RetrieveToken(ctx context.Context, cfg oauth2.Config, deviceCode string) (*oauth2.Token, error)
• type AuthorizationErrorResponse
  • func (err AuthorizationErrorResponse) Error() string
• type AuthorizationResponse
  • func RetrieveCode(ctx context.Context, cfg oauth2.Config) (*AuthorizationResponse, error)
  • func (ar AuthorizationResponse) IntervalDuration() time.Duration
  • func (ar AuthorizationResponse) URL() string
• type HandleAuthorizationResponseFunc
• type TokenErrorResponse
  • func (err TokenErrorResponse) Error() string

Constants

const (
	TokenErrorAuthorizationPending = "authorization_pending"
	TokenErrorSlowDown             = "slow_down"
	TokenErrorAccessDenied         = "access_denied"
	TokenErrorExpiredToken         = "expired_token"
)

Error codes of token response, described in https://www.rfc-editor.org/rfc/rfc8628#section-3.5

Functions

func GetToken

func GetToken(ctx context.Context, cfg oauth2.Config, h HandleAuthorizationResponseFunc) (*oauth2.Token, error)

GetToken sends an authorization request and then polls the token response.

func PollToken

func PollToken(ctx context.Context, cfg oauth2.Config, ar AuthorizationResponse) (*oauth2.Token, error)

PollToken tries a token request and waits until it receives a token response. It polls by the interval described in https://www.rfc-editor.org/rfc/rfc8628#section-3.5. When the context is done, this function immediately returns the context error.

func RetrieveToken

func RetrieveToken(ctx context.Context, cfg oauth2.Config, deviceCode string) (*oauth2.Token, error)

RetrieveToken sends a token request to the endpoint. If it received a successful response, it returns the oauth2.Token. If it received an error response JSON, it returns an TokenErrorResponse. Otherwise, it returns an error wrapped with the cause.

Types

type AuthorizationErrorResponse

type AuthorizationErrorResponse struct {
	StatusCode       int    `json:"-"`
	ErrorCode        string `json:"error,omitempty"`
	ErrorDescription string `json:"error_description,omitempty"`
	ErrorURI         string `json:"error_uri,omitempty"`
}

AuthorizationErrorResponse represents the error response, described in https://www.rfc-editor.org/rfc/rfc6749#section-5.2

func (AuthorizationErrorResponse) Error

func (err AuthorizationErrorResponse) Error() string

type AuthorizationResponse

type AuthorizationResponse struct {
	// The device verification code.
	DeviceCode string `json:"device_code,omitempty"`

	// The end-user verification code.
	UserCode string `json:"user_code,omitempty"`

	// The end-user verification URI on the authorization server.
	VerificationURI string `json:"verification_uri,omitempty"`

	// A verification URI that includes the "user_code" (or
	// other information with the same function as the "user_code"),
	// which is designed for non-textual transmission.
	VerificationURIComplete string `json:"verification_uri_complete,omitempty"`

	// The end-user verification URI on the authorization server.
	// Some implementations return this field instead of verification_uri,
	// such as https://developers.google.com/identity/protocols/oauth2/limited-input-device.
	VerificationURL string `json:"verification_url,omitempty"`

	// The lifetime in seconds of the "device_code" and "user_code".
	ExpiresIn int `json:"expires_in,omitempty"`

	// The minimum amount of time in seconds that the client
	// SHOULD wait between polling requests to the token endpoint.
	// If no value is provided, clients MUST use 5 as the default.
	Interval int `json:"interval,omitempty"`
}

AuthorizationResponse represents Device Authorization Response, described in https://www.rfc-editor.org/rfc/rfc8628#section-3.2

func RetrieveCode

func RetrieveCode(ctx context.Context, cfg oauth2.Config) (*AuthorizationResponse, error)

RetrieveCode sends an authorization request to the authorization endpoint. If it received a successful response, it returns the AuthorizationResponse. If it received an error response JSON, it returns an AuthorizationErrorResponse. Otherwise, it returns an error wrapped with the cause.

func (AuthorizationResponse) IntervalDuration

func (ar AuthorizationResponse) IntervalDuration() time.Duration

func (AuthorizationResponse) URL

func (ar AuthorizationResponse) URL() string

URL returns either of VerificationURIComplete, VerificationURI or VerificationURL.

type HandleAuthorizationResponseFunc

type HandleAuthorizationResponseFunc func(response AuthorizationResponse)

HandleAuthorizationResponseFunc is a function to handle an authorization response. It should display the user code and verification URL to the user. See https://www.rfc-editor.org/rfc/rfc8628#section-3.3

type TokenErrorResponse

type TokenErrorResponse struct {
	StatusCode       int    `json:"-"`
	ErrorCode        string `json:"error,omitempty"`
	ErrorDescription string `json:"error_description,omitempty"`
	ErrorURI         string `json:"error_uri,omitempty"`
}

TokenErrorResponse represents an error response, described in https://www.rfc-editor.org/rfc/rfc6749#section-5.2 and https://www.rfc-editor.org/rfc/rfc8628#section-3.5

func (TokenErrorResponse) Error

func (err TokenErrorResponse) Error() string