oauth

README

oauth middleware

OAuth 2.0 Authorization Server & Authorization Middleware for go-chi

This library was ported to go-chi from https://github.com/maxzerbini/oauth by jeffreydwalter.

This library offers an OAuth 2.0 Authorization Server based on go-chi and an Authorization Middleware usable in Resource Servers developed with go-chi.

Build status

Authorization Server

The Authorization Server is implemented by the struct OAuthBearerServer that manages two grant types of authorizations (password and client_credentials). This Authorization Server is made to provide an authorization token usable for consuming resources API.

Password grant type

OAuthBearerServer supports the password grant type, allowing the token generation for username / password credentials.

Client Credentials grant type

OAuthBearerServer supports the client_credentials grant type, allowing the token generation for client_id / client_secret credentials.

Authorization Code and Implicit grant type

These grant types are currently partially supported implementing AuthorizationCodeVerifier interface. The method ValidateCode is called during the phase two of the authorization_code grant type evalutations.

Refresh token grant type

If authorization token will expire, the client can regenerate the token calling the authorization server and using the refresh_token grant type.

Authorization Middleware

The go-chi middleware BearerAuthentication intercepts the resource server calls and authorizes only resource requests containing a valid bearer token.

Token Formatter

Authorization Server crypts the token using the Token Formatter and Authorization Middleware decrypts the token using the same Token Formatter. This library contains a default implementation of the formatter interface called SHA256RC4TokenSecureFormatter based on the algorithms SHA256 and RC4. Programmers can develop their Token Formatter implementing the interface TokenSecureFormatter and this is really recommended before publishing the API in a production environment.

Credentials Verifier

The interface CredentialsVerifier defines the hooks called during the token generation process. The methods are called in this order:

• ValidateUser() or ValidateClient() called first for credentials verification
• AddClaims() used for add information to the token that will be encrypted
• StoreTokenID() called after the token generation but before the response, programmers can use this method for storing the generated IDs
• AddProperties() used for add clear information to the response

There is another method in the CredentialsVerifier interface that is involved during the refresh token process. In this case the methods are called in this order:

• ValidateTokenID() called first for TokenID verification, the method receives the TokenID related to the token associated to the refresh token
• AddClaims() used for add information to the token that will be encrypted
• StoreTokenID() called after the token regeneration but before the response, programmers can use this method for storing the generated IDs
• AddProperties() used for add clear information to the response

Authorization Server usage example

This snippet shows how to create an authorization server

func main() {
    r := chi.NewRouter()
    r.Use(middleware.Logger)
    r.Use(middleware.Recoverer)

    s := oauth.NewOAuthBearerServer(
        "mySecretKey-10101",
	time.Second*120,
	&TestUserVerifier{},
	nil)
	
    r.Post("/token", s.UserCredentials)
    r.Post("/auth", s.ClientCredentials)
    http.ListenAndServe(":8080", r)
}

See /test/authserver/main.go for the full example.

Authorization Middleware usage example

