gocloakecho

README

gocloak-echo

Keycloak handler & middleware for echo

This project is still WiP and the interfaces might change pretty often

Supported authentication flows:

• Direct Grant Flow

Use this together with the keycloak client gocloak

Usage examples

• Install the package

go get "github.com/Nerzal/gocloak/v9"

// AuthenticationHandler is used to authenticate with the api
type AuthenticationHandler interface {
	AuthenticateClient(Authenticate) (*gocloak.JWT, error)
	AuthenticateUser(Authenticate) (*gocloak.JWT, error)
	RefreshToken(Refresh) (*gocloak.JWT, error)
}

// AuthenticationMiddleWare is used to validate the JWT
type AuthenticationMiddleWare interface {
	CheckToken(next echo.HandlerFunc) echo.HandlerFunc
    CheckTokenCustomHeader(next echo.HandlerFunc) echo.HandlerFunc
	CheckScope(next echo.HandlerFunc) echo.HandlerFunc
    DecodeAndValidateToken(next echo.HandlerFunc) echo.HandlerFunc
}

Compatibility Matrix

This middleware uses echo and gocloak. Choose the right version for you

Versions	Compatibility
gockloak-echo/v3	gocloak/v3, echo/v3
gockloak-echo/v4	gocloak/v3, echo/v4
gockloak-echo/v7	gocloak/v7, echo/v4
gockloak-echo/v8	gocloak/v8, echo/v4

License

Documentation

Index

• Constants
• func Contains(a []string, x string) bool
• type APICustomError
  • func (apiError APICustomError) Error() string
• type Authenticate
• type AuthenticationHandler
  • func NewAuthenticationHandler(ctx context.Context, gocloak gocloak.GoCloak, realm *string) AuthenticationHandler
• type AuthenticationMiddleWare
  • func NewDirectGrantMiddleware(ctx context.Context, gocloak gocloak.GoCloak, ...) AuthenticationMiddleWare
• type Authorization
• type Claims
  • func (c *Claims) HasPermission(resource string, scope string) bool
• type EnforcerConfig
• type EnforcerConfigPermission
• type JWT
• type Permission
  • func (pc Permission) Contains(id string, scope string) bool
• type PermissionClaim
• type Refresh
• type RequestModeEnum

Constants

const (
	// KeyRealm is used as realm key constant
	KeyRealm = "realm"
)

Functions

func Contains

func Contains(a []string, x string) bool

Contains tells whether a contains x.

Types

type APICustomError

type APICustomError struct {
	Code    int    `json:"code"`
	Message string `json:"message"`
	Result  string `json:"result"`
}

APIError holds message and statusCode for api errors

func (APICustomError) Error

func (apiError APICustomError) Error() string

Error stringifies the APIError

type Authenticate

type Authenticate struct {
	ClientID     string  `json:"clientID"`
	ClientSecret string  `json:"clientSecret"`
	Realm        string  `json:"realm,omitempty"`
	Scope        string  `json:"scope,omitempty"`
	UserName     *string `json:"username,omitempty"`
	Password     *string `json:"password,omitempty"`
}

Authenticate holds authentication information

type AuthenticationHandler

type AuthenticationHandler interface {
	AuthenticateClient(Authenticate) (*JWT, error)
	AuthenticateUser(Authenticate) (*JWT, error)
	RefreshToken(Refresh) (*JWT, error)
}

AuthenticationHandler is used to authenticate with the api

func NewAuthenticationHandler

func NewAuthenticationHandler(ctx context.Context, gocloak gocloak.GoCloak, realm *string) AuthenticationHandler

NewAuthenticationHandler instantiates a new AuthenticationHandler Setting realm is optional noinspection GoUnusedExportedFunction

type AuthenticationMiddleWare

type AuthenticationMiddleWare interface {
	// Decodes the token and checks if it is valid
	DecodeAndValidateToken(next echo.HandlerFunc) echo.HandlerFunc

	CheckToken(next echo.HandlerFunc) echo.HandlerFunc

	// The following 2 methods need higher permissions of the client in the realm
	CheckTokenCustomHeader(next echo.HandlerFunc) echo.HandlerFunc
	CheckScope(next echo.HandlerFunc) echo.HandlerFunc
	Protect(next echo.HandlerFunc) echo.HandlerFunc
	Enforcer(requestData *EnforcerConfig) echo.MiddlewareFunc
}

