ginkeycloak

README

Gin-Keycloak

Gin-Keycloak is specially made for Gin Framework users who also want to use Keycoak. This Project was inspired by zalando's gin-oauth

Project Context and Features

When it comes to choosing a Go framework, there's a lot of confusion about what to use. The scene is very fragmented, and detailed comparisons of different frameworks are still somewhat rare. Meantime, how to handle dependencies and structure projects are big topics in the Go community. We've liked using Gin for its speed, accessibility, and usefulness in developing microservice architectures. In creating Gin-OAuth2, we wanted to take fuller advantage of Gin's capabilities and help other devs do likewise.

Gin-Keycloak is expressive, flexible, and very easy to use. It allows you to:

• do OAuth2 authorization based on the JWT Token
• create router groups to place Keycloak authorization on top, using HTTP verbs and passing them
• more easily decouple services by promoting a "say what to do, not how to do it" approach
• configure your REST API directly in the code (see the "Usage" example below)
• write your own authorization functions

Requirements

• Gin
• An Keycloak Token provider

Gin-Keycloak uses the following Go packages as dependencies:

• Gin
• glog
• gin-glog

Installation

Assuming you've installed Go and Gin, run this:

go get github.com/tbaehler/gin-keycloak

Usage

Authentication-Based Access

With this function you just check if user is authenticated. Therefore there is no need for AccessTuple unlike next two access types.

Gin middlewares you use:

router := gin.New()
router.Use(ginglog.Logger(3 * time.Second))
router.Use(ginkeycloak.RequestLogger([]string{"uid"}, "data"))
router.Use(gin.Recovery())

A Keycloakconfig. You can either use URL and Realm or define a fullpath that point to protocol/openid-connect/certs

var sbbEndpoint = ginkeycloak.KeycloakConfig{
    Url:  "https://keycloack.domain.ch/",
    Realm: "Your Realm",
    FullCertsPath: nil
}

Lastly, define which type of access you grant to the defined team. We'll use a router group again:

privateGroup := router.Group("/api/privateGroup")
privateGroup.Use(ginkeycloak.Auth(ginkeycloak.AuthCheck(), keycloakconfig))
privateGroup.GET("/", func(c *gin.Context) {
	....
})

Once again, you can use curl to test:

    curl -H "Authorization: Bearer $TOKEN" http://localhost:8081/api/privateGroup/
    {"message":"Hello from private to sszuecs member of teapot"}

Uid-Based Access

Restrict all access but for a few users

config := ginkeycloak.BuilderConfig{
          		service:              <yourServicename>,
          		url:                  "<your token url>",
          		realm:                "<your realm to get the public keys>",
          }

router := gin.New()
privateUser := router.Group("/api/privateUser")

privateUser.Use(ginkeycloak.NewAccessBuilder(config).
    RestrictButForUid("domain\user1").
    RestrictButForUid("domain\user2").
    Build())

privateUser.GET("/", func(c *gin.Context) {
	....
})

Testing

To test, you can use curl:

    curl -H "Authorization: Bearer $TOKEN" http://localhost:8081/api/privateUser/
    {"message":"Hello from private for users to Sandor Szücs"}

Role-Based Access

Restrict all access but for the given roles

config := ginkeycloak.BuilderConfig{
              		service:              <yourServicename>,
              		url:                  "<your token url>",
              		realm:                "<your realm to get the public keys>",
              }

router := gin.New()
privateUser := router.Group("/api/privateUser")

privateUser.Use(ginkeycloak.NewAccessBuilder(config).
    RestrictButForRole("role1").
    RestrictButForRole("role2").
    Build())

privateUser.GET("/", func(c *gin.Context) {
	....
})

Once again, you can use curl to test:

curl -H "Authorization: Bearer $TOKEN" http://localhost:8081/api/privateGroup/
    {"message":"Hello from private to sszuecs member of teapot"}

Realm-Based Access

Realm Based Access is also possible and straightforward:

config := ginkeycloak.BuilderConfig{
                  		service:              <yourServicename>,
                  		url:                  "<your token url>",
                  		realm:                "<your realm to get the public keys>",
                  }

router := gin.New()
privateUser := router.Group("/api/privateUser")

privateUser.Use(ginkeycloak.NewAccessBuilder(config).
    RestrictButForRealm("realmRole").
    Build())

privateUser.GET("/", func(c *gin.Context) {
	....
})

Custom Claims Mapper

It is possible to configure a custom claims mapper to add to the KeyCloakToken custom claims that are not standard for KeyCloak tokens. The custom claims can be added to the provided field CustomClaims.

Here a simple example:

type MyCustomClaims struct {
    Tenant string `json:"https://your-realm/tenant,omitempty"`
}

func MyCustomClaimsMapper(jsonWebToken *jwt.JSONWebToken, keyCloakToken *ginkeycloak.KeyCloakToken) error {
    claims := MyCustomClaims{}
    jsonWebToken.UnsafeClaimsWithoutVerification(&claims)
    keyCloakToken.CustomClaims = claims
    return nil
}

var keycloakconfig = ginkeycloak.KeycloakConfig{
    Url:                "https://keycloack.domain.ch/"
    Realm:              "your-realm",
    FullCertsPath:      nil,
    CustomClaimsMapper: MyCustomClaimsMapper,
}

FAQ

Which Token Signature Algorithms are currently supported?

Currently, are only "EC" (which uses keycloak by default) and "RS" supported

How to get the keycloak claims e.g. sub, mail, name?

    ginToken,_ := context.Get("token")
    token := ginToken.(ginkeycloak.KeyCloakToken)

