Keycloak adaptor for golang application

Question

I am going to secure my golang application using keycloak, but keycloak itself does not support go language.

There are some go adaptor as an open project in github that has implemented openId connect protocol as a provider service, but they do not provide an example or documentation on how to integrate libraries with an application.

How can i interact with keycloak using golang?

Solution 1

As you have pointed out, there is no official keycloak adapter for golang. But it is pretty straight forward to implement it. Here is a little walk through.

Keycloak server

For this example, I will use the official keycloak docker image to start the server. The version used is 4.1.0.Final. I think this will work with older KeyCloak versions too though.

docker run -d -p 8080:8080 -e KEYCLOAK_USER=keycloak -e KEYCLOAK_PASSWORD=k --name keycloak jboss/keycloak:4.1.0.Final

After the server is up and running, you can open localhost:8080/auth in your browser, navigate to the administration console and login with username keycloak and k as the corresponding password.

I will not go through the complete process of creating a realm/clients/users. You can look this up under https://www.keycloak.org/docs/latest/server_admin/index.html#admin-console

Here is just an outline for what I did to reproduce this example:

1. create a realm named demo
2. turn off the requirement of ssl for this realm (realmsettings -> login -> require ssl)
3. create a client named demo-client (change the "Access Type" to confidential)
4. create a user named demo with password demo (users -> add user). Make sure to activate and impersonate this user.
5. configure the demo-client to be confidential and use http://localhost:8181/demo/callback as a valid redirect URI.

The resulting keycloak.json (obtained from the installation tab) looks like this:

{
    "realm": "demo",
    "auth-server-url": "http://localhost:8080/auth",
    "ssl-required": "none",
    "resource": "demo-client",
    "credentials": {
        "secret": "cbfd6e04-a51c-4982-a25b-7aaba4f30c81"
    },
    "confidential-port": 0
}

Beware that your secret will be different though.

The Go Server

Let's go over to the go server. I use the github.com/coreos/go-oidc package for the heavy lifting:

package main

import (
    "context"
    "encoding/json"
    "log"
    "net/http"
    "strings"

    oidc "github.com/coreos/go-oidc"
    "golang.org/x/oauth2"
)

func main() {
    configURL := "http://localhost:8080/auth/realms/demo"
    ctx := context.Background()
    provider, err := oidc.NewProvider(ctx, configURL)
    if err != nil {
        panic(err)
    }

    clientID := "demo-client"
    clientSecret := "cbfd6e04-a51c-4982-a25b-7aaba4f30c81"

    redirectURL := "http://localhost:8181/demo/callback"
    // Configure an OpenID Connect aware OAuth2 client.
    oauth2Config := oauth2.Config{
        ClientID:     clientID,
        ClientSecret: clientSecret,
        RedirectURL:  redirectURL,
        // Discovery returns the OAuth2 endpoints.
        Endpoint: provider.Endpoint(),
        // "openid" is a required scope for OpenID Connect flows.
        Scopes: []string{oidc.ScopeOpenID, "profile", "email"},
    }
    state := "somestate"

    oidcConfig := &oidc.Config{
        ClientID: clientID,
    }
    verifier := provider.Verifier(oidcConfig)

    http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
        rawAccessToken := r.Header.Get("Authorization")
        if rawAccessToken == "" {
            http.Redirect(w, r, oauth2Config.AuthCodeURL(state), http.StatusFound)
            return
        }

        parts := strings.Split(rawAccessToken, " ")
        if len(parts) != 2 {
            w.WriteHeader(400)
            return
        }
        _, err := verifier.Verify(ctx, parts[1])

        if err != nil {
            http.Redirect(w, r, oauth2Config.AuthCodeURL(state), http.StatusFound)
            return
        }

        w.Write([]byte("hello world"))
    })

    http.HandleFunc("/demo/callback", func(w http.ResponseWriter, r *http.Request) {
        if r.URL.Query().Get("state") != state {
            http.Error(w, "state did not match", http.StatusBadRequest)
            return
        }

        oauth2Token, err := oauth2Config.Exchange(ctx, r.URL.Query().Get("code"))
        if err != nil {
            http.Error(w, "Failed to exchange token: "+err.Error(), http.StatusInternalServerError)
            return
        }
        rawIDToken, ok := oauth2Token.Extra("id_token").(string)
        if !ok {
            http.Error(w, "No id_token field in oauth2 token.", http.StatusInternalServerError)
            return
        }
        idToken, err := verifier.Verify(ctx, rawIDToken)
        if err != nil {
            http.Error(w, "Failed to verify ID Token: "+err.Error(), http.StatusInternalServerError)
            return
        }

        resp := struct {
            OAuth2Token   *oauth2.Token
            IDTokenClaims *json.RawMessage // ID Token payload is just JSON.
        }{oauth2Token, new(json.RawMessage)}

        if err := idToken.Claims(&resp.IDTokenClaims); err != nil {
            http.Error(w, err.Error(), http.StatusInternalServerError)
            return
        }
        data, err := json.MarshalIndent(resp, "", "    ")
        if err != nil {
            http.Error(w, err.Error(), http.StatusInternalServerError)
            return
        }
        w.Write(data)
    })

    log.Fatal(http.ListenAndServe("localhost:8181", nil))
}

