gate

README

Gate

An authentication and RBAC authorization library using JWT for Go 1.7+

Features

• Simple and well-tested API
• Exported flexible contracts
• Developer friendly
• Persistence free

Supported authentication drivers

• Password-based authentication
• OAuth2

Installation

go get github.com/hiendv/gate

Usage

Quick example to get a taste of Gate

var auth gate.Auth
var user gate.User
var err error

// some construction codes go here

// Login using password-based authentication
user, err = auth.Login(map[string]string{"email": "email", "password": "password"})
if err != nil {
	log.Fatal("oops")
}

// Login using OAuth
// Redirect users to the authentication code URL
url, err := auth.LoginURL("state")

// Receive the code and exchange it
user, err = auth.Login(map[string]string{"code": "received-code"})
if err != nil {
	log.Fatal("oops")
}

// Issue the JWT for the user
jwt, err := auth.IssueJWT(user)
if err != nil {
	log.Fatal("oops")
}

// Send the JWT to the user and let them use it to authenticate
// Authenticate a user using JWT
user, err = auth.Authenticate("eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7ImlkIjoiaWQiLCJ1c2VybmFtZSI6InVzZXJuYW1lIiwicm9sZXMiOlsicm9sZSJdfSwiZXhwIjoxNjA1MDUyODAwLCJqdGkiOiJjbGFpbXMtaWQiLCJpYXQiOjE2MDUwNDkyMDB9.b0gxC2uZRek-SPwHSqyLOoW_DjSYroSivLqJG96Zxl0")
if err != nil {
	log.Fatal("oops")
}

err = auth.Authorize(user, "action", "object")

You may want to check these examples and tests:

• Password-based authentication examples, unit tests & integration tests
• OAuth2 authentication examples, unit tests & integration tests

Development & Testing

Please check the Contributing Guidelines.

Contribution

Issues and PRs are welcome !

Credits

The Gate bouncer logo is licensed under the Creative Commons 4.0 Attributions license.
The original gopher.svg was created by Takuya Ueda, licensed under the Creative Commons 3.0 Attributions license.
The Go Gopher was designed by Renee French, licensed under the Creative Commons 3.0 Attributions license.

Big thanks to:

• dgrijalva/jwt-go for the enormous help dealing with JWT works
• satori/go.uuid for the claims ID generator

Documentation

Overview

Package gate is an authentication and authorization library with a RBAC implementation for Go.

Index

• Variables
• func Authorize(auth Auth, user User, action, object string) (err error)
• type Auth
• type Config
  • func NewConfig(jwtSigningKey, jwtVerifyingKey interface{}, jwtExpiration time.Duration, ...) Config
  • func (config Config) JWTExpiration() time.Duration
  • func (config Config) JWTSigningKey() interface{}
  • func (config Config) JWTSkipClaimsValidation() bool
  • func (config Config) JWTVerifyingKey() interface{}
• type HasEmail
• type JWT
• type JWTClaims
• type JWTConfig
  • func NewHMACJWTConfig(alg string, key interface{}, expiration time.Duration, ...) (config JWTConfig, err error)
  • func NewJWTConfig(method jwt.SigningMethod, signKey, verifyKey interface{}, ...) JWTConfig
• type JWTService
  • func NewJWTService(config JWTConfig) *JWTService
  • func (service JWTService) Issue(claims JWTClaims) (token JWT, err error)
  • func (service JWTService) NewClaims(user User) JWTClaims
  • func (service JWTService) NewTokenFromClaims(claims JWTClaims) (token JWT)
  • func (service JWTService) Parse(tokenString string) (token JWT, err error)
• type Role
• type RoleService
• type TokenService
• type User
• type UserAbility
• type UserInfo
• type UserService

Variables

var (
	// ErrForbidden is thrown when an user is forbidden to take an action on an object
	ErrForbidden = errors.New("forbidden")

	// ErrNoAbilities is thrown when an user has no abilities
	ErrNoAbilities = errors.New("there is no abilities")
)

Functions

func Authorize

func Authorize(auth Auth, user User, action, object string) (err error)

Authorize performs the authorization when a given user takes an action on an object using RBAC

Types

type Auth