AuthenticationMiddleWare is used to validate the JWT

func NewDirectGrantMiddleware

func NewDirectGrantMiddleware(ctx context.Context, gocloak gocloak.GoCloak, realm, clientID, clientSecret, allowedScope string, customHeaderName *string) AuthenticationMiddleWare

NewDirectGrantMiddleware instantiates a new AuthenticationMiddleWare when using the Keycloak Direct Grant aka Resource Owner Password Credentials Flow

see https://www.keycloak.org/docs/latest/securing_apps/index.html#_resource_owner_password_credentials_flow and https://tools.ietf.org/html/rfc6749#section-4.3 for more information about this flow noinspection GoUnusedExportedFunction

type Authorization

type Authorization struct {
	Permissions []Permission `json:"permissions,omitempty"`
}

type Claims

type Claims struct {
	jwt.StandardClaims
	Typ               string             `json:"typ,omitempty"`
	Azp               string             `json:"azp,omitempty"`
	AuthTime          int                `json:"auth_time,omitempty"`
	SessionState      string             `json:"session_state,omitempty"`
	Acr               string             `json:"acr,omitempty"`
	AllowedOrigins    []string           `json:"allowed-origins,omitempty"`
	RealmAccess       jwx.RealmAccess    `json:"realm_access,omitempty"`
	ResourceAccess    jwx.ResourceAccess `json:"resource_access,omitempty"`
	Scope             string             `json:"scope,omitempty"`
	EmailVerified     bool               `json:"email_verified,omitempty"`
	Address           jwx.Address        `json:"address,omitempty"`
	Name              string             `json:"name,omitempty"`
	PreferredUsername string             `json:"preferred_username,omitempty"`
	GivenName         string             `json:"given_name,omitempty"`
	FamilyName        string             `json:"family_name,omitempty"`
	Email             string             `json:"email,omitempty"`
	ClientID          string             `json:"clientId,omitempty"`
	ClientHost        string             `json:"clientHost,omitempty"`
	ClientIP          string             `json:"clientAddress,omitempty"`
	Authorization     Authorization      `json:"authorization,omitempty"`
}

func (*Claims) HasPermission

func (c *Claims) HasPermission(resource string, scope string) bool

type EnforcerConfig

type EnforcerConfig struct {
	Audience     string
	Permissions  []EnforcerConfigPermission
	ResponseMode *RequestModeEnum
}

type EnforcerConfigPermission

type EnforcerConfigPermission struct {
	Resource string
	Scope    string
}

type JWT

type JWT struct {
	AccessToken      string `json:"accessToken"`
	ExpiresIn        int    `json:"expiresIn"`
	RefreshExpiresIn int    `json:"refreshExpiresIn"`
	RefreshToken     string `json:"refreshToken"`
	TokenType        string `json:"tokenType"`
	NotBeforePolicy  int    `json:"notBeforePolicy"`
	SessionState     string `json:"sessionState"`
	Scope            string `json:"scope"`
}

JWT is a JWT

type Permission

type Permission struct {
	Scopes []string `json:"scopes,omitempty"`
	Rsid   string   `json:"rsid,omitempty"`
	Rsname string   `json:"rsname,omitempty"`
}

func (Permission) Contains

func (pc Permission) Contains(id string, scope string) bool

type PermissionClaim

type PermissionClaim struct {
	Id string
	// contains filtered or unexported fields
}

type Refresh

type Refresh struct {
	ClientID     string `json:"clientID"`
	ClientSecret string `json:"clientSecret"`
	Realm        string `json:"realm,omitempty"`
	RefreshToken string `json:"refreshToken,omitempty"`
}

Refresh is used to refresh the JWT

type RequestModeEnum

type RequestModeEnum string

const (
	PermissionRequestMode RequestModeEnum = "permission"
	DecisionRequestMode   RequestModeEnum = "decision"
)