Monday, 6 February 2017

Removing Mongo support from Keycloak

At times you have to make hard decisions and this has been one of those. We have decided to remove Mongo support from Keycloak. The primary motivation behind this decision is that we simply don't have the resources to maintain and further develop the back-end for both relational databases and Mongo. Further, there are some fundamental issues with our current use of Mongo that would require a large amount of work to become fully production ready. This primarily boils down to the lack of ACID transactions in Mongo.

We hope that this decision won't result in too much trouble for those of you that are currently using Mongo as the back-end for Keycloak. It should be relatively painless to migrate to a relational database with our export/import feature. If you do run into issues with this please let us know on the mailing list and we will do whatever we can to help make the transition as smooth as possible.

If anyone from the community would like to take over the Mongo support and maintain it as a separate extension please let us know. We can help with extracting the code and work together in making it easy to install it as an extension.

Migrating from Mongo to relational database

First step is to export the full database. You can do this by stopping the Keycloak server and running:

bin/ -Dkeycloak.migration.action=export -Dkeycloak.migration.provider=dir -Dkeycloak.migration.dir=backup

This will export all data from Mongo to JSON files within the directory backup. For full details refer to the Server Administration Guide.

Next step is to install a relational database and configure it in Keycloak. Take your pick we support quite a few. For full details refer to the Server Installation Guide.

Once you have the relational database ready and configured, you can start Keycloak and import the data exported from Mongo. To do this run Keycloak with:

bin/ -Dkeycloak.migration.action=import -Dkeycloak.migration.provider=dir -Dkeycloak.migration.dir=backup

Hopefully you're now up and running with all your realms and users migrated to the relational database. If not, let us know on the user mailing list and we'll help you out as soon as possible.

Thursday, 26 January 2017

Administer Keycloak server from shell with Admin CLI

A few months ago we introduced Client Registration CLI - a tool for registering new clients with Keycloak server in a self-service manner.

With release 2.5.0 we now also have Admin CLI - a general purpose administration tool that an admin can use to perform a full set of actions over Admin REST API without having to use a web based Admin Console.

This tool should come especially handy in combination with shell scripts or tools like Ansible or Docker, where before one would have to resort to using curl or wget in a much more cumbersome way.

You can find Admin CLI execution scripts in KEYCLOAK/bin directory - there's for Bash, and kcadm.bat for Windows CMD.

Running the tool without any parameters will greet you with some help to get you started.


Typical usage begins with authentication step where user or client credentials are provided.

$ config credentials --server http://localhost:8080/auth --realm master --user admin --password admin

Session is maintained by saving an access token into a configuration file - by default it is at ~/.keycloak/kcadm.config.

You can also pass authentication parameters to any other commands together with --no-config option, which will skip using a config file altogether - authentication, access token retrieval, and operation invocation will all be part of a single command execution after which the token will simply be forgotten.

Assuming we've authenticated using a configuration file we can then perform operations against Admin REST endpoints. For example, you may want to create a new realm with roles, clients, some users, then reset a user's password, and set up events logging.

Create a new realm

$ create realms -s realm=demo -s enabled=true

Create new realm roles

$ create roles -r demo -s name=admin
$ create roles -r demo -s name=user

Create a new public client

$ create clients -r demo -s clientId=myapp -s publicClient=true -s 'redirectUris["http://localhost:8980/myapp/*"]' -o

Create a new user

$ SUPER_ID=` create users -r demo -s username=super -i`

Add client role to a user

$ add-roles -r demo --uusername super --cclientid realm-management --rolename realm-admin

Add realm roles to a user

$ add-roles -r demo --uusername super --rolename admin --rolename user

Update a user

$ update users/$SUPER_ID -r demo -s enabled=true

Change user's password

$ set-password -r demo --username super --password password

We can now login as a newly created user so we don't have to continually specify the target realm:

$ config credentials --server http://localhost:8080/auth --realm demo --user super --password password

Get existing users

$ get users --limit 20

Get existing clients

$ get clients --fields id,clientId,publicClient,redirectUris

Setup login events logging

$ update events/config -s eventsEnabled=true

Get last twenty login events

$ get events --offset 0 --limit 100

