wipac-keycloak-rest-services 1.5.1
Services surrounding KeyCloak, that use the REST API to read/update state
Requires Python: <3.15,>=3.10
Keywords: WIPAC, rest tools, utilities

<!--- Top of README Badges (automated) --->
[![PyPI](https://img.shields.io/pypi/v/wipac-keycloak-rest-services)](https://pypi.org/project/wipac-keycloak-rest-services/) [![GitHub release (latest by date including pre-releases)](https://img.shields.io/github/v/release/WIPACrepo/keycloak-rest-services?include_prereleases)](https://github.com/WIPACrepo/keycloak-rest-services/) [![Versions](https://img.shields.io/pypi/pyversions/wipac-keycloak-rest-services.svg)](https://pypi.org/project/wipac-keycloak-rest-services) [![PyPI - License](https://img.shields.io/pypi/l/wipac-keycloak-rest-services)](https://github.com/WIPACrepo/keycloak-rest-services/blob/master/LICENSE) [![GitHub issues](https://img.shields.io/github/issues/WIPACrepo/keycloak-rest-services)](https://github.com/WIPACrepo/keycloak-rest-services/issues?q=is%3Aissue+sort%3Aupdated-desc+is%3Aopen) [![GitHub pull requests](https://img.shields.io/github/issues-pr/WIPACrepo/keycloak-rest-services)](https://github.com/WIPACrepo/keycloak-rest-services/pulls?q=is%3Apr+sort%3Aupdated-desc+is%3Aopen)
<!--- End of README Badges (automated) --->
# 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:

    ```bash
    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:

    ```bash
    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:

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