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

The tests run automatically in CircleCI, but for those that want to run them locally, there is a way.

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