keycloak

README

echo-keycloak

Keycloak authorization middleware for echo v4

The echo-keycloak middleware validates a token given by header, query & url param or cookie with a keycloak server token endpoint and adds the token to context as *jwt.Token (default key is "user").

The echo-keycloak-roles middleware validates given roles with keycloak client or user roles and adds all roles to context as []string (default key is "roles").

General

• echo-keycloak middleware must be executed before echo-keycloak-roles middleware
• Context key of echo-keycloak middleware and echo-keycloak-roles middleware must be equal
• Client and user roles are supported
• The client or user must have one of the given roles to get access. Use multiple instances of echo-keycloak-roles middleware if a route requires multiple roles
• Claim type in echo-keycloak middleware must be jwt.MapClaims (default) for echo-keycloak-roles middleware

Examples

Simple example

Documentation

Index

• Variables
• func Keycloak(url, realm string) echo.MiddlewareFunc
• func KeycloakRoles(roles []string) echo.MiddlewareFunc
• func KeycloakRolesWithConfig(config KeycloakRolesConfig) echo.MiddlewareFunc
• func KeycloakWithConfig(config KeycloakConfig) echo.MiddlewareFunc
• type KeycloakConfig
• type KeycloakErrorHandler
• type KeycloakErrorHandlerWithContext
• type KeycloakRolesConfig
• type KeycloakSuccessHandler

Variables

var (
	ErrClaimsMissing      = echo.NewHTTPError(http.StatusInternalServerError, "no claims in context found")
	ErrRealmAccessMissing = echo.NewHTTPError(http.StatusInternalServerError, "no realm_access in claims found")
	ErrRolesMissing       = echo.NewHTTPError(http.StatusInternalServerError, "no roles in realm_access claim found")
	ErrRolesInvalid       = echo.NewHTTPError(http.StatusForbidden, "invalid roles")
)

Errors

var (
	// DefaultKeycloakRolesConfig is the default KeycloakRoles auth middleware config.
	DefaultKeycloakConfig = KeycloakConfig{
		Skipper:     middleware.DefaultSkipper,
		ContextKey:  "user",
		TokenLookup: "header:" + echo.HeaderAuthorization,
		AuthScheme:  "Bearer",
		Claims:      jwt.MapClaims{},
	}
)

var (
	// DefaultKeycloakRolesConfig is the default KeycloakRoles roles middleware config.
	DefaultKeycloakRolesConfig = KeycloakRolesConfig{
		Skipper:         middleware.DefaultSkipper,
		TokenContextKey: "user",
		RolesContextKey: "roles",
	}
)

var (
	ErrTokenMissing = echo.NewHTTPError(http.StatusBadRequest, "missing or malformed token")
)

Errors

Functions

func Keycloak

func Keycloak(url, realm string) echo.MiddlewareFunc

KeycloakRoles returns a KeycloakRoles auth middleware.

For valid token, it sets the user in context and calls next handler. For invalid token, it returns "401 - Unauthorized" error. For missing token, it returns "400 - Bad Request" error.

See `KeycloakRolesConfig.TokenLookup`

func KeycloakRoles

func KeycloakRoles(roles []string) echo.MiddlewareFunc

KeycloakRoles returns a KeycloakRoles auth middleware.

For valid token, it sets the user in context and calls next handler. For invalid roles, it returns "403 - Forbidden" error. For missing token in context, it returns "500 - Internal Server Error" error.

func KeycloakRolesWithConfig

func KeycloakRolesWithConfig(config KeycloakRolesConfig) echo.MiddlewareFunc

KeycloakRolesWithConfig returns a KeycloakRoles auth middleware with config. See: `KeycloakRoles()`.

func KeycloakWithConfig

func KeycloakWithConfig(config KeycloakConfig) echo.MiddlewareFunc

KeycloakRolesWithConfig returns a KeycloakRoles auth middleware with config. See: `KeycloakRoles()`.

Types

type KeycloakConfig

type KeycloakConfig struct {
	// Skipper defines a function to skip middleware.
	Skipper middleware.Skipper

	// BeforeFunc defines a function which is executed just before the middleware.
	BeforeFunc middleware.BeforeFunc

	// SuccessHandler defines a function which is executed for a valid token.
	SuccessHandler KeycloakSuccessHandler

	// ErrorHandler defines a function which is executed for an invalid token.
	// It may be used to define a custom KeycloakRoles error.
	ErrorHandler KeycloakErrorHandler

	// ErrorHandlerWithContext is almost identical to ErrorHandler, but it's passed the current context.
	ErrorHandlerWithContext KeycloakErrorHandlerWithContext

	// KeycloakURL defines the URL of the KeycloakRoles server.
	KeycloakURL string

	// KeycloakRealm defines the realm of the KeycloakRoles server.
	KeycloakRealm string

	// Context key to store user information from the token into context.
	// Optional. Default value "user".
	ContextKey string

	// Claims are extendable claims data defining token content.
	// Optional. Default value jwt.MapClaims
	Claims jwt.Claims

	// TokenLookup is a string in the form of "<source>:<name>" that is used
	// to extract token from the request.
	// Optional. Default value "header:Authorization".
	// Possible values:
	// - "header:<name>"
	// - "query:<name>"
	// - "param:<name>"
	// - "cookie:<name>"
	TokenLookup string

	// AuthScheme to be used in the Authorization header.
	// Optional. Default value "Bearer".
	AuthScheme string
	// contains filtered or unexported fields
}

KeycloakRolesConfig defines the config for the KeycloakRoles middleware.

type KeycloakErrorHandler

type KeycloakErrorHandler func(error) error

KeycloakErrorHandler defines a function which is executed for an invalid token.

type KeycloakErrorHandlerWithContext

type KeycloakErrorHandlerWithContext func(error, echo.Context) error

KeycloakErrorHandlerWithContext is almost identical to KeycloakErrorHandler, but it's passed the current context.

type KeycloakRolesConfig

type KeycloakRolesConfig struct {
	// Skipper defines a function to skip middleware.
	Skipper middleware.Skipper

	// BeforeFunc defines a function which is executed just before the middleware.
	BeforeFunc middleware.BeforeFunc

	// SuccessHandler defines a function which is executed for a valid token.
	SuccessHandler KeycloakSuccessHandler

	// ErrorHandler defines a function which is executed for an invalid token.
	// It may be used to define a custom KeycloakRoles error.
	ErrorHandler KeycloakErrorHandler

	// ErrorHandlerWithContext is almost identical to ErrorHandler, but it's passed the current context.
	ErrorHandlerWithContext KeycloakErrorHandlerWithContext

	// KeycloakRoles defines the KeycloakRoles roles having access.
	KeycloakRoles []string

	// TokenContextKey is the context key which stores the keycloak jwt token
	// Optional. Default value "user".
	TokenContextKey string

	// RolesContextKey is the context key which stores the roles as []string
	// Optional. Default value "roles".
	RolesContextKey string
}

KeycloakRolesConfig defines the config for the KeycloakRoles roles middleware.

type KeycloakSuccessHandler

type KeycloakSuccessHandler func(echo.Context)

KeycloakSuccessHandler defines a function which is executed for a valid token.