type Auth interface {
	UserService() (UserService, error)
	RoleService() (RoleService, error)
	TokenService() (TokenService, error)
	JWTService() (*JWTService, error)
	Matcher() (internal.Matcher, error)

	Login(map[string]string) (User, error)
	LoginURL(string) (string, error)

	IssueJWT(User) (JWT, error)
	ParseJWT(string) (JWT, error)
	StoreJWT(JWT) error

	Authenticate(string) (User, error)
	Authorize(User, string, string) error

	GetUserFromJWT(JWT) (User, error)
	GetUserAbilities(User) ([]UserAbility, error)
}

Auth is the common interface for authentication and authorization. E.g. PasswordBased, OAuth, etc.

type Config

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

Config is the configuration for Auth

func NewConfig

func NewConfig(jwtSigningKey, jwtVerifyingKey interface{}, jwtExpiration time.Duration, jwtSkipClaimsValidation bool) Config

NewConfig is the constructor for Config

func (Config) JWTExpiration

func (config Config) JWTExpiration() time.Duration

JWTExpiration is the setter for JWT expiration configuration

func (Config) JWTSigningKey

func (config Config) JWTSigningKey() interface{}

JWTSigningKey is the setter for JWT signing key configuration

func (Config) JWTSkipClaimsValidation

func (config Config) JWTSkipClaimsValidation() bool

JWTSkipClaimsValidation is the setter for JWT claims validation skip configuration

func (Config) JWTVerifyingKey

func (config Config) JWTVerifyingKey() interface{}

JWTVerifyingKey is the setter for JWT verifying key configuration

type HasEmail

type HasEmail interface {
	GetEmail() string
}

HasEmail is the contract for user service entity

type JWT

type JWT struct {
	ID        string
	Value     string
	UserID    string
	ExpiredAt time.Time
	IssuedAt  time.Time
}

JWT is the JSON Web Token

type JWTClaims

type JWTClaims struct {
	User UserInfo `json:"user"`
	jwt.StandardClaims
}

JWTClaims are JWT claims with user's information

type JWTConfig

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

JWTConfig is the configuration for JWT service

func NewHMACJWTConfig

func NewHMACJWTConfig(alg string, key interface{}, expiration time.Duration, skipClaimsValidation bool) (config JWTConfig, err error)

NewHMACJWTConfig is the constructor for JWTConfig using HMAC signing method

func NewJWTConfig

func NewJWTConfig(method jwt.SigningMethod, signKey, verifyKey interface{}, expiration time.Duration, skipClaimsValidation bool) JWTConfig

NewJWTConfig is the constructor for JWTConfig

type JWTService

type JWTService struct {
	Now              func() time.Time
	GenerateClaimsID func() string
	// contains filtered or unexported fields
}

JWTService is the service which manages JWTs

func NewJWTService

func NewJWTService(config JWTConfig) *JWTService

NewJWTService is the constructor for JWTService

func (JWTService) Issue

func (service JWTService) Issue(claims JWTClaims) (token JWT, err error)

Issue generates a token from JWT claims with the service configuration

func (JWTService) NewClaims

func (service JWTService) NewClaims(user User) JWTClaims

NewClaims generates JWTClaims for a specific user

func (JWTService) NewTokenFromClaims

func (service JWTService) NewTokenFromClaims(claims JWTClaims) (token JWT)

NewTokenFromClaims constructs a token from JWT claims

func (JWTService) Parse

func (service JWTService) Parse(tokenString string) (token JWT, err error)

Parse resolves a token string to a JWT with the service configuration

type Role

type Role interface {
	GetAbilities() []UserAbility
}

Role is the contract for the role entity

type RoleService

type RoleService interface {
	FindByIDs([]string) ([]Role, error)
}

RoleService is the contract which offers queries on the role entity

type TokenService

type TokenService interface {
	FindOneByID(string) (JWT, error)
	Store(JWT) error
}

TokenService is the contract which offers queries on the token entity

type User

type User interface {
	GetID() string
	GetEmail() string
	GetRoles() []string
}

User is the contract for the user entity

type UserAbility

type UserAbility interface {
	GetAction() string
	GetObject() string
}

UserAbility is the contract for the ability entity

type UserInfo

type UserInfo struct {
	ID    string   `json:"id"`
	Email string   `json:"email"`
	Roles []string `json:"roles"`
}

UserInfo is the user information entity

type UserService

type UserService interface {
	FindOneByID(string) (User, error)
	FindOrCreateOneByEmail(string) (User, error)
	FindOneByEmail(string) (User, error)
}

UserService is the contract which offers queries on the user entity