This program starts a regular http server with two endpoints. The first one ("/") is your regular endpoint that handles application logic. In this case, it only returns "hello world" to your client.

The second endpoint ("/demo/callback") is used as a callback for keycloak. This endpoint needs to be registered on your keycloak server. Keycloak will issue a redirect to this callback URL upon successful user authentication. The redirect contains some additional query parameters. These parameters contain a code that can be used to obtain access/id tokens.

Verify your setup

In order to test this setup you can open a webbrowser and navitage to http://localhost:8181. The request should reach your go server, which tries to authenticate you. Since you did not send a token, the go server will redirecty you to keycloak to authenticate. You should see the login screen of keycloak. Login with the demo user you have created for this realm (demo/demo). If you have configured your keycloak correctly, it will authenticate you and redirect you to your go server callback.

The end result should be a json like this

{
    "OAuth2Token": {
        "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJsc1hHR2VxSmx3UUZweWVYR0x6b2plZXBYSEhXUngtTHVJTVVLdDBmNmlnIn0.eyJqdGkiOiI5ZjAxNjM2OC1lYmEwLTRiZjMtYTU5Ni1kOGU1MzdmNTNlZGYiLCJleHAiOjE1MzIxNzM2NTIsIm5iZiI6MCwiaWF0IjoxNTMyMTczMzUyLCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvZGVtbyIsImF1ZCI6ImRlbW8tY2xpZW50Iiwic3ViIjoiMzgzMzhjOGItYWQ3Zi00NjlmLTgzOTgtMTc5ODk1ODFiYTEyIiwidHlwIjoiQmVhcmVyIiwiYXpwIjoiZGVtby1jbGllbnQiLCJhdXRoX3RpbWUiOjE1MzIxNzMzNTIsInNlc3Npb25fc3RhdGUiOiJjZTg2NWFkZC02N2I4LTQ5MDUtOGYwMy05YzE2MDNjMWJhMGQiLCJhY3IiOiIxIiwiYWxsb3dlZC1vcmlnaW5zIjpbXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm9mZmxpbmVfYWNjZXNzIiwidW1hX2F1dGhvcml6YXRpb24iXX0sInJlc291cmNlX2FjY2VzcyI6eyJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50IiwibWFuYWdlLWFjY291bnQtbGlua3MiLCJ2aWV3LXByb2ZpbGUiXX19LCJzY29wZSI6Im9wZW5pZCBwcm9maWxlIGVtYWlsIiwiZW1haWxfdmVyaWZpZWQiOnRydWUsInByZWZlcnJlZF91c2VybmFtZSI6ImRlbW8iLCJlbWFpbCI6ImRlbW9AZGVtby5jb20ifQ.KERz8rBddxM9Qho3kgigX-fClWqbKY-3JcWT3JOQDoLa-prkorfa40BWlyf9ULVgjzT2d8FLJpqQIQYvucKU7Q7vFBVIjTGucUZaE7b6JGMea5H34A1i-MNm7L2CzDJ2GnBONhNwLKoftTSl0prbzwkzcVrps-JAZ6L2gssSa5hBBGJYBKAUfm1OIb57Jq0vzro3vLghZ4Ay7iNunwfcHUrxiFJfUjaU6PQwzrA5pnItOPuavJFUgso7-3JLtn3X9GQuyyZKrkDo6-gzU0JZmkQQzAXXgt43NxooryImuacwSB5xbIKY6qFkedldoOPehld1-oLv0Yy_FIwEad3uLw",
        "token_type": "bearer",
        "refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJsc1hHR2VxSmx3UUZweWVYR0x6b2plZXBYSEhXUngtTHVJTVVLdDBmNmlnIn0.eyJqdGkiOiI0MjdmMTlhYy1jMTkzLTQ2YmQtYWFhNi0wY2Q1OTI5NmEwMGQiLCJleHAiOjE1MzIxNzUxNTIsIm5iZiI6MCwiaWF0IjoxNTMyMTczMzUyLCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvZGVtbyIsImF1ZCI6ImRlbW8tY2xpZW50Iiwic3ViIjoiMzgzMzhjOGItYWQ3Zi00NjlmLTgzOTgtMTc5ODk1ODFiYTEyIiwidHlwIjoiUmVmcmVzaCIsImF6cCI6ImRlbW8tY2xpZW50IiwiYXV0aF90aW1lIjowLCJzZXNzaW9uX3N0YXRlIjoiY2U4NjVhZGQtNjdiOC00OTA1LThmMDMtOWMxNjAzYzFiYTBkIiwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm9mZmxpbmVfYWNjZXNzIiwidW1hX2F1dGhvcml6YXRpb24iXX0sInJlc291cmNlX2FjY2VzcyI6eyJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50IiwibWFuYWdlLWFjY291bnQtbGlua3MiLCJ2aWV3LXByb2ZpbGUiXX19LCJzY29wZSI6Im9wZW5pZCBwcm9maWxlIGVtYWlsIn0.FvvDW6ZSH8mlRR2zgaN1zesX14SmkCs9RrIVU4Jn1-SHVdKEA6YKur0-RUAFTObQDMLVhFFJ05AjGVGWpBrgVDcAwW2pI9saM-OHlyTJ3VfFoylgfzakVOIpbIDnHO12UaJrkOI9NWPAJdbBOzBHfsDhKbxhjg4ZX8SwlKr42rV4WWuSRcNu4_YDVO19SiXSCKXVldZ1_2S-qPvViq7VZfaoRLHuYyDvma_ByMsmib9JUkevJ8dxsYxVQ5FWaAfFanh1a1f8HxNRI-Cl180oPn1_Tqq_SYwxzBCw7Q_ENkMirwRS1a4cX9yMVEDW2uvKz2D-OiNAUK8d_ONuPEkTGQ",
        "expiry": "2018-07-21T13:47:28.986686385+02:00"
    },
    "IDTokenClaims": {
        "jti": "f4d56526-37d9-4d32-b99d-81090e92d3a7",
        "exp": 1532173652,
        "nbf": 0,
        "iat": 1532173352,
        "iss": "http://localhost:8080/auth/realms/demo",
        "aud": "demo-client",
        "sub": "38338c8b-ad7f-469f-8398-17989581ba12",
        "typ": "ID",
        "azp": "demo-client",
        "auth_time": 1532173352,
        "session_state": "ce865add-67b8-4905-8f03-9c1603c1ba0d",
        "acr": "1",
        "email_verified": true,
        "preferred_username": "demo",
        "email": "[email protected]"
    }
}

