ARLAS with Keycloak

What is it?

Keycloak aims at adding an Identity and Access Management (IAM) to the ARLAS stack.
Keycloak provides authentication (user login) and authorisation (permissions to access data and APIs) services to ARLAS components: server, WUI, hub, builder...

The stack can be started with or without Keycloak.

ARLAS with Keycloak is composed of 3 main components:

1. an implementation of the ARLAS PolicyEnforcer (interface available in the ARLAS-server/arlas-commons module: io.arlas.filter.core.PolicyEnforcer)
   • Keycloak implementation (io.arlas.filter.impl.KeycloakPolicyEnforcer)
2. a Keycloak instance.
3. An optional resources.yaml file to define the Keycloak resources (see Keycloak v23.0 Configuration section)

Policy Enforcers configuration

The policy enforcers are in the arlas-commons module.
The implementation to activate must be defined in the backend component configuration:

Further configuration is required:

Optional configuration:

Keycloak v23.0 Configuration

Concepts

Keycloak is configured through multiple items. ARLAS uses only a subset of them, which are described here.

• Realm: a realm is the container of the configuration used by an ARLAS instance (clients, users, groups...)
• Client: a client contains the configuration that controls the ARLAS components access.
  • Client roles: roles can be given to users in order to control their rights. Some role names must follow some specific naming rules (such as ARLAS groups).
  • Authorization/Resources: resources are a list of ARLAS rules and headers (see before). Their names contain the rule/header to be sent to ARLAS. Resources with the same type value can be referenced together through that value in permissions.
  • Authorization/Policies: policies are pieces of logic that are used to check a condition. For now only "role policies" are used: it checks if a user has a given client role.
  • Authorization/Permissions: only "resource-based" permissions are used. They associate resources or resource types with policies. Whenever a permission's policy matches, the associated resources are sent to ARLAS in the authentication process of a user (in the permission claim of the RPT : requesting party token)
• Groups: are used to group together a list of client roles in order to facilitate their allocation to users. Modifications to a group (adding/removing roles) will be spread to all users belonging to the group. This is not the same concept as an ARLAS group.
• Users: are accounts allowed to connect to ARLAS. They can (and should) belong to keycloak groups and can also be mapped to individual client roles.

There are four types of roles used by ARLAS, which are distinguished by their prefixes:

• group/
• role/arlas/
• role/data/
• role/m2m/importer

Roles prefixed with group/ are used to manage access to dashboards. The specific group group/public allows you to share dashboards with unauthenticated users. Groups prefixed with group/config.json/ allow you to define access groups for dashboards (but not for data!).

Roles prefixed with role/arlas/ are used to define access to ARLAS services:

Roles prefixed with role/data/ are used to define data access. By default, the role/data/all role must be created and grants access to all data to users having that role. Other roles (role/data/xxx), can be created and associated with a resource, which is itself associated with a permission, which is itself associated with a policy. Important: the role/data/all role must not be assigned to users having more restricted access through other role/data/xxx roles.

The role/m2m/importer role allows collections to be imported via the dedicated endpoint on the ARLAS server, primarily used by M2M processes.

Manual configuration

In order to configure Keycloak from scratch, follow this tutorial, as a minimum set of settings to make it work with ARLAS.
Another way is to import the default configuration file given with this module (see next section).

1. Create a realm. Its name must be configured in ARLAS_AUTH_KEYCLOAK_REALM. Switch to the realm administration console. The following lines refer to the appropriate menu items from the console with a prefix text in parentheses (left menu/right tabs/...), e.g. (Clients/Lookup)
2. (Clients/Lookup/Create) Create a new client with:
   • Client ID=arlas-backend (must be configured in ARLAS_AUTH_KEYCLOAK_RESOURCE)
   • Client Protocol=openid-connect
   • Next
3. (Clients/Arlas-backend/Capability Config) Change the following configuration items:
   • Client authentication=ON
   • Authorization=ON
   • Standard Flow=ON
   • Next
   • Direct access grants=ON
   • Valid Redirect URIs=*
   • Valid post logout redirect URIs=*
   • Web Origins=+
   • Save
