Manage Users

After mapping your users from your OpenID Connect (OIDC) identity provider using either Just-In-Time (JIT) User Provisioning or the web UI / API process as described in the Create a User section, you can leverage user groups for efficient access control management.

User groups, organized by roles, departments, or other relevant criteria, enable streamlined permissions assignment. This not only simplifies user onboarding and role adjustments but also enhances data security.

Diagram illustrating how user permissions and access to data are managed through user groups in a GoodData deployment. A data source connects to the Sales Workspace, which is accessible by three user groups: Admin Group (Manage permission), Sales Analysts Group (Analyze permission), and Sales Viewers Group (View permission). Individual users are shown as members of these groups: Admin is in the Admin Group, Analytics Engineer is in the Sales Analysts Group, Analytics Consumer is in the Sales Viewers Group, and Analytics & Financials Consumer is in both the Sales Viewers Group and the Financials Viewers Group. The Financials Viewers Group belongs to a separate Financial Department section.

Create a User

To create a new user in GoodData, the user must already exist in your OIDC identity provider and you must know the user’s sub claim - the value of a user’s sub claim is provided by your OIDC identity provider.

In general, we recommend you automate the creation of users either through the use of JIT user provisioning or by creating an automated pipeline using the API call described below. Creating users manually using the web UI is best reserved for test scenarios or to address specific edge cases.

Steps:

  1. On the home page, switch to the Users & groups tab.

    The home page left-hand menu with the Users & groups tab selected.

  2. Click Add user.

    The Add user button highlighted in the top right corner of the Users & groups page.

  3. Fill in the user’s name, email (optional) and their sub claim. You can also assign them to user groups.

    Add user dialog with fields for first name, last name, email, authentication ID, and user group assignment. Cancel and Add buttons are in the bottom-right corner.

  1. Click Create.

    The user is created.

    The process depends on the identity provider (IdP) you are using:

    • Using Your Own IdP: The user creates their account first. After that, you can update their permissions.

    • Using GoodData’s Hosted IdP: When an invitation is sent to the user’s email, an account with its metadata is created in GoodData at the same time. This lets admins set permissions for the account before the user logs in for the first time.

    Users & groups page showing a list of users, displaying their name, email, group memberships, and assigned workspaces.

    Next we recommend you assign the user to one or more user groups. See Create a User Group below if you did not create any yet.

  2. Click on the user to open the user’s setting dialog, switch to the Groups tab and click on Add to group.

    User settings dialog with the Groups tab selected. A message indicates the user is not in any group. Add to group button is at the bottom-left of the dialog.

  3. Add one or more groups and Add the user to them

    Add to group dialog with a search bar and relevant groups listed below it. The Add and Cancel buttons are in the bottom-right corner.

    The user now has access to all workspaces (and data sources) that are assigned to the user groups.

    The Users table on the Users & groups page showing that the user belongs to the Sales Viewers group and has access to the Sales and Presales workspaces. The Groups and Workspaces columns are highlighted.

Create a user by making a POST call to the API endpoint /api/v1/entities/users/ with the user definition in its payload:

curl $HOST_URL/api/v1/entities/users \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/vnd.gooddata.api+json" \
-X POST \
-d '{
    "data": {
        "id": "<userId>",
        "type": "user",
        "attributes": {
        "authenticationId": "<subClaim>",
        "email": "<email>",
        "firstname": "<firstName>",
        "lastname": "<lastName>"
        },
        "relationships": {
        "userGroups": {
            "data": [{
            "id": "<userGroupId>",
            "type": "userGroup"
            }]
        }
        }
    }
}'

Create a User Group

All users should be assigned to one or more user groups. Permissions may be allocated to user groups, and these permissions then extend to all users within the group.

