diff --git a/src/guide/admin/keycloak-access-control.md b/src/guide/admin/keycloak-access-control.md index 4ced1333..b417a606 100644 --- a/src/guide/admin/keycloak-access-control.md +++ b/src/guide/admin/keycloak-access-control.md @@ -16,7 +16,7 @@ keycloak: adminPassword: myDefaultPassword ``` -## Creating a New Admin User +## Access Control Initially, only one user can access the Node UI since only the root user is created in Keycloak during deployment. In order to create another user with the ability to sign in to the Node UI via Keycloak, navigate to the Keycloak console. This can be found by appending `/keycloak` to the end of the domain used for the Node UI e.g. @@ -24,7 +24,7 @@ console. This can be found by appending `/keycloak` to the end of the domain use ### Creating a New User -Login to Keycloak with the `adminUser` and `adminPassword` used during deployment as described in the previous section. +Login to Keycloak with the `adminUser` and `adminPassword` values used during deployment as described in the previous section. Once logged in, change the current realm to the "flame" realm: [![Changing Keycloak Realms](/images/keycloak_images/keycloak_5.png)](/images/keycloak_images/keycloak_5.png) @@ -42,6 +42,27 @@ Your new user page should look similar to this: Click "Create" and the new user will be added, and you will be directed to the "Details" tab for the user. +### Role Based Access Control (RBAC) +Admins may wish to grant certain individuals access to the Node UI, but restrict what they can do. The node software +package allows for Node UI RBAC via the bundled Keycloak instance. Additioanl information on the roles and how to +configure their names can be found in the [Node Installation](/guide/deployment/node-installation#role-based-access-control-rbac) instructions. + +#### Assigning Users a Role +Login to the administrative keycloak console and navigate to the "flame" realm. If you wish to create a new user, follow +the steps in [Creating a New User](#creating-a-new-user), otherwise, click on the user that you wish to assign a role. Navigate +to the "Role Mapping" tab to view the current roles the user has (the default `flameuser` user should have the "admin" role) and +click on the "Assign role" button and then on "Client roles". + +[![Assigning a Role in Keycloak](/images/keycloak_images/keycloak_assigning_role.png)](/images/keycloak_images/keycloak_assigning_role.png) + +In the search box in the top left, search for role which you want to assign the user, either "admin", "researcher", or "steward". +There should be a result with the role name that has a "Client ID" of "node-ui". Checkmark this result and click "Assign". The user +now has this role and the permissions that come with it. + +::: info Role Names +If you modified the names of the roles during deployment in your `values.yaml` file, then you will see those names here instead. +::: + ### Setting a Temporary Password Finally, a temporary password must be set for the new administrator for their first login attempt. Click on the @@ -74,3 +95,4 @@ Admins can configure the FLAME software to use a separate IDP (i.e. different Ke useful when you already have an instance with your users and roles configured. This needs to be done during installation and instructions on how to achieve this can be found [here](/guide/deployment/node-installation#using-your-own-idp). + diff --git a/src/guide/deployment/node-installation.md b/src/guide/deployment/node-installation.md index 9da756d6..5627655f 100644 --- a/src/guide/deployment/node-installation.md +++ b/src/guide/deployment/node-installation.md @@ -94,6 +94,37 @@ all generated and configured within this included IDP. If you wish to your own I Adapter and the Node UI will have to be created and their secrets set in the values template. See the [Using Your Own IDP](#using-your-own-idp) section for more information. +#### Role Based Access Control (RBAC) +The node software package supports restricting the actions of certain users with access to the Node UI via RBAC. A +user can have one of three roles with the following names and permissions: +* **steward**: can modify/create data stores, but cannot start/stop/delete analyses or view their logs +* **researcher**: can start/stop/delete analyses and view their logs, but cannot modify data stores +* **admin**: full access + +The included Keycloak instance includes these roles by default, and the initially created `flameuser` is given the "admin" role. +The names of these roles can be modified in your `my-values.yaml`, and these changes will be reflected in Keycloak as well: + +```yaml +rbac: + roleClaimName: "resource_access.node-ui.roles" + adminRole: "admin" + stewardRole: "steward" + researcherRole: "researcher" +``` + +::: warning Role Claim Name +The `roleClaimName` value is specific for how the role is defined in the JWT provided by the bundled Keycloak, and +should not be modified. This only ever needs to be changed if you are [using your own IDP](#using-your-own-idp). +::: + +See the [Access Control](/guide/admin/keycloak-access-control#access-control) section of the documentation for more information +on how to create users and assign them specific roles. + +::: info Disabling RBAC +If you have no need for RBAC, it can be disabled by setting `roleClaimName` to an empty string (`""`). +::: + + ### Using Your Own IDP For better security, this software uses Keycloak for authenticating the various services and users that make up FLAME. @@ -107,6 +138,33 @@ clients as this information along with the (accessible) URL for your IDP must be An example of how to configure this in for your cluster can be seen in this separate IDP example. +#### RBAC +Admins using their own IDP who also wish to utilize RBAC for the Node UI will need to configure the roles using +their IDP's documentation. Once a the role is created and assigned to a user, the `roleClaimName` value needs to +be modified so that the role can be extracted from the JWT provided by the IDP. The `roleClaimName` value should +contain the keys leading to the role value in the decrypted JWT, with each hierarchical level separated by a +period ("."). + +In this example: +```json +{ + "sub": "1234567890", + "name": "John Doe", + "iat": 1516239022, + "access_control": { + "node-ui-client": { + "user-defined-roles": [ + "steward" + ] + } + }, + "scope": "openid email profile", + "email_verified": true +} +``` +the `roleClaimName` should be changed to `"access_control.node-ui-client.user-defined-roles"`. + + ## Installation At this point, you should have a custom values file (e.g. `my-values.yaml`) which contains the robot credentials and private key for your node. If you have all of this information, then you can proceed with deploying the FLAME Node by diff --git a/src/public/images/keycloak_images/keycloak_assigning_role.png b/src/public/images/keycloak_images/keycloak_assigning_role.png new file mode 100644 index 00000000..ca60c8bf Binary files /dev/null and b/src/public/images/keycloak_images/keycloak_assigning_role.png differ