This snippet shows how to use the middleware

    r.Route("/", func(r chi.Router) {
	// use the Bearer Authentication middleware
	r.Use(oauth.Authorize("mySecretKey-10101", nil))

	r.Get("/customers", GetCustomers)
	r.Get("/customers/{id}/orders", GetOrders)
    }

See /test/resourceserver/main.go for the full example.

Note that the authorization server and the authorization middleware are both using the same token formatter and the same secret key for encryption/decryption.

Reference

• OAuth 2.0 RFC
• OAuth 2.0 Bearer Token Usage RFC

License

MIT

Documentation

Index

• Constants
• func Authorize(secretKey string, formatter TokenSecureFormatter) func(next http.Handler) http.Handler
• func CheckBasicAuthentication(username, password string, r *http.Request) error
• func GetBasicAuthentication(r *http.Request) (username, password string, err error)
• type AuthorizationCodeVerifier
• type BearerAuthentication
  • func NewBearerAuthentication(secretKey string, formatter TokenSecureFormatter) *BearerAuthentication
  • func (ba *BearerAuthentication) Authorize(next http.Handler) http.Handler
• type BearerServer
  • func NewBearerServer(secretKey string, ttl time.Duration, verifier CredentialsVerifier, ...) *BearerServer
  • func (bs *BearerServer) AuthorizationCode(w http.ResponseWriter, r *http.Request)
  • func (bs *BearerServer) ClientCredentials(w http.ResponseWriter, r *http.Request)
  • func (bs *BearerServer) UserCredentials(w http.ResponseWriter, r *http.Request)
• type CredentialsVerifier
• type GrantType
• type RC4TokenSecureFormatter
  • func NewRC4TokenSecurityProvider(key []byte) *RC4TokenSecureFormatter
  • func (sc *RC4TokenSecureFormatter) CryptToken(source []byte) ([]byte, error)
  • func (sc *RC4TokenSecureFormatter) DecryptToken(source []byte) ([]byte, error)
• type RefreshToken
• type SHA256RC4TokenSecureFormatter
  • func NewSHA256RC4TokenSecurityProvider(key []byte) *SHA256RC4TokenSecureFormatter
  • func (sc *SHA256RC4TokenSecureFormatter) CryptToken(source []byte) ([]byte, error)
  • func (sc *SHA256RC4TokenSecureFormatter) DecryptToken(source []byte) ([]byte, error)
• type Token
• type TokenProvider
  • func NewTokenProvider(formatter TokenSecureFormatter) *TokenProvider
  • func (tp *TokenProvider) CryptRefreshToken(t *RefreshToken) (token string, err error)
  • func (tp *TokenProvider) CryptToken(t *Token) (token string, err error)
  • func (tp *TokenProvider) DecryptRefreshTokens(refreshToken string) (refresh *RefreshToken, err error)
  • func (tp *TokenProvider) DecryptToken(token string) (t *Token, err error)
• type TokenResponse
• type TokenSecureFormatter
• type TokenType

Constants

const (
	CredentialContext  contextKey = "oauth.credential"
	ClaimsContext      contextKey = "oauth.claims"
	ScopeContext       contextKey = "oauth.scope"
	TokenTypeContext   contextKey = "oauth.tokentype"
	AccessTokenContext contextKey = "oauth.accesstoken"
)

Functions

func Authorize

func Authorize(secretKey string, formatter TokenSecureFormatter) func(next http.Handler) http.Handler

Authorize is the OAuth 2.0 middleware for go-chi resource server. Authorize creates a BearerAuthentication middleware and return the Authorize method.

func CheckBasicAuthentication

func CheckBasicAuthentication(username, password string, r *http.Request) error

Check Basic Authorization header credentials

func GetBasicAuthentication

func GetBasicAuthentication(r *http.Request) (username, password string, err error)

GetBasicAuthentication get username and password from Authorization header

Types

type AuthorizationCodeVerifier

type AuthorizationCodeVerifier interface {
	// ValidateCode checks the authorization code and returns the user credential
	ValidateCode(clientID, clientSecret, code, redirectURI string, r *http.Request) (string, error)
}

AuthorizationCodeVerifier defines the interface of the Authorization Code verifier

type BearerAuthentication

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

BearerAuthentication middleware for go-chi

func NewBearerAuthentication

func NewBearerAuthentication(secretKey string, formatter TokenSecureFormatter) *BearerAuthentication

NewBearerAuthentication create a BearerAuthentication middleware

func (*BearerAuthentication) Authorize

func (ba *BearerAuthentication) Authorize(next http.Handler) http.Handler

Authorize verifies the bearer token authorizing or not the request. Token is retrieved from the Authorization HTTP header that respects the format Authorization: Bearer {access_token}

type BearerServer

type BearerServer struct {
	TokenTTL time.Duration
	// contains filtered or unexported fields
}

BearerServer is the OAuth 2 bearer server implementation.

func NewBearerServer

func NewBearerServer(secretKey string, ttl time.Duration, verifier CredentialsVerifier, formatter TokenSecureFormatter) *BearerServer

NewBearerServer creates new OAuth 2 bearer server

func (*BearerServer) AuthorizationCode

func (bs *BearerServer) AuthorizationCode(w http.ResponseWriter, r *http.Request)

AuthorizationCode manages authorization code grant type requests for the phase two of the authorization process

func (*BearerServer) ClientCredentials

func (bs *BearerServer) ClientCredentials(w http.ResponseWriter, r *http.Request)

ClientCredentials manages client credentials grant type requests

func (*BearerServer) UserCredentials

func (bs *BearerServer) UserCredentials(w http.ResponseWriter, r *http.Request)

UserCredentials manages password grant type requests

type CredentialsVerifier

type CredentialsVerifier interface {
	// Validate username and password returning an error if the user credentials are wrong
	ValidateUser(username, password, scope string, r *http.Request) error
	// Validate clientID and secret returning an error if the client credentials are wrong
	ValidateClient(clientID, clientSecret, scope string, r *http.Request) error
	// Provide additional claims to the token
	AddClaims(tokenType TokenType, credential, tokenID, scope string, r *http.Request) (map[string]string, error)
	// Provide additional information to the authorization server response
	AddProperties(tokenType TokenType, credential, tokenID, scope string, r *http.Request) (map[string]string, error)
	// Optionally validate previously stored tokenID during refresh request
	ValidateTokenID(tokenType TokenType, credential, tokenID, refreshTokenID string) error
	// Optionally store the tokenID generated for the user
	StoreTokenID(tokenType TokenType, credential, tokenID, refreshTokenID string) error
}

CredentialsVerifier defines the interface of the user and client credentials verifier.

type GrantType

type GrantType string

const (
	PasswordGrant          GrantType = "password"
	ClientCredentialsGrant GrantType = "client_credentials"
	AuthCodeGrant          GrantType = "authorization_code"
	RefreshTokenGrant      GrantType = "refresh_token"
)

type RC4TokenSecureFormatter

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

func NewRC4TokenSecurityProvider

func NewRC4TokenSecurityProvider(key []byte) *RC4TokenSecureFormatter

func (*RC4TokenSecureFormatter) CryptToken

func (sc *RC4TokenSecureFormatter) CryptToken(source []byte) ([]byte, error)

func (*RC4TokenSecureFormatter) DecryptToken

func (sc *RC4TokenSecureFormatter) DecryptToken(source []byte) ([]byte, error)

type RefreshToken

type RefreshToken struct {
	CreationDate   time.Time `json:"date"`
	TokenID        string    `json:"id_token"`
	RefreshTokenID string    `json:"id_refresh_token"`
	Credential     string    `json:"credential"`
	TokenType      TokenType `json:"type"`
	Scope          string    `json:"scope"`
}

RefreshToken structure included in the authorization server response

type SHA256RC4TokenSecureFormatter

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

func NewSHA256RC4TokenSecurityProvider

func NewSHA256RC4TokenSecurityProvider(key []byte) *SHA256RC4TokenSecureFormatter

func (*SHA256RC4TokenSecureFormatter) CryptToken

func (sc *SHA256RC4TokenSecureFormatter) CryptToken(source []byte) ([]byte, error)

func (*SHA256RC4TokenSecureFormatter) DecryptToken

func (sc *SHA256RC4TokenSecureFormatter) DecryptToken(source []byte) ([]byte, error)

type Token

type Token struct {
	ID           string            `json:"id_token"`
	CreationDate time.Time         `json:"date"`
	ExpiresIn    time.Duration     `json:"expires_in"` // secs
	Credential   string            `json:"credential"`
	Scope        string            `json:"scope"`
	Claims       map[string]string `json:"claims"`
	TokenType    TokenType         `json:"type"`
}

Token structure generated by the authorization server

type TokenProvider

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

func NewTokenProvider

func NewTokenProvider(formatter TokenSecureFormatter) *TokenProvider

func (*TokenProvider) CryptRefreshToken

func (tp *TokenProvider) CryptRefreshToken(t *RefreshToken) (token string, err error)

func (*TokenProvider) CryptToken

func (tp *TokenProvider) CryptToken(t *Token) (token string, err error)

func (*TokenProvider) DecryptRefreshTokens

func (tp *TokenProvider) DecryptRefreshTokens(refreshToken string) (refresh *RefreshToken, err error)

func (*TokenProvider) DecryptToken

func (tp *TokenProvider) DecryptToken(token string) (t *Token, err error)

type TokenResponse

type TokenResponse struct {
	Token        string            `json:"access_token"`
	RefreshToken string            `json:"refresh_token"`
	TokenType    TokenType         `json:"token_type"` // bearer
	ExpiresIn    int64             `json:"expires_in"` // secs
	Properties   map[string]string `json:"properties"`
}

TokenResponse is the authorization server response

type TokenSecureFormatter

type TokenSecureFormatter interface {
	CryptToken(source []byte) ([]byte, error)
	DecryptToken(source []byte) ([]byte, error)
}

type TokenType

type TokenType string

const (
	BearerToken TokenType = "Bearer"
	AuthToken   TokenType = "A"
	UserToken   TokenType = "U"
	ClientToken TokenType = "C"
)