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 kcreg.sh (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


$ kcreg.sh 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


$ kcreg.sh 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:

$ kcreg.sh 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


$ kcreg.sh 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:

$ kcreg.sh 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`.

$ kcreg.sh 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:

$ kcreg.sh 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:

$ kcreg.sh 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:

$ kcreg.sh 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.

3 comments:

  1. Great idea. What we need in our project is an integration of Keycloak admin tasks for realm- and client-management in our JEE application and also in our deployment scripts. Up to know we thought about preparing realms and associated clients via the admin-console on a separate building environment and deploying the so prepared realms by export/import mechanism, but this is a rather inflexible approach.

    ReplyDelete
  2. Hi thanks for nice document.

    How to get an Initial Access Token received from admin?

    ReplyDelete
  3. Is there a REST API available to do the same thing? How can we do it?

    ReplyDelete

Please only add comments directly associated with the post. For general questions use the Keycloak user mailing list.