How users are managed#
In this section we will describe how Piveau handles authorization and user management.
Process#
graph RL
A(Frontend/Service) --> C(piveau access managment)
C --> D(Keycloak)
classDef green fill:#9f6,stroke:#333,stroke-width:2px;
classDef orange fill:#f96,stroke:#333,stroke-width:4px;
class A, green
class D orange
Piveau is comprised of multiple microservices, Open Source software and a set of distinct web-based user interfaces. In order to support Single Sign-On (SSO) for all user interfaces and authentication/authorization to all microservices, we use Keycloak[^1] as central identity and access management service.
Piveau uses fine-grained authorization follows the User-Managed Access (UMA)[^2] specification, where resource servers (back-end services) and a UMA-enabled authorization server (Keycloak) can provide uniform management features to user-owned resources such as catalogs and datasets.
Resources used in Piveau#
- Catalogues
- Datasets
How do we achieve this?#
For Catalogues resources we use Groups in keycloak. For each catalogue resource exists a corresponding group. This group will have the provider role and gets permission for the catalogue resource. We will define also two Roles:
Roles#
- operator
The operator role is allowed to manage catalogues. Each user that should have access to the catalogue resource must join this group.
How to install Keycloak#
To install the Keycloak please use official[^3] sources.
How to configure Keycloak to work with Piveau#
- Select 'Administration Console' and on the left hand side you'll see the 'Master' realm, hover over that and select 'Add realm' Add realm
- Give the realm name "piveau" and press Create.
How to add Roles#
We need to create Role operator will be used beResource server piveau-hub-repo. The operator role is allowed to manage catalogues. The operator role is also allowed to manage all datasets in all catalogues.
select piveau realm \< Create role >
and go to Realm Roles to create both Roles.
How to add users#
We need to create a User e.g. alice and assign the provider role that was created. With this Role user alice is allowed to manage catalogues. The operator role is also allowed to manage all datasets in all catalogues.
- On the left-hand menu, look for "Users". Click on that.
- To see which users already exist, click on "View all users"
- To add a user, click on "Add user"
- To create a valid user, you actually only need a name. The other fields are not mandatory.
How to set roles for users#
We are about to assign two roles developer and provider that was created in the Roles chapter to the user alice.
How to set permissions and roles for users and catalogues#
We use Groups for catalogue resources. Groups in Keycloak allow you to manage a common set of attributes and role mappings for a set of users. Users can be members of zero or more groups. Users inherit the attributes and role mappings assigned to each group.
For each catalogue resource exists a corresponding group. This group will have the provider role and gets permission for the catalogue resource. Each user that should have access to the catalogue resource must join this group.
Let's add user alice to the group govdata that belong to the govdata catalogue resource. Each user that should have access to the catalogue resource must join this group. So we will give alice user access to the govdata catalogue.
Select govdata group, select Members and add alice user to the Members of the group.
[^1]: Open Source Identity and Access Management
[^2]: Kantara Initiative:Federated authorization for user-managed access uma 2.0.