OAuth 2.0 Authorization Server & Authorization Middleware for Gin-Gonic
This library offers an OAuth 2.0 Authorization Server based on Gin-Gonic and an Authorization Middleware usable in Resource Servers developed with Gin-Gonic.
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.
OAuthBearerServer supports the password grant type, allowing the token generation for username / password credentials.
OAuthBearerServer supports the client_credentials grant type, allowing the token generation for client_id / client_secret credentials.
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.
If authorization token will expire, the client can regenerate the token calling the authorization server and using the refresh_token grant type.
The Gin-Gonic middleware BearerAuthentication intercepts the resource server calls and authorizes only resource requests containing a valid bearer token.
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.
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
This snippet shows how to create an authorization server
func main() {
router := gin.New()
router.Use(gin.Recovery())
router.Use(gin.Logger())
s := oauth.NewOAuthBearerServer(
"mySecretKey-10101",
time.Second*120,
&TestUserVerifier{},
nil)
router.POST("/token", s.UserCredentials)
router.POST("/auth", s.ClientCredentials)
router.Run(":9090")
}See /test/authserver/main.go for the full example.
This snippet shows how to use the middleware
authorized := router.Group("/")
// use the Bearer Athentication middleware
authorized.Use(oauth.Authorize("mySecretKey-10101", nil))
authorized.GET("/customers", GetCustomers)
authorized.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.
This master branch introduces breaking changes in the interface CredentialsVerifier methods ValidateUser, ValidateClient and AddClaims. Refer to v1 branch for the previous implementation. Updated server implementation in v3 due to go.uuid library change.