This project turns possible to register clients in Keycloak in an automated way.
Here, Keycloak is managed by Docker.
The Admin CLI is invoked inside the created container by matrix-functions.sh to create realms, and manage the clients.
Let’s see how this works by following the next steps.

1. Prerequisites

  1. Docker installed.

  2. A macOS or Linux operational system.

This project was only tested on macOS 10.15.6 and Linux Ubuntu 20.04.1.

2. Download the project and change the current directory

$ git clone https://github.com/paulojeronimo/keyckoak-matrix
$ cd `basedir $_`

3. Turn the Matrix functions available in your shell

$ source functions.sh

  1. The line above will turn available the matrix-* functions in your shell. You can see what are these functions by typing the following command:

    $ set | grep ^matrix- | sort

  2. It will also put a line inside your ~/.bashrc or ~./bash_profile (depend on with OS you are using) with will automatically load this script for you. You can check this by running the following command:

    $ [[ $OSTYPE =~ darwin ]] && profile=~/.bash_profile || profile=~/.bashrc
$ grep functions $profile

4. Start the Matrix

$ matrix-create

  1. You can now open http://localhost:8080/auth/admin/ and log in using the credentials configured in config.sh. The credentails are configured by two shell variables: MATRIX_ADMIN_USER and MATRIX_ADMIN_PASSWORD.

    1. The config.sh is a copy of the file config.sample.sh with your own configurations (and it is ignored by Git).

  2. The matrix-create function will start a Keycloak docker container. This container will be an instance of the image configured in the file config.sh. The docker image (and the created container) can be checked by the following commands:

    $ docker images | grep keycloak
$ docker container ls | grep keycloak

  3. You can also use the matrix-status function to discover if Keycloak is started.

    $ matrix-status

  4. Wait until Keycloak is started! You can check the logs by using the command docker logs -f keycloak until you see a line like this:

    00:57:26,386 INFO  [org.jboss.as] (Controller Boot Thread) WFLYSRV0051:
Admin console listening on http://127.0.0.1:9990

5. Run the sample apps

5.1. Plain JavaScript

5.1.1. Starting and configuring Keycloak

$ matrix-project-add samples/plain-js/

  1. The matrix-project-add function will add the specified project.

    1. A project is a directory containing a file called matrix-functions.sh. The function with suffix -project-add (inside this file) will be called automatically.

5.1.2. Starting the webapp

$ samples/plain-js/serve.sh &

  1. This will start a local server listening on port 3000 and serving the directory plain-js/webapp which contains an static HTML file called index.html.

$ open http://localhost:3000

  1. If you are using Linux, type xdg-open in place of open in the command above.

  2. You will need to register an new user. After that you will be automatically redirected to the app, as a logged user.

5.1.3. References

5.2. React

TODO

5.3. Angular

TODO

5.4. Spring Boot

TODO