[keycloak-dev] Client Registration CLI tool

[John Dennis]

On 06/27/2016 07:48 AM, Marko Strukelj wrote:
> I've started work on Client Registration CLI tool. As a first step, here
> is a design document describing how I imagine the tool would be used.
>
>
> https://docs.google.com/document/d/18SoZ34sY_k7N8ae-WDsvo7QeI-cHkpTURIlUk5dpIhU/edit?usp=sharing
>
>
> I'll use this document as a spec / guide as I implement the client tool.
>
> Within days I'll also send a link to initial ideas for Admin Client tool
> which in principle should allow administrator to configure everything
> that can otherwise be done through Admin Console.
>
> Any feedback welcome.

FWIW we've already written a client registration tool for Keycloak. At 
the moment it is specifically targeted for SAML clients (SP, Service 
Provider) in Apache HTTPD but we have plans to extend it to OIDC.

It is currently in Fedora and will also ship in OSP.

It is hosted here:
https://github.com/jdennis/keycloak-httpd-client-install

The man page for it (formatted for HTML) can be found here:
https://jdennis.fedorapeople.org/doc/keycloak-httpd-client-install.html

The man page discusses 3 different ways you can authenticate and 2 
different ways client registration can be performed.

I have a lot of experience with Keycloak client registration tools and 
have worked through many issues, I'm happy to share my experience.

Here are some thoughts/issues you may want to take into account:

* The tool must be capable of running without interactivity as part of a 
scripted installation task.

* It should not depend on a home directory being available.

* If a home directory is utilized how will you disambiguate any stored 
state belonging to a script that is run by different processes but under 
the same user (possibly simultaneously)? To clarify, many install tools 
run as the root user or some other admin user. Each invocation of these 
install tools can be run with entirely different parameters and may 
execute either in parallel or partially overlapping in time.

* The tool should be idempotent.

* You suggest storing tokens in a cache, how do you plan on handling the 
case where a token expires before all operations are complete?

* We also initially took the approach of caching tokens but discovered 
the complexity did not justify the minimal cost of obtaining a new token 
for each invocation. This greatly simplified the code with very little 
performance impact.

* You do not mention what type of client you're registering. I'm 
assuming it's OpenID but SAML clients (SP) are equally important. The 
tool must be able to handle both.

* I don't see anything in your document on how to specify the SAML metadata.

* I don't see anything in your document on how the user modifies the 
client. It appears as if you are retrieving a ClientRepresentation JSON 
document and expecting the user to edit it in a text editor which will 
then be sent back. That won't work for non-interactive installs. It also 
presumes the user knows how to read and modify the JSON.

* Keycloak currently has a few problems with client registration and 
it's necessary to modify the client before it will work correctly. We 
currently do this via the REST API. How are you planning on handling 
these issues in your installer? It would be nice if the installer was 
aware of the Keycloak version and could apply "fix-ups" as needed based 
on the version.

* Keycloak has two ways to register a client (client registration 
service vs. REST API). The two methods do not produce the same client 
configuration (I suspect because they do not share common code in the 
server). How are you planning on addressing the discrepancies?

* The tool should be smart enough to produce a working client without 
manual intervention (i.e. the need to run admin cli commands afterwards 
to fix problems). Most admins won't know how to tweak the configuration.

* The tool should not have significant dependencies.

Those are the thoughts off the top of my head, as you fill out the 
details I'll continue to review. Recall the plan of record is for 
Keycloak to provide such tools which we will then utilize. The 
keycloak-httpd-client-install tool is a stop-gap solution until such 
time as "offical" tools become available.



-- 
John