How can I define a new role?

A ROLE is a permission to access certain closed data. You can think of it as a group to which a user might belong to, to see more data.

Which data is available for a certain role is defined inside our Mobility API / ACL rules.

Per default all data is closed, if you want to make it an Open Dataset, add to GUEST.sql, otherwise add to the different role definitions.

Step-by-step in Keycloak

For example, if you would like to create a new role called LAIMBURG, do the following:

1. Go to Keycloak / Clients
2. Open odh-mobility-v2
3. Then to "Roles > Add Role"
4. Add a role prefixed with BDP_ and a description for it: BDP_LAIMBURG
5. Create a new file in Mobility API / ACL rules with name LAIMBURG.sql (all uppercase)
6. Add the filename to the list of rules inside rules.txt
7. Inside that file create an SQL statement which gets added to a SQL WHERE clause afterwards. Make sure to surround that statement with ( and )... see other files in that folder for some examples

Example for LAIMBURG.sql:

-- Laimburg can see all data with origin = laimburg
(
    s.origin = 'laimburg'
)

Hint: See our swagger specs to understand prefixes of query columns, here s stands for station for example

Scopes in related clients

When you add a new Keycloak role, make sure that associated client roles allow them. This can be accomplished in two ways.

For example, if you want to activate the new BDP_LAIMBURG role in https://analytics.opendatahub.com, you need to do the following:

1. Go to Keycloak / Clients
2. Open odh-mobility-analytics
3. Then to "Scope", now you have two possibilities:

• Easier, but less secure:
  1. Allow Full Scope Allowed
• More work, but better security:
  1. Disable Full Scope Allowed
  2. Go to Client Roles and search for odh-mobility-v2
  3. Enable all roles that you want to allow for this application

4. Finally, you need to repeat these steps for all clients that access odh-mobility-v2