As you may have guessed by now Admin CLI is pretty generic. You specify a command followed by a target endpoint URI which will be resolved relative to Admin REST API root, and current realm as specified with --realm option during authentication. It also takes target realm override into account which you specify with -r option. This way any Admin REST API endpoint can be reached. Content to send is specified by using -s option - specified attributes become part of a JSON document sent to a target URI.

You can find a more comprehensive list of recipes for specific tasks in Admin CLI chapter of a Server Administration Guide.

Give Admin CLI a try, and let us know how it works for you.

Keycloak 2.5.1.Final Released

We've just released Keycloak 2.5.1.Final! There are no new features to brag about this time, but we did fix a good amount of issues so I recommend everyone to upgrade. This release will also be the basis for the next Red Hat Single-Sign On release.

To download the release go to the Keycloak homepage. Before you upgrade refer to the migration guide.

Tuesday, 3 January 2017

Keycloak 2.5.0.Final Released

Keycloak 2.5.0.Final has just been released.

There are no changes since 2.5.0.CR1. To download the release go to the Keycloak homepage. Before you upgrade refer to the migration guide

Thursday, 22 December 2016

Keycloak 2.5.0.CR1 Released

We've released Keycloak 2.5.0.CR1 just in time for Christmas. This release mainly focuses on bug fixing and we've resolved an impressive 165 issues in this release! Due to Christmas holidays the final release won't be until early January.

Highlights of the release includes:

  • User Storage SPI - We've removed the old User Federation SPI in this release. If you have custom user federation providers you will need to migrate them to the User Storage SPI.
  • HMAC Key Provider - We've added a secret key provider to be able to do HMAC signatures. These are faster than RSA signatures and are used for signing cookies.
  • Ability to disable Impersonation - If you don't want to allow admins to be able to impersonate users you can now fully disable this feature.

This is the second to last release in the Keycloak 2 series. Expect one more round of bug fixing and a 2.5.1.Final release towards the end of January. After that we'll get started on Keycloak 3!

Plans for Keycloak 3 are not finalized, but some things we're hoping to do next year include:

  • Multi data center support - It's kinda possible at the moment, but we are planning to do a lot of improvements in this area
  • Authentication SPI - We're aiming to cleanup the authentication SPI and may also be adding more built-in authentication capabilities
  • Validation on Admin Endpoints and Console - There's currently a lack of validation on the admin endpoints which could result in bad configuration
  • Profile SPI - Single configurable and extensible place to define validation for user validation for self-registration, account management and the admin console
  • New Account Management - New modern and easier to use account management console
  • Testing and CI - More automated testing, better test coverage and more Jenkins!

I'd like to wish everyone a merry christmas and a happy new year on behalf of the Keycloak team. We're looking forward to a adding loads more features and improvements to Keycloak in 2017!

For the full list of issues resolved check out JIRA and to download the release go to the Keycloak homepage.

Friday, 2 December 2016

Considering removing Mongo from Keycloak

We are considering removing Mongo support from Keycloak in 3.x. The reasons behind it is that there are a fair few issues in the current implementation, especially around consistency due to lack of transaction support in Mongo and often we update multiple documents. In many cases we rely on transactions to rollback to prevent partial updates, but this obviously doesn't work in Mongo.

With the fact that Mongo is already partially broken and the constant maintenance involved we're considering removing it and rather focus purely on the relational database back-end.

Another point to make is that we are not considering supporting Mongo in the supported version of Keycloak (Red Hat Single Sign-On). So we are never able to provide the same level of care and attention to it as we can for relational databases.

If we do decide to remove it we would make sure we provide a seamless and easy option to migrate from Mongo to a relational database!

I would like to gather some feedback from the community before doing anything. So please vote on the following Doodle:

Also, comments on this post is more than welcome!

I'll end with a comment - Time spent by core developer on maintaining Mongo could be better spent on awesome new features, testing and bug fixing!

Thursday, 24 November 2016

Keycloak 2.4.0.Final Released

Keycloak 2.4.0.Final has just been released.

There are no changes since 2.4.0.CR1. To download the release go to the Keycloak homepage. Before you upgrade refer to the migration guide