Monday, 31 October 2016

Registering new clients from shell

Keycloak comes with a powerful web admin console that is a primary tool for configuring everything in Keycloak. As powerful as it is it does not lend itself to scripting. Automation requires the ability to script the admin tasks, and to facilitate that we've been working on CLI tools that would be friendly for automation as well as interactive shell use.

The first of the CLI tools - Client Registration CLI - is now available as part of Keycloak distribution. It allows creating and updating new clients - operations you would otherwise have to do in Web Admin Console under Clients section.

Client Registration CLI can be used by application developers that integrate their applications with Keycloak server, and don't necessarily have administrative privileges on the server itself. That is possible by way of special client creation tokens called Initial Access Tokens that can be issued by realm administrator, and distributed to developers for them to self-service. In that case developer doesn't even need a user account, Initial Access Token is their means of authenticating to perform client creation operations.

The Client Registration CLI can also be used by applications and services to dynamically self-register themselves. This makes it possible to automate the creation and management of client configuration by applications and services themselves.

In theory such self-service can be performed by using generic tools like curl or wget, but in reality the mechanics of handling the tokens requires writing code or shell script and debugging it before it starts to work properly. Client Registration CLI takes care of all of that. It can maintain state between invocations, it can handle tokens for you, and it's very easy to use.

You can find the tool in your KEYCLOAK/bin directory - it's called (or kcreg.bat on Windows).

Here's a little tour to give you a sense of what you can do with it.

Register an Initial Access Token received from admin

$ config initial-token --server http://localhost:8080/auth --realm demo

You will be prompted for the token issued to you by realm admin. The token will be saved to default configuration file at ~/.keycloak/kcreg.config

Declare which server and realm to use by default

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

Any operation from now on will use the set server, and realm as default values.

Alternatively you can login as user with client management rights - admin for example:

$ config credentials --server http://localhost:8180/auth --realm master --user admin --password admin --secret db2cd162-aa86-4154-a16e-a393c9db4f76

By default kcreg identifies to Keycloak server as client with clientId 'admin-cli'. It's a client automatically configured for every new realm to represent client tools like kcreg. We assume here that 'admin-cli' client has Access Type set to 'Confidential', and uses 'Client Id and Secret' for authentication. That's how we got the secret - from Credentials tab of Master realm's Clients section.

Create a new client configuration

$ create -s clientId=app-profile-jsp -s protocol=openid-connect -s rootUrl=http://localhost:8080/app-profile-jsp

That is enough to create a new public client using a standard flow for authentication - one for static html5 applications.

Get client configuration

To see the configuration we just created we can use:

$ get app-profile-jsp

Update client configuration

For this little tour we want to create a client for a dynamic web application hosted on a server, so we'll make the client `confidential`.

$ update app-profile-jsp -s publicClient=false

Get Keycloak Adapter configuration file

Now we want to get a configuration file to put inside our packaged web application:

$ get app-profile-jsp -e install > keycloak.json

We can now put keycloak.json in WEB-INF directory of our .war file.

Delete client configuration

We may not need some client configuration any more. We can easily delete it:

$ delete app-profile-jsp

This was a very simple tour tailored to interactive use. Client Registration CLI also supports more complex usage.

For example, it's possible to perform one time authentication for individual command, that doesn't save any tokens into a config file:

$ create --no-config -s clientId=app-profile-jsp -s protocol=openid-connect -s rootUrl=http://localhost:8080/app-profile-jsp -s publicClient=false --server http://localhost:8180/auth --realm master --user admin --password admin --secret db2cd162-aa86-4154-a16e-a393c9db4f76

All the kcreg commands accept additional options which you can learn about by using --help.

Client Registration CLI doesn't use Keycloak Admin REST, but rather a separate Client Registration REST service. It is thus limited in its scope, and tailored to the special use case of configuring new clients in a self-service manner.

Another more general Admin CLI tool is in the making that will use Keycloak Admin REST, and eventually allow all Web Admin Console operations to be performed through CLI.

Why not give Client Registration CLI a try, and let us know what you think.

Wednesday, 26 October 2016

Keycloak 2.3.0.Final Released

Keycloak 2.3.0.Final has just been released.

For the list of resolved issues check out JIRA and to download the release go to the Keycloak homepage. Before you upgrade refer to the migration guide

Friday, 21 October 2016

Keycloak 2.3.0.CR1 Released

We've just released Keycloak 2.3.0.CR1. This release brings a number of new existing features!

Highlights of the release includes:

  • OpenID Connect certification - We've now completed the work on making our OpenID Connect implementation pass the OpenID Connect certification and we're currently passing all 5 profiles!
  • User SPI - We now have a new simpler User SPI. This will make it easier to implement a custom user provider to pull in users from any external user store. In the next release we'll port our LDAP provider to this SPI, which will make it possible to pull in users from LDAP without syncing data to the Keycloak database. Once this work is completed we'll remove the old User Federation SPI.
  • Realm Key Rotation - We now support multiple keys in a realm. This makes it possible to seamlessly rotate keys without any impact to applications and users.
  • Client Registration CLI - A while back we added dynamic client registration capabilities, we've now created a CLI that makes it easy to register and update clients from the command-line.
  • Dynamic Client Registration Policies - We've introduced a mechanism to control what clients can be dynamically created. This includes the ability to define policies to allow clients to register without the need to authenticate.
  • Node.js Adapter - We've had a Node.js adapter a while, but we've now polished it a lot and made it a first class citizen.

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