Aleph

On this page

Last updated on 2024-12-02.
Edit this page on GitHub.

How to Set Up an Identity Provider for Development

When making changes to the OAuth authentication flow in Aleph, it can be helpful to test changes against a real identity provider. This guide describes how to run the Keycloak identity provider in your local development environment and how to configure Aleph accordingly.

This guide describes how to set up Keycloak in a development environment. If you want to configure a production Aleph instance to use Keycloak as an identity provider, please refer to our operations guide.

Set up Keycloak

The official Keycloak documentation provides detailed instructions on how to run Keycloak using Docker. You can follow these instructions for the most part. However, you will have to make a few minor changes:

  1. The default port used in the Keycloak documentation is 8080. In an Aleph development environment that port is already in use for the Aleph UI. Adjust the port mapping for the Keycloak container to use a different port:

    docker run -p "8888:8080" -e "KEYCLOAK_ADMIN=admin" -e "KEYCLOAK_ADMIN_PASSWORD=admin" quay.io/keycloak/keycloak:23.0.1 start-dev

  2. After creating a new realm in the Keycloak admin console, set the “Frontend URL” setting to http://localhost:8888. This is necessary to ensure that Aleph redirects you to the correct URL during the authentication flow.

  3. When creating a new client using the Keycloak admin console, change the following settings:

    SettingValue
    Client authenticationEnabled
    Valid redirect URIshttp://localhost:8080/api/2/sessions/callback
    Valid post logout redirect URIshttp://localhost:8080/

  4. After creating a new client using the Keycloak admin console, switch to the “Credentials” tab and take note of the client secret.

Configure Aleph

Finally, you need to adjust Aleph’s configuration to use your local Keycloak instance instead of the default password authentication flow.

  1. Set the following Aleph configuration options:

    Configuration optionValue
    ALEPH_OAUTHtrue
    ALEPH_OAUTH_KEYmyclient
    ALEPH_OAUTH_SECRETClient secret from previous step
    ALEPH_OAUTH_METADATA_URLhttp://host.docker.internal:8888/realms/myrealm/.well-known/openid-configuration
    ALEPH_PASSWORD_LOGIN=falsefalse

  2. Restart Aleph, visit the Aleph UI at http://localhost:8080, and click on the “Sign in” button in the navigation bar to test the authentication flow.

Sync user groups

Aleph can automatically sync user groups from certain identity providers, including Keycloak. If you want to test this feature in your development environment, you need to apply additional settings in the Keycloak admin console.

  1. In the Keycloak admin console, switch to the “myrealm” realm you created previously.

  2. Navigate to the “myclient” client you created previously.

  3. Switch to the “Client scopes” tab and select the “myclient-dedicated” scope.

  4. In the “Mappers” tab, click on “Configure a new mapper”.

  5. Choose “Group Memberships” as the mapper type and fill in the form:

    SettingValue
    NameGroup memberships
    Token Claim Namegroups

  6. Click “Save”.

  7. Navigate to the “Groups” section and create a new group.

  8. Click on the group you created, switch to the “Members” tab and add the user you created previously to the group.

  9. Aleph syncs group memberships everytime a users signs in. To test the configuration changes switch to the Aleph UI, sign out, then sign in again. You should now see the group created in the previous step in the left sidebar in the “Groups” section.