keycloak-rest-services

Services surrounding Keycloak, that use the REST API to read/update state.

JavaScript claims mappers

In the custom-jars directory are custom extensions to Keycloak. This is most useful for adding JavaScript claims mappers that can edit a token before it is issued.

Each mapper requires meta-inf info and one or more script files. Then it needs to be packaged into a jar for deployment to Keycloak. The build.sh script will build all subdirectories into jars.

These jars need to be added to /opt/keycloak/providers/ during the Keycloak build process or before Keycloak starts. After Keycloak is started no changes are allowed.

Running Tests

To run tests locally:

First, build and load the local python environment:

./setupenv.sh
. env/bin/activate

Then, start instances of Keycloak, LDAP, and RabbitMQ in other terminals:

./resources/start-keycloak.sh
./resources/start-ldap.sh
./resources/start-rabbitmq.sh

Note that version of Keycloak server used for testing is set in resources/keycloak-image/Dockerfile.

Keycloak may take a minute to start. If it does not, check your network settings, as it does not play well with VPNs and other more exotic network situations.

Finally, run the tests:

source ./resources/pytest-env.sh
pytest

Getting Test Coverage

If you want a coverage report, instead of running pytest directly, run it under the coverage tool:

keycloak_url=http://localhost:8080 username=admin password=admin coverage run -m pytest
coverage html --include='krs*'

Manually Running Scripts

It is possible to manually run all of the basic operations for controlling users and groups.

1. Bootstrap Keycloak

   If you do not already have a Keycloak instance, start a test instance as shown above. Then, run the bootstrap script to create a realm and the REST service account:

   keycloak_url=http://localhost:8080 username=admin password=admin realm=test python3 -m krs.bootstrap
   

   Save the client_secret that gets printed, as you will need this.

2. User and group actions

   Now you can actually run the scripts, which take the format:

   keycloak_url=http://localhost:8080 client_id=rest-access client_secret=<SECRET> realm=test python -m krs.<SCRIPT> <ARGS>
   

   As an example, to list all groups:

   keycloak_url=http://localhost:8080 client_id=rest-access client_secret=<SECRET> realm=test python -m krs.groups list