Documentation
¶
Overview ¶
Package oauth2 provides structures and functions to implement OAuth2 compatible authentication servers.
The library can be used standalone or with any framework as it is built on top of the standard Go http library.
Index ¶
- Constants
- func BuildIntrospectionRequest(uri string, r IntrospectionRequest) (*http.Request, error)
- func BuildRevocationRequest(uri string, r RevocationRequest) (*http.Request, error)
- func BuildTokenRequest(uri string, r TokenRequest) (*http.Request, error)
- func IntrospectionRequestValues(r IntrospectionRequest) url.Values
- func KnownGrantType(str string) bool
- func KnownResponseType(str string) bool
- func KnownTokenType(str string) bool
- func ParseBearerToken(r *http.Request) (string, error)
- func ParseRequestError(res *http.Response, limit int64) error
- func RevocationRequestValues(r RevocationRequest) url.Values
- func TokenRequestValues(r TokenRequest) url.Values
- func Write(w http.ResponseWriter, obj interface{}, status int) error
- func WriteBearerError(w http.ResponseWriter, err error) error
- func WriteCodeResponse(w http.ResponseWriter, r *CodeResponse) error
- func WriteError(w http.ResponseWriter, err error) error
- func WriteIntrospectionResponse(w http.ResponseWriter, r *IntrospectionResponse) error
- func WriteRedirect(w http.ResponseWriter, uri string, params map[string]string, useFragment bool) error
- func WriteTokenResponse(w http.ResponseWriter, r *TokenResponse) error
- type AuthorizationRequest
- type Client
- type ClientConfig
- type CodeResponse
- type Error
- func AccessDenied(description string) *Error
- func InsufficientScope(necessaryScope Scope) *Error
- func InvalidClient(description string) *Error
- func InvalidGrant(description string) *Error
- func InvalidRequest(description string) *Error
- func InvalidScope(description string) *Error
- func InvalidToken(description string) *Error
- func ProtectedResource() *Error
- func ServerError(description string) *Error
- func TemporarilyUnavailable(description string) *Error
- func UnauthorizedClient(description string) *Error
- func UnsupportedGrantType(description string) *Error
- func UnsupportedResponseType(description string) *Error
- func UnsupportedTokenType(description string) *Error
- type HS256Token
- type IntrospectionRequest
- type IntrospectionResponse
- type RevocationRequest
- type Scope
- type Server
- type ServerConfig
- type ServerCredential
- type ServerEntity
- type TokenRequest
- type TokenResponse
Constants ¶
const ( PasswordGrantType = "password" ClientCredentialsGrantType = "client_credentials" AuthorizationCodeGrantType = "authorization_code" RefreshTokenGrantType = "refresh_token" )
The known OAuth2 grant types.
const ( TokenResponseType = "token" CodeResponseType = "code" )
The known OAuth2 response types.
const ( AccessToken = "access_token" RefreshToken = "refresh_token" )
The known OAuth2 token types.
const BearerAccessTokenType = "bearer"
BearerAccessTokenType is the bearer access token type as defined by the OAuth2 Bearer Token spec.
Variables ¶
This section is empty.
Functions ¶
func BuildIntrospectionRequest ¶
func BuildIntrospectionRequest(uri string, r IntrospectionRequest) (*http.Request, error)
BuildIntrospectionRequest will build the provided request.
func BuildRevocationRequest ¶
func BuildRevocationRequest(uri string, r RevocationRequest) (*http.Request, error)
BuildRevocationRequest will build the provided request.
func BuildTokenRequest ¶
func BuildTokenRequest(uri string, r TokenRequest) (*http.Request, error)
BuildTokenRequest will build a request from the provided data.
func IntrospectionRequestValues ¶
func IntrospectionRequestValues(r IntrospectionRequest) url.Values
IntrospectionRequestValues will return the form values for the provided request.
func KnownGrantType ¶
KnownGrantType returns true if the grant type is a known grant type (e.g. password, client credentials, authorization code or refresh token).
func KnownResponseType ¶
KnownResponseType returns true if the response type is a known response type (e.g. token or code).
func KnownTokenType ¶
KnownTokenType returns true if the token type is a known token type (e.g. access token or refresh token).
func ParseBearerToken ¶
ParseBearerToken parses and returns the bearer token from a request. It will return an Error if the extraction failed.
Note: The spec also allows obtaining the bearer token from query parameters and the request body (form data). This implementation only supports obtaining the token from the "Authorization" header as this is the most common use case and considered most secure.
func ParseRequestError ¶
ParseRequestError will try to parse an oauth2.Error from the provided response. It will fall back to an error containing the response status.
func RevocationRequestValues ¶
func RevocationRequestValues(r RevocationRequest) url.Values
RevocationRequestValues will return the form values for the provided request.
func TokenRequestValues ¶
func TokenRequestValues(r TokenRequest) url.Values
TokenRequestValues will return the form values for the provided request.
func Write ¶
func Write(w http.ResponseWriter, obj interface{}, status int) error
Write will encode the specified object as json and write a response to the response writer as specified by the OAuth2 spec.
func WriteBearerError ¶
func WriteBearerError(w http.ResponseWriter, err error) error
WriteBearerError will write the specified error to the response writer. The function will fall back and write an internal server error if the specified error is not known.
Common bearer token errors: ProtectedResource, InvalidRequest, InvalidToken, InsufficientScope, ServerError.
func WriteCodeResponse ¶
func WriteCodeResponse(w http.ResponseWriter, r *CodeResponse) error
WriteCodeResponse will write a redirection based on the specified code response to the response writer.
func WriteError ¶
func WriteError(w http.ResponseWriter, err error) error
WriteError will write the specified error to the response writer. The function will fall back and write a server error if the specified error is not known. If the RedirectURI field is present on the error a redirection will be written instead.
func WriteIntrospectionResponse ¶
func WriteIntrospectionResponse(w http.ResponseWriter, r *IntrospectionResponse) error
WriteIntrospectionResponse will write a response to the response writer.
func WriteRedirect ¶
func WriteRedirect(w http.ResponseWriter, uri string, params map[string]string, useFragment bool) error
WriteRedirect will either add the specified parameters to the query of the specified uri or encode them and it as the fragment as specified by the OAuth2 spec.
func WriteTokenResponse ¶
func WriteTokenResponse(w http.ResponseWriter, r *TokenResponse) error
WriteTokenResponse will write the specified response to the response writer. If the RedirectURI field is present on the response a redirection that transmits the token in the fragment will be written instead.
Types ¶
type AuthorizationRequest ¶
type AuthorizationRequest struct { ResponseType string Scope Scope ClientID string RedirectURI string State string }
A AuthorizationRequest is typically returned by ParseAuthorizationRequest and holds all information necessary to handle an authorization request.
func ParseAuthorizationRequest ¶
func ParseAuthorizationRequest(r *http.Request) (*AuthorizationRequest, error)
ParseAuthorizationRequest parses an incoming request and returns an AuthorizationRequest. The function validates basic constraints given by the OAuth2 spec.
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client is a low-level OAuth2 client.
func NewClient ¶
func NewClient(config ClientConfig) *Client
NewClient will create and return a new client.
func NewClientWithClient ¶
func NewClientWithClient(config ClientConfig, client *http.Client) *Client
NewClientWithClient will create and return a new client using the provided client.
func (*Client) Authenticate ¶
func (c *Client) Authenticate(trq TokenRequest) (*TokenResponse, error)
Authenticate will send the provided token request and return the servers token response or an error if failed.
func (*Client) Introspect ¶
func (c *Client) Introspect(irq IntrospectionRequest) (*IntrospectionResponse, error)
Introspect will send the provided introspection request and return the server response or an error if failed.
func (*Client) Revoke ¶
func (c *Client) Revoke(rrq RevocationRequest) error
Revoke will send the provided revocation request and return and error if it failed.
type ClientConfig ¶
type ClientConfig struct { BaseURI string TokenEndpoint string IntrospectionEndpoint string RevocationEndpoint string ResponseLimit int64 }
ClientConfig is used to configure a client.
func Default ¶
func Default(baseURI string) ClientConfig
Default will return a default configuration.
type CodeResponse ¶
type CodeResponse struct { Code string `json:"code"` State string `json:"state,omitempty"` RedirectURI string `json:"-"` }
A CodeResponse is typically constructed after an authorization code request has been authenticated to return an authorization code.
func NewCodeResponse ¶
func NewCodeResponse(code, redirectURI, state string) *CodeResponse
NewCodeResponse constructs a CodeResponse.
func (*CodeResponse) Map ¶
func (r *CodeResponse) Map() map[string]string
Map returns a map of all fields that can be presented to the client. This method can be used to construct query parameters or a fragment when redirecting the code response.
type Error ¶
type Error struct { Name string `json:"error"` State string `json:"state,omitempty"` Scope Scope `json:"scope,omitempty"` Realm string `json:"realm,omitempty"` Description string `json:"error_description,omitempty"` URI string `json:"error_uri,omitempty"` Status int `json:"-"` Headers map[string]string `json:"-"` RedirectURI string `json:"-"` UseFragment bool `json:"-"` }
An Error represents an error object defined by the OAuth2 specification. All functions that are used during the authorization and token request processing flow return such error instances.
func AccessDenied ¶
AccessDenied constructs an error that indicates that the resource owner or authorization server denied the request.
func InsufficientScope ¶
InsufficientScope constructs and error that indicates that the request requires higher privileges than provided by the access token.
func InvalidClient ¶
InvalidClient constructs an error that indicates that the client authentication failed (e.g., unknown client, no client authentication included, or unsupported authentication method).
func InvalidGrant ¶
InvalidGrant constructs an error that indicates that the provided authorization grant (e.g., authorization code, resource owner credentials) or refresh token is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client.
func InvalidRequest ¶
InvalidRequest constructs an error that indicates that the request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed.
func InvalidScope ¶
InvalidScope constructs an error that indicates that the requested scope is invalid, unknown, malformed, or exceeds the scope granted by the resource owner.
func InvalidToken ¶
InvalidToken constructs and error that indicates that the access token provided is expired, revoked, malformed, or invalid for other reasons.
func ProtectedResource ¶
func ProtectedResource() *Error
ProtectedResource constructs and error that indicates that the requested resource needs authentication.
func ServerError ¶
ServerError constructs an error that indicates that the authorization server encountered an unexpected condition that prevented it from fulfilling the request.
func TemporarilyUnavailable ¶
TemporarilyUnavailable constructs an error that indicates that the authorization server is currently unable to handle the request due to a temporary overloading or maintenance of the server.
func UnauthorizedClient ¶
UnauthorizedClient constructs an error that indicates that the authenticated client is not authorized to use this authorization grant type or method to request and access token.
func UnsupportedGrantType ¶
UnsupportedGrantType constructs an error that indicates that the authorization grant type is not supported by the authorization server.
func UnsupportedResponseType ¶
UnsupportedResponseType constructs an error that indicates that the authorization server does not support obtaining an access token using this method.
func UnsupportedTokenType ¶
UnsupportedTokenType constructs an error that indicates that the authorization server does not support the introspection of the presented token type.
func (*Error) Map ¶
Map returns a map of all fields that can be presented to the client. This method can be used to construct query parameters or a fragment when redirecting the error.
func (*Error) SetRedirect ¶
SetRedirect marks the error to be redirected by setting the state value as well as the redirect URI and whether the error should be added to the query parameter or fragment part of the URI.
type HS256Token ¶
HS256Token implements a simple abstraction around generating token using the hmac-sha256 algorithm.
func GenerateHS256Token ¶
func GenerateHS256Token(secret []byte, length int) (*HS256Token, error)
GenerateHS256Token will return a new hmac-sha256 token that is constructed using the specified secret and random key of the specified length.
Note: The secret and the to be generated token key should both at least have a length of 16 characters to be considered unguessable.
func HS256TokenFromKey ¶
func HS256TokenFromKey(secret []byte, key []byte) *HS256Token
HS256TokenFromKey will return a new hmac-sha256 token that is constructed using the specified secret and key.
Note: The secret and the token key should both at least have a length of 16 characters to be considered unguessable.
func MustGenerateHS256Token ¶
func MustGenerateHS256Token(secret []byte, length int) *HS256Token
MustGenerateHS256Token will generate a token using GenerateHS256Token and panic instead of returning an error.
Note: The cryptographically secure pseudo-random number generator provided by the operating system may fail. However, such a fail would mean that something seriously must be wrong with the machine running this code.
func ParseHS256Token ¶
func ParseHS256Token(secret []byte, str string) (*HS256Token, error)
ParseHS256Token will parse a token that is in its string representation.
func (*HS256Token) Equal ¶
func (t *HS256Token) Equal(signature []byte) bool
Equal returns true then the specified signature is the same as the token signature.
Note: This method should be used over just comparing the byte slices as it computed in constant time and limits time based attacks.
func (*HS256Token) KeyString ¶
func (t *HS256Token) KeyString() string
KeyString returns a string (base64) representation of the key.
func (*HS256Token) SignatureString ¶
func (t *HS256Token) SignatureString() string
SignatureString returns a string (base64) representation of the signature.
func (*HS256Token) String ¶
func (t *HS256Token) String() string
String returns a string representation of the whole token.
func (*HS256Token) Valid ¶
func (t *HS256Token) Valid(secret []byte) bool
Valid returns true when the token's key matches its signature.
type IntrospectionRequest ¶
type IntrospectionRequest struct { Token string TokenTypeHint string ClientID string ClientSecret string }
A IntrospectionRequest is returned by ParseIntrospectionRequest and holds all information necessary to handle an introspection request.
func ParseIntrospectionRequest ¶
func ParseIntrospectionRequest(r *http.Request) (*IntrospectionRequest, error)
ParseIntrospectionRequest parses an incoming request and returns an IntrospectionRequest. The function validates basic constraints given by the OAuth2 spec.
type IntrospectionResponse ¶
type IntrospectionResponse struct { Active bool `json:"active"` Scope Scope `json:"scope,omitempty"` ClientID string `json:"client_id,omitempty"` Username string `json:"username,omitempty"` TokenType string `json:"token_type,omitempty"` ExpiresAt int64 `json:"exp,omitempty"` IssuedAt int64 `json:"iat,omitempty"` NotBefore int64 `json:"nbf,omitempty"` Subject string `json:"sub,omitempty"` Audience string `json:"aud,omitempty"` Issuer string `json:"iss,omitempty"` Identifier string `json:"jti,omitempty"` Extra map[string]interface{} `json:"extra,omitempty"` }
IntrospectionResponse is a response returned by the token introspection endpoint.
func NewIntrospectionResponse ¶
func NewIntrospectionResponse(active bool, scope Scope, clientID, username, tokenType string) *IntrospectionResponse
NewIntrospectionResponse constructs an IntrospectionResponse.
func ParseIntrospectionResponse ¶
func ParseIntrospectionResponse(res *http.Response, limit int64) (*IntrospectionResponse, error)
ParseIntrospectionResponse will parse the provided response.
type RevocationRequest ¶
type RevocationRequest struct { Token string TokenTypeHint string ClientID string ClientSecret string }
A RevocationRequest is returned by ParseRevocationRequest and holds all information necessary to handle a revocation request.
func ParseRevocationRequest ¶
func ParseRevocationRequest(r *http.Request) (*RevocationRequest, error)
ParseRevocationRequest parses an incoming request and returns a RevocationRequest. The function validates basic constraints given by the OAuth2 spec.
type Scope ¶
type Scope []string
A Scope is received typically in an authorization and token request.
func ParseScope ¶
ParseScope parses the joined string representation of a scope.
func (Scope) MarshalJSON ¶
MarshalJSON implements the json.Marshaler interface.
func (*Scope) UnmarshalJSON ¶ added in v2.2.0
UnmarshalJSON implements the json.Unmarshaler interface.
type Server ¶
type Server struct { Config ServerConfig Clients map[string]*ServerEntity Users map[string]*ServerEntity AccessTokens map[string]*ServerCredential RefreshTokens map[string]*ServerCredential AuthorizationCodes map[string]*ServerCredential Mutex sync.Mutex }
Server implements a basic in-memory OAuth2 authentication server intended for testing purposes.
func NewServer ¶
func NewServer(config ServerConfig) *Server
NewServer creates and returns a new server.
type ServerConfig ¶
type ServerConfig struct { Secret []byte KeyLength int AllowedScope Scope AccessTokenLifespan time.Duration RefreshTokenLifespan time.Duration AuthorizationCodeLifespan time.Duration }
ServerConfig is used to configure a server.
func DefaultServerConfig ¶
func DefaultServerConfig(secret []byte, allowed Scope) ServerConfig
DefaultServerConfig will return a default configuration.
func (ServerConfig) MustGenerate ¶
func (c ServerConfig) MustGenerate() *HS256Token
MustGenerate will generate a new token.
type ServerCredential ¶
type ServerCredential struct { ClientID string Username string ExpiresAt time.Time Scope Scope RedirectURI string Code string Used bool }
ServerCredential represents an access token, refresh token or authorization code.
type ServerEntity ¶
ServerEntity represents a client or resource owner.
type TokenRequest ¶
type TokenRequest struct { GrantType string Scope Scope ClientID string ClientSecret string Username string Password string RefreshToken string RedirectURI string Code string }
A TokenRequest is typically returned by ParseTokenRequest and holds all information necessary to handle a token request.
func ParseTokenRequest ¶
func ParseTokenRequest(r *http.Request) (*TokenRequest, error)
ParseTokenRequest parses an incoming request and returns a TokenRequest. The function validates basic constraints given by the OAuth2 spec.
Note: Obtaining the client id and secret from the request body (form data) is not implemented by default due to security considerations.
type TokenResponse ¶
type TokenResponse struct { TokenType string `json:"token_type"` AccessToken string `json:"access_token"` ExpiresIn int `json:"expires_in"` RefreshToken string `json:"refresh_token,omitempty"` Scope Scope `json:"scope,omitempty"` State string `json:"state,omitempty"` RedirectURI string `json:"-"` }
A TokenResponse is typically constructed after a token request has been authenticated and authorized to return an access token, a potential refresh token and more detailed information.
func NewBearerTokenResponse ¶
func NewBearerTokenResponse(token string, expiresIn int) *TokenResponse
NewBearerTokenResponse creates and returns a new token response that carries a bearer access token.
func NewTokenResponse ¶
func NewTokenResponse(tokenType, accessToken string, expiresIn int) *TokenResponse
NewTokenResponse constructs a TokenResponse.
func ParseTokenResponse ¶
func ParseTokenResponse(res *http.Response, limit int64) (*TokenResponse, error)
ParseTokenResponse will parse the provided response.
func (*TokenResponse) Map ¶
func (r *TokenResponse) Map() map[string]string
Map returns a map of all fields that can be presented to the client. This method can be used to construct query parameters or a fragment when redirecting the token response.
func (*TokenResponse) SetRedirect ¶
func (r *TokenResponse) SetRedirect(uri, state string) *TokenResponse
SetRedirect marks the response to be redirected by setting the redirect URI and state.
Source Files
¶
Directories
¶
Path | Synopsis |
---|---|
Package oauth2test implements reusable integration tests to run against any OAuth2 authentication server.
|
Package oauth2test implements reusable integration tests to run against any OAuth2 authentication server. |