keycloak

keycloak is a Go client library for accessing the Keycloak API.

Installation

go get github.com/zemirco/keycloak

Usage

package main

import (
    "context"

    "github.com/zemirco/keycloak"
    "golang.org/x/oauth2"
)

func main() {
    // create your oauth configuration
    config := oauth2.Config{
        ClientID: "admin-cli",
        Endpoint: oauth2.Endpoint{
            TokenURL: "http://localhost:8080/auth/realms/master/protocol/openid-connect/token",
        },
    }

    // get a valid token from keycloak
    ctx := context.Background()
    token, err := config.PasswordCredentialsToken(ctx, "admin", "admin")
    if err != nil {
        panic(err)
    }

    // create a new http client that uses the token on every request
    client := config.Client(ctx, token)

    // create a new keycloak instance and provide the http client
    k, err := keycloak.NewKeycloak(client, "http://localhost:8080/auth/")
    if err != nil {
        panic(err)
    }

    // start using the library and, for example, create a new realm
    realm := &keycloak.Realm{
        Enabled: keycloak.Bool(true),
        ID:      keycloak.String("myrealm"),
        Realm:   keycloak.String("myrealm"),
    }

    res, err := k.Realms.Create(ctx, realm)
    if err != nil {
        panic(err)
    }
}

Examples

• full example: realm, client, users, resources, policies, permissions, evaluation
• ClientsService.Create: Create a new client
• GroupsService.Create: Create a new group
• NewKeycloak-Admin: Create an admin instance
• NewKeycloak-User: Create a user instance
• PoliciesService.CreateUserPolicy: Create a user policy
• RealmsService.Create: Create a new realm
• ResourcesService.Create: Create a new resource
• RolesService.Create: Create a new role
• ScopesService.Create: Create a new scope
• UsersService.Create: Create a new user

Development

Use docker-compose to start Keycloak locally.

docker-compose up -d

Keycloak is running at http://localhost:8080/. The admin credentials are admin (username) and admin (password). If you want to change them simply edit the docker-compose.yml.

Keycloak uses PostgreSQL and all data is kept across restarts.

Use down if you want to stop the Keycloak server.

docker-compose down

Architecture

The main entry point is keycloak.go. This is where the Keycloak instance is created. It all starts in this file.

Within Keycloak we also have the concept of clients. They are the ones that connect to Keycloak for authentication and authorization purposes, e.g. our frontend and backend apps. That is why this library simply uses the keycloak instance of type Keycloak and not a client instance like go-github. Although technically this library is a Keycloak client library for Go. However this distinction should make it clear what is meant when we talk about a client in our context.

Testing

You need to have Keycloak running on your local machine to execute the tests. Simply use docker-compose to start it.

All tests are independent from each other. Before each test we create a realm and after each test we delete it. You don't have to worry about it since the helper function createRealm does that automatically for you. Inside this realm you can do whatever you want. You don't have to clean up after yourself since everything is deleted automatically when the realm is deleted.

Run all tests.

go test -race -v ./...

Create code coverage.

go test -v ./... -coverprofile=coverage.out
go tool cover -html=coverage.out -o coverage.html

We have also provided a simple Makefile that run both jobs automatically.

make

Open coverage.html with your browser.

Design goals

1. Zero dependencies

   It's just the Go standard library.

   The only exception is go-querystring to easily handle query parameters.

2. Idiomatic Go

   Modelled after go-github and go-jira.

3. Keep authentication outside this library

   This is the major difference to most of the other Go Keycloak libraries.

   We leverage the brilliant oauth2 package to deal with authentication. We have provided multiple examples to show you the workflow. It basically means we do not provide any methods to call the /token endpoint.

4. Return struct and HTTP response

   Whenever the Keycloak API returns JSON content you'll get a proper struct as well as the HTTP response.

   func (s *ClientsService) Get(ctx context.Context, realm, id string) (*Client, *http.Response, error)

Related work

• https://github.com/Nerzal/gocloak
• https://github.com/PhilippHeuer/go-keycloak
• https://github.com/coreos/go-oidc
• https://github.com/keycloak/kcinit
• https://github.com/pulumi/pulumi-keycloak/tree/master/sdk/go/keycloak
• https://github.com/airmap/go-keycloak
• https://github.com/cloudtrust/keycloak-client
• https://github.com/myENA/go-keycloak
• https://github.com/threez/go-keycloak

License

MIT