The highest tagged major version is
README
¶
oauth2
A fundamental and extendable OAuth2 library for Go.
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.
Specifications
The library considers and implements the following specifications:
- OAuth 2.0 Framework - RFC 6749
- Bearer Token Usage - RFC 6750
- Threat Model and Security Considerations - RFC 6819
Example
The example package implements a basic but feature-complete in-memory OAuth2 authentication server. The example can be used as a template to build a custom implementation of an OAuth2 compatible authentication server.
Installation
Get the package using the go tool:
$ go get -u github.com/gonfire/oauth2
License
The MIT License (MIT)
Copyright (c) 2016 Joël Gähwiler
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 KnownGrantType(str string) bool
- func KnownResponseType(str string) bool
- func Redirect(w http.ResponseWriter, uri string, params map[string]string, useFragment bool) error
- func RedirectCodeResponse(w http.ResponseWriter, uri string, res *CodeResponse) error
- func RedirectError(w http.ResponseWriter, uri string, useFragment bool, err error) error
- func RedirectTokenResponse(w http.ResponseWriter, uri string, res *TokenResponse) error
- func Write(w http.ResponseWriter, obj interface{}, status int) error
- func WriteError(w http.ResponseWriter, err error) error
- func WriteTokenResponse(w http.ResponseWriter, res *TokenResponse) error
- type AuthorizationRequest
- type CodeResponse
- type Error
- func AccessDenied(state, description string) *Error
- func InvalidClient(state, description string) *Error
- func InvalidGrant(state, description string) *Error
- func InvalidRequest(state, description string) *Error
- func InvalidScope(state, description string) *Error
- func ServerError(state, description string) *Error
- func TemporarilyUnavailable(state, description string) *Error
- func UnauthorizedClient(state, description string) *Error
- func UnsupportedGrantType(state, description string) *Error
- func UnsupportedResponseType(state, description string) *Error
- type Scope
- type TokenRequest
- type TokenResponse
Constants ¶
const ( // NoState is and can be used with all error builders to indicate that this // error gets constructed without including a state parameter. NoState = "" // NoDescription can be used with all error builders to indicate that this // error gets constructed without including a description parameter. NoDescription = "" )
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.
Variables ¶
This section is empty.
Functions ¶
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 Redirect ¶
Redirect 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 RedirectCodeResponse ¶
func RedirectCodeResponse(w http.ResponseWriter, uri string, res *CodeResponse) error
RedirectCodeResponse will write a redirection based on the specified code response to the response writer.
func RedirectError ¶
RedirectError will write a redirection based on the specified error to the response writer. The function will fall back and write a server error redirection if the specified error is not known.
func RedirectTokenResponse ¶
func RedirectTokenResponse(w http.ResponseWriter, uri string, res *TokenResponse) error
RedirectTokenResponse will write a redirection based on the specified token response to the response writer.
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 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.
func WriteTokenResponse ¶
func WriteTokenResponse(w http.ResponseWriter, res *TokenResponse) error
WriteTokenResponse will write the specified response to the response writer.
Types ¶
type AuthorizationRequest ¶
type AuthorizationRequest struct {
ResponseType string
Scope Scope
ClientID string
RedirectURI string
State string
HTTP *http.Request
}
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 functions validates basic constraints given by the OAuth2 spec.
type CodeResponse ¶
A CodeResponse is typically constructed after an authorization code request has been authenticated to return an authorization code.
func NewCodeResponse ¶
func NewCodeResponse(code 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"`
Description string `json:"error_description,omitempty"`
URI string `json:"error_uri,omitempty"`
Status int `json:"-"`
Headers map[string]string `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 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 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.
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.
type TokenRequest ¶
type TokenRequest struct {
GrantType string
Scope Scope
ClientID string
ClientSecret string
Username string
Password string
RefreshToken string
RedirectURI string
Code string
HTTP *http.Request
}
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 functions 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"`
}
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 NewTokenResponse ¶
func NewTokenResponse(tokenType, accessToken string, expiresIn int) *TokenResponse
NewTokenResponse constructs a TokenResponse.
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.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package bearer provides structures and functions to implement the additional OAuth2 Bearer Token specification.
|
Package bearer provides structures and functions to implement the additional OAuth2 Bearer Token specification. |
|
Package example implements a basic in-memory OAuth2 authentication server.
|
Package example implements a basic in-memory OAuth2 authentication server. |
|
Package hmacsha provides a simple token implementation using the hmac-sha256 algorithm.
|
Package hmacsha provides a simple token implementation using the hmac-sha256 algorithm. |
|
Package spec implements reusable integration tests to test against any OAuth2 authentication server.
|
Package spec implements reusable integration tests to test against any OAuth2 authentication server. |