Steps:

  1. On the home page, switch to the Users & groups tab.

    The home page left-hand menu, with the Users & groups tab selected.

  2. Click on Create group.

    The Add group button highlighted in the top right corner of the Users & groups page.

  3. Assign a descriptive name to the group and Create it.

    Add group dialog with a group name field. Cancel and Add buttons are in the bottom-right corner.

    The user group has been created. In the following steps you will assign workspace permissions to this group to let its members access the designated workspaces.

  4. Locate the newly created user group in the Groups tab and click on it.

    Users & groups page showing a list of groups, displaying the number of group members and assigned workspaces.

  5. Switch to the Workspaces tab and click Add workspace permission.

    Group settings dialog with the Workspaces tab selected. A message indicates the group does not have permissions for any workspace. Add workspace permission button is at the bottom-left of the dialog.

  6. Select workspaces you want the members of this group to get access to, and specify the level of their access rights.

    Add workspace permission dialog with a search bar and relevant workspaces listed below it. The Permission level dropdown and the option to include the workspace's sub-hierarchy are to the right of the workspace's name. The Add and Cancel buttons are in the bottom-right corner.

  1. Click Add.

    You can now see the workspaces you have assigned to this group:

    Group settings dialog with the Workspaces tab selected. The added workspaces are listed and the permission level is shown, including its validity for the workspace's sub-hierarchy.

  2. Switch to the Members tab and click Add members.

    Group settings dialog with the Members tab selected. The Add members button is highlighted in the bottom-left corner.

  3. Select users you want to add as members of this group.

    Add group members dialog with a search bar and relevant users listed below it. The Add and Cancel buttons are in the bottom-right corner.

  4. Click Add.

    You can now see the users you have assigned to this group:

    Group settings dialog with the Members tab selected and the added members listed below.

    Your user group is all set up!

    Users & groups page showing a list of groups, displaying the changed number of group members and assigned workspaces.

Using the API to manage user groups involves a few steps due to how permissions are structured. Permissions are directly linked to their respective objects, such as workspaces. Therefore, to effectively set up a user group through the API, you’ll need to complete three key actions:

  1. Create a new user group.
  2. Link the user group to the desired workspaces.
  3. Add users to the user group.

Steps:

  1. Create a new empty user group by making a POST call to the API endpoint /api/v1/entities/userGroups with the user group definition in its payload:

    curl $HOST_URL/api/v1/entities/userGroups \
-H "Content-Type: application/vnd.gooddata.api+json" \
-H "Accept: application/vnd.gooddata.api+json" \
-H "Authorization: Bearer $API_TOKEN" \
-X POST \
-d '{
    "data": {
        "type": "userGroup",
        "id": "<userGroupId>",
        "attributes": {
        "name": "<userGroupDisplayName>"
        }
    }
}'

  2. Assign the user group to a workspace by making a POST call to the API endpoint /api/v1/actions/workspaces/<workspaceId>/managePermissions/ with an array of user groups that you want to assign permissions to access this workspace:

    curl $HOST_URL/api/v1/actions/workspaces/<workspaceId>/managePermissions/ \
    -H "Authorization: Bearer $API_TOKEN" \
    -H "Content-Type: application/json" \
    -X POST \
    -d '[
    {
        "assigneeIdentifier": {
            "id": "<userGroupId>",
            "type": "userGroup"
        },
        "permissions": ["VIEW"]
    }
]'

    Repeat this step for all workspaces that you want this user group to have access to.

    Note that you can use either permissions or hierarchyPermissions, see Manage Workspace Permissions for the difference between them.

  3. Add members to your user group by making a POST call to the API endpoint /api/v1/actions/userManagement/userGroups/<userGroupId>/addMembers with an array of users to be added:

    curl $HOST_URL/api/v1/actions/userManagement/userGroups/<userGroupId>/addMembers \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/vnd.gooddata.api+json" \
-X POST \
-d '{
    "data": {
        "members": [
            {
                "id": "<userId>"
            }
        ]
    }
}'

    Your user group is all set up!