README
¶
OAuth2 Security
This package contains functions and types for enabling OAuth2 as a security mechanism in a microservice. It integrates with Goa generated OAuth2 security and also as part of the SecurityChain.
Setting up a OAuth2 security
There are a couple of things you need to do to enable the OAuth2 security middleware. For details on OAuth2 you can find many resources on the official site: https://oauth.net.
Setting up the secret keys
Create a directory in which you'll keep your key-pair:
mkdir rsa-keys
cd rsa-keys
The generate 2048-bit RSA key pair:
openssl genrsa -des3 -out private.pem 2048
The output the keys in PEM form:
openssl rsa -in private.pem -outform PEM -pubout -out public.pub
Remove passphrase
openssl rsa -in private.pem -out withoutPassphrase.pem
NOTE: Make sure that the public key ends in .pub. This is how the default
key resolver of the library locates the public keys.
Set up OAuth2 with Goagen
Create a security file app/security.go with the following content:
package app
import (
"github.com/keitaroinc/goa"
)
// NewOAuth2Security creates a OAuth2 security definition.
func NewOAuth2Security() *goa.OAuth2Security {
def := goa.OAuth2Security{
Flow: "accessCode",
TokenURL: "http://localhost:8080/oauth2/token",
AuthorizationURL: "http://localhost:8080/oauth2/authorize",
Scopes: map[string]string{
"api:read": "no description",
"api:write": "no description",
}}
return &def
}
More details on how to configure the OAuth2 security are available on the official documentation:
- Docs: https://goa.design/implement/security/
- Example: https://github.com/goadesign/examples/blob/master/security/oauth2.go
Setting up a SecurityChain
Once the security specs are generated by Goa, you need to set up a security chain for the microservice.
In the main.go file of your microservice, set up the JWT Security Chain
middleware and add it to the security chain.
import (
"github.com/Microkubes/microservice-security/oauth2"
"github.com/Microkubes/microservice-security/chain"
)
func main() {
// Create new OAuth2 security chain
// "rsa-keys" is the directory containing the RSA keys
// app.NewOAuth2Security() creates the OAuth2Security scheme structure
OAUTH2Middleware := oauth2.NewOAuth2Security("rsa-keys", app.NewOAuth2Security())
sc := chain.NewSecurityChain().AddMiddleware(OAUTH2Middleware)
// other initializations here...
service.Use(chain.AsGoaMiddleware(sc)) // attach the security chain as Goa middleware
}
Testing the setup
To test the setup, you'll need to generate and sign a JWT token, then use it in the request header.
To generate a JWT, you can use different tools. In this example we'll use jwtgen command line tool. To install it:
npm install -g jwtgen
Then, to generate the JWT token, type:
jwtgen -a RS256\
-p rsa-keys/withoutPassphrase.pem\
-c "userId=599316bbf456208abcbcc186" \
-c "username=test-user"\
-c "roles=user,admin"\
-c "scopes=api:read api:write"\
-c "organizations=Org1,Org2"
which will output the JWT:
eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpYXQiOjE1MDM0NzQxOTcsInVzZXJJZCI6IjU5OTMxNmJiZjQ
1NjIwOGFiY2JjYzE4NiIsInVzZXJuYW1lIjoidGVzdC11c2VyIiwicm9sZXMiOiJ1c2VyLGFkbWluIiwic2NvcGV
zIjoiYXBpOnJlYWQgYXBpOndyaXRlIiwib3JnYW5pemF0aW9ucyI6Ik9yZzEsT3JnMiJ9.WUILgtGMgILtlUSrP9
MHbNfiD1-q4mIvw-UbOqjrg4HnMLvTyXMD7Td4H4yeSjThJZxEzglUf3JdMu8_8Xf4CRnAPLqeiDOSia8SWRQeRG
majagiOkRPWYp0Ns7zlsguSXuPJ64RN2eik7ROV43qtnwahHGTfyjducSNMyK9OqzacciZE2G1WDlMlbSb2p1fZZ
oXr7je6r64qfW2g1HWjG8ojXmmqbxZO5RURUgly9fUOkPBq-y5E2yq3mZ1FdPoqi7QQ9ZeUnRv4-m0q8kXVqY3P9
4uc3HYRXxd35jBQP0JfU_aVzr_eL7b16QbyT7O_dTsbUOcOvcm4Hh54Gu4Mg
(Note that the JWT is actually one line. For readability purposes it is displayed here in multiple lines.)
Then you'll need to add the token in the Authorization HTTP header of the request.
curl --header "Authorization: Bearer eyJ0eXAiOiJKV1Q...<full token here>...4pfw" "http://localhost:8080/profiles/me"
Documentation
¶
Index ¶
- Constants
- Variables
- func CompareRedirectURI(registered, provided string) error
- func GenerateRandomCode(n int) (string, error)
- func NewOAuth2Security(keysDir string, scheme *goa.OAuth2Security) chain.SecurityChainMiddleware
- func NewOAuth2SecurityMiddleware(resolver goaJwt.KeyResolver, scheme *goa.OAuth2Security) goa.Middleware
- type AuthProvider
- func (provider *AuthProvider) Authenticate(clientID, clientSecret string) error
- func (provider *AuthProvider) Authorize(clientID, scope, redirectURI string) (code string, err error)
- func (provider *AuthProvider) Exchange(clientID, code, redirectURI string) (refreshToken, accessToken string, expiresIn int, err error)
- func (provider *AuthProvider) Refresh(refreshToken, scope string) (newRefreshToken, accessToken string, expiresIn int, err error)
- type AuthToken
- type Client
- type ClientAuth
- type ClientService
- type TokenService
- type User
- type UserService
Constants ¶
const OAuth2SecurityType = "OAuth2"
OAuth2SecurityType is the name of the security type (JWT, OAUTH2, SAML...)
Variables ¶
var InternalServerError = goa.NewErrorClass("server_error", 500)
InternalServerError is a generic server error
var OAuth2AccessDenied = goa.NewErrorClass("access_denied", 403)
OAuth2AccessDenied is an access denied error for created auth
var OAuth2ErrorInvalidRedirectURI = goa.NewErrorClass("invalid_request", 400)
OAuth2ErrorInvalidRedirectURI is Bad Request error for invalid redirect URI
var OAuth2ErrorInvalidScope = goa.NewErrorClass("invalid_scope", 400)
OAuth2ErrorInvalidScope is Bad Request error for invalid scope requested
OAuth2ErrorUnauthorizedClient is an error for bad client credentials
Functions ¶
func CompareRedirectURI ¶
CompareRedirectURI compares the registered redirect URI with a provided one.
func GenerateRandomCode ¶
GenerateRandomCode generates a cryptographically strong random string with the specified length.
func NewOAuth2Security ¶
func NewOAuth2Security(keysDir string, scheme *goa.OAuth2Security) chain.SecurityChainMiddleware
NewOAuth2Security creates a OAuth2 SecurityChainMiddleware using a simple key resolver that loads the public keys from the keysDir. The key files must end in *.pub. The scheme is obtained from app/security.go.
func NewOAuth2SecurityMiddleware ¶
func NewOAuth2SecurityMiddleware(resolver goaJwt.KeyResolver, scheme *goa.OAuth2Security) goa.Middleware
NewOAuth2SecurityMiddleware creates a middleware that checks for the presence of an authorization header and validates its content. The steps taken by the middleware are: 1. Validate the "Bearer" token present in the "Authorization" header against the key(s) 2. If scopes are defined for the action validate them against the "scopes" JWT claim
Types ¶
type AuthProvider ¶
type AuthProvider struct {
ClientService
UserService
TokenService
tools.KeyStore
SigningMethod string
AuthCodeLength int
RefreshTokenLength int
AccessTokenValidityPeriod int
ProviderName string
}
AuthProvider holds the data for implementing the oauth2.Provider interface.
func (*AuthProvider) Authenticate ¶
func (provider *AuthProvider) Authenticate(clientID, clientSecret string) error
Authenticate checks the client credentials.
func (*AuthProvider) Authorize ¶
func (provider *AuthProvider) Authorize(clientID, scope, redirectURI string) (code string, err error)
Authorize performs the authorization of a client and generates basic ClientAuth.
type AuthToken ¶
type AuthToken struct {
// AccessToken is the actual value of the access token.
AccessToken string `json:"accessToken, omitempty" bson:"accessToken"`
// RefreshToken holds the refresh token value.
RefreshToken string `json:"refreshToken, omitempty" bson:"refreshToken"`
// Unix timestamp of the time when the access token was issued.
IssuedAt int64 `json:"issuedAt, omitempty" bson:"issuedAt"`
// ValidFor is the time duration for which this token is valid. Expressed in milliseconds.
ValidFor int `json:"validFor, omitempty" bson:"validFor"`
// Scope is the scope for which this access token is valid.
Scope string `json:"scope, omitempty" bson:"scope"`
// ClientID is the reference to the client for which this token has been issued.
ClientID string `json:"clientId, omitempty" bson:"clientId"`
// UserID is the reference to the user for which this token has been issued.
UserID string `json:"userId, omitempty" bson:"userId"`
}
AuthToken holds the data for oauth2 token.
type Client ¶
type Client struct {
ClientID string `json:"clientId, omitempty"`
Name string `json:"name, omitempty"`
Description string `json:"description, omitempty"`
Website string `json:"domain, omitempty"`
Secret string `json:"secret, omitempty"`
}
Client holds the data for a specific client (app). A client must firt be registered for access on the platform.
type ClientAuth ¶
type ClientAuth struct {
ClientID string `json:"clientId, omitempty" bson:"clientId"`
UserID string `json:"userId, omitempty" bson:"userId"`
Scope string `json:"scope, omitempty" bson:"scope"`
Code string `json:"code, omitempty" bson:"code"`
GeneratedAt int64 `json:"generatedAt, omitempty" bson:"generatedAt"`
UserData string `json:"userData, omitempty" bson:"userData"`
RedirectURI string `json:"redirectUri, omitempty" bson:"redirectUri"`
Confirmed bool `json:"confirmed, omitempty" bson:"confirmed"`
}
ClientAuth is an authorization record for a specific client (app) and user. It holds the data for a specific client that is (or needs to be) authorized by a user to access some part of the platform.
type ClientService ¶
type ClientService interface {
// GetClient retrieves a Client by its ID.
GetClient(clientID string) (*Client, error)
// VerifyClientCredentials verfies that there is a registered Client with the specified client ID and client secret.
// It returns the actual Client data if the credentials are valid, or nil if there is no such client.
VerifyClientCredentials(clientID, clientSecret string) (*Client, error)
// SaveClientAuth stores a ClientAuth.
SaveClientAuth(clientAuth *ClientAuth) error
// GetClientAuth retrieves a ClientAuth for the specified client ID and a generated random code for verification.
GetClientAuth(clientID, code string) (*ClientAuth, error)
// GetClientAuthForUser retrieves a ClientAuth for a Client and User.
// Used when is situations where the access code is still not generated.
GetClientAuthForUser(userID, clientID string) (*ClientAuth, error)
// ConfirmClientAuth updates the Confirmed field (sets it to true).
// Used to update the client auth once the user has accepted the client to access the data.
ConfirmClientAuth(userID, clientID string) (*ClientAuth, error)
// UpdateUserData updates the ClientAuth with the full user data.
// This is techincally a workaround since the goa-oauth2 Provider does not take
// into account the user in the access_grant flow.
UpdateUserData(clientID, code, userID, userData string) error
// DeleteClientAuth deletes the ClientAuth.
// If you never call this, the ClientAuth should expire automatically after a certain period.
DeleteClientAuth(clientID, code string) error
}
ClientService is an interface that defines the access to a Client and ClientAuth.
type TokenService ¶
type TokenService interface {
// SaveToken saves the token data to the backend.
SaveToken(token AuthToken) error
// GetToken retrieves the OAuth2Token for a refreshToken.
GetToken(refreshToken string) (*AuthToken, error)
// GetTokenForClient looks up an OAuth2Token for a specific client and user.
// There should be only one such token.
GetTokenForClient(userID, clientID string) (*AuthToken, error)
}
TokenService defines the interface for managing OAuth2 Tokens.
type User ¶
type User struct {
ID string `json:"id, omitempty"`
Username string `json:"username, omitempty"`
Email string `json:"email, omitempty"`
Roles []string `json:"roles, omitempty"`
Organizations []string `json:"organizations, omitempty"`
Namespaces []string `json:"namespaces, omitempty"`
ExternalID string `json:"externalId, omitempty"`
Active bool `json:"active, omitempty"`
}
User holds the user data.
type UserService ¶
type UserService interface {
// VerifyUser verifies the credentials (username and password) and retrieves a
// User if the credentials are valid.
VerifyUser(username, password string) (*User, error)
}
UserService defines an interface for verification of the user credentials. This is used in the access_grant flow, to login the user and then prompt it for confirmation about authorizing the client to access the services on the platform.
Source Files