4. (Clients/Arlas-backend/Login settings) Select Client Authenticator "Client Id and Secret" and copy the Secret value to ARLAS_AUTH_KEYCLOAK_SECRET
5. (Clients/Arlas-backend/Roles) Add the following roles:
   • group/public (See groups in Concepts)
   • group/config.json/xxx: add as many groups as needed where xxx will be the name of groups available to share dashboards in ARLAS hub and that can be associated to data filters.
   • role/arlas/builder (See role/arlas/ in Concepts)
   • role/arlas/tagger
   • role/arlas/user
   • role/arlas/downloader
   • role/arlas/datasets
   • role/data/all (See role/data/all in Concepts)
   • role/data/xxx: add as many roles as needed where xxx will be a role linked to a data permission (see Protect data access)
   • role/m2m/importer (rule to import collections via the dedicated ARLAS server endpoint, mainly used by M2M processes)
6. (Clients/Arlas-backend/Authorization/Policies) Add role policies for each new role you have added. Choose a policy type Role. Keep the logic to Positive. Choose the relevant role in the arlas-backend roles list.
7. (Clients/Arlas-backend/Authorization/Resources) Add any resource header:name:value (as name) you need (optionally setting a type if you need to map more than one in a group/config.json/... role) and create permission (select relevant role policy).
   If the resource length is too long for the Keycloak resource name, you must use the resources.yaml configuration file to define the resources.
   In that case, the resource name in Keycloak must be the one defined in the resources of resources.yaml and the resource value will be define in the values part under the name in the yaml.
   Example of resources.yaml file:

    resources:
     resourceTooLongForKeycloakName:
      description:
       - "resourceTooLongForKeycloakName description"
      values:
       - h:partition-filter:{*:*}
   

   You can use the environment variable ARLAS_AUTH_INIT_RESOURCES_PATH to set the path of the resources.yaml file.
   A basic example: you might need to authorize a user to see all the fields of all the collections. This is a resource named h:column-filter:*:*. Create a role and policy named role/data/all. Then create a resource named h:column-filter:*:* and create a permission for this resource and apply role/data/all to it.
8. (Groups) Add groups with some arlas-backend client roles according to the way you want to assign permissions to users.
9. (Users) Add users:
10. Username= choose name
11. Groups= choose groups
12. Role mappings: assign relevant individual roles from arlas-backend client roles if not assigned through groups
13. Save
14. (Users/\<user>/Credentials) Set password
15. (Clients/Lookup/Create) Create a new client with:
    • Client ID=arlasm2m
    • Client Protocol=openid-connect
    • Next
16. (Clients/Arlasm2m/Capability config) Change the following configuration items:
    • Access Type=confidential
    • Switch off Standard Flow Enabled
    • Switch on Service Accounts Enabled
    • Save
17. (Clients/Arlasm2m/Service Account Roles) Select arlas-backend in the Client Roles drop down list and add selected roles:
    • role/arlas/user
    • role/m2m/importer
    • group/public (to create public dashboard)
18. (Clients/Lookup/Create) Create a new client with:
    • Client ID=arlas-front (must be configured in arlas frontend app configurations)
    • Client Protocol=openid-connect
    • Save
19. (Clients/Arlas-backend/Capability config) Change the following configuration items:
    • Client authentication=OFF
    • Authorization=OFF
    • Standard Flow=ON
    • Direct access grants=OFF
    • Implicit Flow=OFF
    • Valid Redirect URIs=*
    • Valid post logout redirect URIs=+
    • Web Origins=*
    • Save

Import configuration

1. In the realm selection drop down list, select "Create realm".
2. Select the file to import and click Create (template is in https://github.com/gisaia/ARLAS-Exploration-stack/blob/develop/conf/keycloak/keycloak.realm.json)
3. (Clients/Arlas-backend/Credentials) Select Client Authenticator "Client Id and Secret", regenerate the secret, and copy the Secret value to ARLAS_AUTH_KEYCLOAK_SECRET
4. (Clients/Arlasm2m/Credentials) Select Client Authenticator "Client Id and Secret", regenerate the secret (and copy if needed)
5. (Clients/Arlas/Roles) Add the following roles:
   • group/config.json/XXXXX: add as many groups as needed where XXXXX will be the name of groups available to share dashboards in ARLAS hub and that can be associated to data filters.
6. (Clients/Arlas/Authorization/Policies) Add role policies for each new group you have added
7. (Clients/Arlas/Authorization/Resources) Add any header:name:value you need (optionally setting a type if you need to map more than one in a group/config.json/... role) and create permission (select relevant role policy)
8. (Groups) Add groups with some arlas-backend client roles according to the way you want to assign permissions to users.
9. (Users) Add users:
10. Username= choose name
11. Groups= choose groups
12. Role mappings: assign relevant individual roles from arlas-backend client roles if not assigned through groups
13. Save
14. (Users/\<user>/Credentials) Set password