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
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.