Contributors

Thanks to:

• Zalando Team for their initial work

License

See MIT-License LICENSE file.

Documentation

Index

• Variables
• func Auth(accessCheckFunction AccessCheckFunction, endpoints KeycloakConfig) gin.HandlerFunc
• func AuthCheck() func(tc *TokenContainer, ctx *gin.Context) bool
• func GroupCheck(at []AccessTuple) func(tc *TokenContainer, ctx *gin.Context) bool
• func RealmCheck(allowedRoles []string) func(tc *TokenContainer, ctx *gin.Context) bool
• func RequestLogger(keys []string, contentKey string) gin.HandlerFunc
• func UidCheck(at []AccessTuple) func(tc *TokenContainer, ctx *gin.Context) bool
• type AccessCheckFunction
• type AccessTuple
• type BuilderConfig
• type Certs
• type ClaimMapperFunc
• type KeyCloakToken
• type KeyEntry
• type KeycloakConfig
• type RestrictedAccessBuilder
  • func NewAccessBuilder(config BuilderConfig) RestrictedAccessBuilder
• type ServiceRole
• type TokenContainer
  • func GetTokenContainer(token *oauth2.Token, config KeycloakConfig) (*TokenContainer, error)
  • func (t *TokenContainer) Valid() bool

Variables

var VarianceTimer = 30000 * time.Millisecond

VarianceTimer controls the max runtime of Auth() and AuthChain() middleware

Functions

func Auth

func Auth(accessCheckFunction AccessCheckFunction, endpoints KeycloakConfig) gin.HandlerFunc

func AuthCheck

func AuthCheck() func(tc *TokenContainer, ctx *gin.Context) bool

func GroupCheck

func GroupCheck(at []AccessTuple) func(tc *TokenContainer, ctx *gin.Context) bool

func RealmCheck

func RealmCheck(allowedRoles []string) func(tc *TokenContainer, ctx *gin.Context) bool

func RequestLogger

func RequestLogger(keys []string, contentKey string) gin.HandlerFunc

func UidCheck

func UidCheck(at []AccessTuple) func(tc *TokenContainer, ctx *gin.Context) bool

Types

type AccessCheckFunction

type AccessCheckFunction func(tc *TokenContainer, ctx *gin.Context) bool

type AccessTuple

type AccessTuple struct {
	Service string
	Role    string
	Uid     string
}

type BuilderConfig

type BuilderConfig struct {
	Service              string
	Url                  string
	Realm                string
	FullCertsPath        *string
	DisableSecurityCheck bool
}

type Certs

type Certs struct {
	Keys []KeyEntry `json:"keys"`
}

type ClaimMapperFunc

type ClaimMapperFunc func(jsonWebToken *jwt.JSONWebToken, keyCloakToken *KeyCloakToken) error

type KeyCloakToken

type KeyCloakToken struct {
	Jti               string                 `json:"jti,omitempty"`
	Exp               int64                  `json:"exp"`
	Nbf               int64                  `json:"nbf"`
	Iat               int64                  `json:"iat"`
	Iss               string                 `json:"iss"`
	Sub               string                 `json:"sub"`
	Typ               string                 `json:"typ"`
	Azp               string                 `json:"azp,omitempty"`
	Nonce             string                 `json:"nonce,omitempty"`
	AuthTime          int64                  `json:"auth_time,omitempty"`
	SessionState      string                 `json:"session_state,omitempty"`
	Acr               string                 `json:"acr,omitempty"`
	ClientSession     string                 `json:"client_session,omitempty"`
	AllowedOrigins    []string               `json:"allowed-origins,omitempty"`
	ResourceAccess    map[string]ServiceRole `json:"resource_access,omitempty"`
	Name              string                 `json:"name"`
	PreferredUsername string                 `json:"preferred_username"`
	GivenName         string                 `json:"given_name,omitempty"`
	FamilyName        string                 `json:"family_name,omitempty"`
	Email             string                 `json:"email,omitempty"`
	RealmAccess       ServiceRole            `json:"realm_access,omitempty"`
	CustomClaims      interface{}            `json:"custom_claims,omitempty"`
}

type KeyEntry

type KeyEntry struct {
	Kid string   `json:"kid"`
	Kty string   `json:"kty"`
	Alg string   `json:"alg"`
	Use string   `json:"use"`
	Crv string   `json:"crv"`
	X   string   `json:"x"`
	Y   string   `json:"y"`
	N   string   `json:"n"`
	E   string   `json:"e"`
	X5C []string `json:"x5c"`
}

type KeycloakConfig

type KeycloakConfig struct {
	Url                string
	Realm              string
	FullCertsPath      *string
	CustomClaimsMapper ClaimMapperFunc
}

type RestrictedAccessBuilder

type RestrictedAccessBuilder interface {
	RestrictButForRole(role string) RestrictedAccessBuilder
	RestrictButForUid(uid string) RestrictedAccessBuilder
	RestrictButForRealm(realmName string) RestrictedAccessBuilder
	Build() gin.HandlerFunc
}

func NewAccessBuilder

func NewAccessBuilder(config BuilderConfig) RestrictedAccessBuilder

type ServiceRole

type ServiceRole struct {
	Roles []string `json:"roles"`
}

type TokenContainer

type TokenContainer struct {
	Token         *oauth2.Token
	KeyCloakToken *KeyCloakToken
}

TokenContainer stores all relevant token information

func GetTokenContainer

func GetTokenContainer(token *oauth2.Token, config KeycloakConfig) (*TokenContainer, error)

func (*TokenContainer) Valid

func (t *TokenContainer) Valid() bool