[ bsd3, library, program, unclassified ] [ Propose Tags ]

Please see the README on GitHub at

[Skip to Readme]
Versions [faq],,,,,,, 0.1.1, 0.2.0, 1.0.0, 1.0.1, 1.1.0, 1.1.1, 2.0.0, 2.0.1, 2.0.2, 2.0.3, 2.1.0
Change log
Dependencies aeson (>=1.4 && <1.6), aeson-casing (>=0.1 && <0.3), base (>= && <5), base64-bytestring (>=1.0 && <1.2), bytestring (==0.10.*), containers (==0.6.*), exceptions (==0.10.*), hashable (>=1.1 && <1.4), hslogger (>=1.2 && <1.4), http-api-data (==0.4.*), http-client (>=0.5 && <0.7), http-types (==0.12.*), jose (==0.8.*), keycloak-hs, lens (>=4.17 && <4.20), lens-aeson (==1.1.*), mtl (==2.2.*), safe (==0.3.*), string-conversions (==0.4.*), text (==1.2.*), unordered-containers (==0.2.*), word8 (==0.1.*), wreq (==0.5.*) [details]
License BSD-3-Clause
Copyright 2019 Corentin Dupont
Author Corentin Dupont
Home page
Bug tracker
Source repo head: git clone
Uploaded by CorentinDupont at 2020-10-29T15:59:57Z
Distributions NixOS:1.1.1
Executables example
Downloads 4362 total (653 in the last 30 days)
Rating (no votes yet) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Hackage Matrix CI
Docs available [build log]
Last success reported on 2020-10-29 [all 1 reports]


[Index] [Quick Jump]


Maintainer's Corner

For package maintainers and hackage trustees

Readme for keycloak-hs-2.1.0

[back to package description]


Keycloak-hs is an Haskell library for connecting to Keycloak. Keycloak allows to authenticate and manage users and to protect API resources. This library allows you to retrieve and analyse Keycloak authentication tokens, and to protect resources in your API.


Installation follows the standard approach to installing Stack-based projects.

  1. Install the Haskell stack tool.
  2. Run stack install --fast to install this package.


In this tutorial, we'll configure Keycloak for running our small example. First you should install and run Keycloak: follow this tutorial.

The example is compiled and run this way:

$ stack install
$ example

But before running it, we should create a Client in Keycloak and retrieve the adapter config file. In Keycloak admin panel, create the following:

  • a realm named "demo"
  • a client named "demo".

This file is now downloadable in your Client/Installation tab (JSON format). Place it in this folder.


Authentication with Keycloak is based on JWTs.

In Keycloak, create a user named "demo" with password "demo". Make sure that your user is enable, email verified, and the password is not temporary. At this point, you should be able to retrieve tokens from Keycloak, verify them using this library, and extract a User from the tokens.

Additionaly, you can add attributes to your user. In Keycloak UI, go in the User Attributes tab and add an attribute, such as "phone". In order for this attribute to appear in the token claims, we should also add a client "mapper". In the client "demo", click on "Mappers"/"add mappers". Fill the name="phone", Mapper Type=User attribute, Token Claim Name="phone", Claim JSON Type=String, and save.


Keycloak can also manage your resources and related access policies. The idea is that, each time a user makes a request on your application, you will ask Keycloak "Can he really do that??".

In the client "demo":

  • change "Access Type" to confidential
  • turn "Authorization Enabled" ON.

A new "Authorization" tab should appear.

Let's set up some authorization policies in order to demonstrate the capacity of Keycloak-hs. We want to authorize our user "demo" to "view" any resource. First go in the new "Authorization" tab that appeared. Flip ON "Remote Resource Management".

Create a new Scope in the "Authorization Scopes" tab:

  • Name it "view".

Create a new "User" policy in the "Policies" tab with the following settings:

  • Name it "Demo user have access".
  • Select user "demo" in the drop box.
  • Logic should be positive.

Create a new scope-based permission in the "Permissions" tab:

  • Name it "View resources".
  • Select "view" in Scopes.
  • Select your previous policy "Demo user have access" in "Apply Policy".

That's it for the confguration of Keycloak. You are now able to play with the "Authorization" part of the example. Keycloak is very complex, so you'll have fun exploring all the possibilities ;)