You can copy your access token and use curl to verify if the server is able to accept your tokens:

# use your complete access token here
export TOKEN="eyJhbG..."
curl -H "Authorization: Bearer $TOKEN" localhost:8181
# output hello world

You can try it again after the token has expired - or temper with the token. In case you do it, you should get a redirect to your keycloak server again.

Solution 2

There is also the gocloak library which provides lot's of functionality. The lib is in active development and allready in use in real world projects. So possible bugs & feature requests are being handled.

It provides administration features like "CreateUser","CreateGroup" etc. and also provides functions for Login, Token validation, etc.

For example creating a user is as easy as:

client := gocloak.NewClient("https://mycool.keycloak.instance")
token, err := client.LoginAdmin("user", "password", "realmName")
if err != nil {
    panic("Something wrong with the credentials or url")
}
user := gocloak.User{
    FirstName: "Bob",
    LastName:  "Uncle",
    EMail:     "[email protected]",
    Enabled:   true,
    Username:  "CoolGuy",
}
client.CreateUser(token.AccessToken, "realm", user)
if err != nil {
    panic("Oh no!, failed to create user :(")
}

It does also supports Introspecting a Requesting Party Token

client := gocloak.NewClient(hostname)
token, err := client.LoginClient(clientid, clientSecret, realm)
if err != nil {
    panic("Login failed:"+ err.Error())
}

rptResult, err := client.RetrospectToken(token.AccessToken, clientid, clientSecret, realm)
if err != nil {
    panic("Inspection failed:"+ err.Error())
}

if !rptResult.Active {
    panic("Token is not active")
}

permissions := rptResult.Permissions
//Do something with the permissions ;) 

Also to handle easy authentication & token refresh when using echo there is another lib based on gocloak called gocloak-echo. This lib provides handler & middleware to help out, but is still in a more WIP state.

The library also provides decoding of accessTokens into custom claims

Disclosure: I am the (main) author of gocloak, so it's also a little advertising, but in general it answers the question. I had the same problem as the author and i decided to create my own lib (based on the lib of someone else, as stated in the readme on github).

Comments

[Jan Garaj]

It seems to me that it's a question for project maintainers - how to use their projects. IMHO top project is github.com/gambol99/keycloak-proxy - it's not an adaptor, but it's an auth proxy. It's not keycloak only, but it's OIDC auth proxy (GitHub, Google, ...).

[ShrimpPhaser]

gocloak looks really nice. Thanks for pointing it out! One little nitpick though: You should add a short disclosure that you are the author.

[Tobias Theel]

Thanks for the hint! I added a disclosure

[Ramon Rambo]

Thank you for your example, it helped me a lot! Maybe it is a bit misleading, because there are a lot of different tokens being used, but I struggled with the last step. I think the TOKEN variable should be filled with the value of the rawIDToken string, not with the access_token from the oauth2token. When I use the rawIDToken it does work, with the access_token it did not.

[3ps]

Token verification fails with expected audience "demo-client" got ["account"] with latest keycloak. Client Scopes need to be adjusted like explained in stackoverflow.com/a/53627747