Manage groups

In this tutorial, you are going to learn how to create, manage, and delete groups using Qlik Cloud management APIs.

Groups are used for access control and sharing of content in Qlik Cloud, and are most commonly populated from your Identity Provider, either as users log in, or via SCIM if you’re using a compatible Identity Provider such as Azure AD.

This means that deleting groups from a tenant does not prevent them from reappearing permanently - you will need to make changes in your Identity Provider configuration if you wish to filter these out of user claims before they are sent to Qlik Cloud.

For more information on configuring Identity Providers, see here.

The use of groups means that your Identity Provider becomes responsible for the majority of access control in the platform. Any groups that you might create in your tenant via API rely on relationships passed via the user’s claims from the Identity Provider.

Note: Groups must be passed in a valid claim from your chosen Identity Provider in order to be associated with a user. There is no way to manage the relationship between users and groups in Qlik Cloud.

Prerequisites

• You have a basic understanding of Qlik Cloud and its access control rules for creating content and managing spaces.
• cURL for running the inline examples.
• qlik-cli@1.5.0 or greater if running qlik-cli commands

Note: The cURL examples in this topic show the command syntax for Windows Command Prompt. If you are using another command line interface, different syntax may be required for line continuation. You may also need to adjust the number and type of quotes surrounding the parameters and their values.

Variable substitution

Throughout this tutorial, variables will be used to communicate value placement. The variable substitution format is <VARIABLE_NAME>. Here is a list of variables referred to in this topic.

Create a group and assign a role to it

Creating groups on the tenant helps to facilitate the setup of spaces and security before users first log in. By assigning roles, space access, or section access to groups, you remove the need to assign these to each user, but it also means that the user has immediate access to the required content as soon as they log in, without waiting for someone to add them to a resource.

For a description of the various security roles that can be applied to groups, see What is a security role.

Note: Roles are case sensitive. For a full list of tenant roles, refer to the List Roles > endpoint. For a full list of space roles, retrieve the space using the List Spaces > endpoint.

Here’s a cURL example that shows you how to create a group and assign the Developer role to it.

curl -L "https://<TENANT>/api/v1/groups" ^
-X POST ^
--header "Content-Type: application/json" ^
--header "Authorization: Bearer <ACCESS_TOKEN>" ^
--data "{\"name\": \"<GROUP_NAME>\", \"status\": \"active\", \"assignedRoles\": [{\"name\": \"Developer\"}]}"

The result is a JSON object where id is the <GROUP_ID>. Keep a note of this <GROUP_ID> because you will need it when you update group roles in the next section of this tutorial.

{
    "id": "649c6d64cf28896726e572ae",
    "tenantId": "BL4tTJ4S7xrHTcq0zQxQrJ5qB1_Q6cSo",
    "createdAt": "2023-06-28T17:27:00.502Z",
    "lastUpdatedAt": "2023-06-28T17:27:00.502Z",
    "name": "<GROUP_NAME>",
    "status": "active",
    "assignedRoles": [
        {
            "id": "608050f7634644db3678b1a2",
            "name": "Developer",
            "type": "default",
            "level": "user"
        }
    ],
    ...
}

List groups

There are two types of groups within Qlik Cloud:

• Identity Provider managed groups - these are created by your Identity Provider as users log in, or manually via APIs
• Qlik system groups - these are created and managed by Qlik, and their membership, name, and other properties cannot be updated (for example, the Everyone group, which automatically contains every user in the tenant)

Once you have the ID of a group, you can update it’s roles, assign it to spaces, or use it with section access.

Note: The List Groups endpoint does not return both Identity Provider managed and Qlik system groups at the same time. If you wish to retrieve all groups in the tenant, you will need to make two API calls.

Identity Provider managed groups

To retrieve groups that have been created via API calls or your Identity Provider, you can leverage all available filters on the List Groups endpoint, with systemGroups blank or set to false.

curl --location "https://<TENANT>/api/v1/groups" ^
--header "Authorization: Bearer <ACCESS_TOKEN>" ^
--header "Content-type: application/json"

This will return only the Identity Provider managed groups in the tenant.

Qlik system groups

The same List Groups endpoint can be used to retrieve system groups, but you must set systemGroups to true, and you may not use any other filters with the query.

curl -L "https://<TENANT>/api/v1/groups?systemGroups=true" ^
--header "Authorization: Bearer <ACCESS_TOKEN>" ^
--header "Content-type: application/json"

This will return the system groups, which have present names and IDs that are the same across all tenants. For example, the Everyone group manifests as:

{
    "data": [
        {
            "id": "000000000000000000000001",
            "tenantId": "BL4tTJ4S7xrHTcq0zQxQrJ5qB1_Q6cSo",
            "createdAt": "2023-05-25T07:52:58.816Z",
            "lastUpdatedAt": "2023-05-25T07:52:58.816Z",
            "name": "com.qlik.Everyone",
            "status": "active",
            "assignedRoles": [],
            ...
        }
    ],
    ...
}

Assigning a role to this group will provide that capability to all users in the tenant.

Update roles assigned to a group

This step shows you how to replace any existing group assignments with two new assignments for TenantAdmin and Developer. It is not possible to add or remove individual roles from a group.

curl -L "https://<TENANT>/api/v1/groups/<GROUP_ID>" ^
-X PATCH ^
--header "Authorization: Bearer <ACCESS_TOKEN>" ^
--header "Content-type: application/json" ^
--data "[{\"op\": \"replace\", \"path\": \"/assignedRoles\", \"value\": [ {\"name\": \"TenantAdmin\"}, {\"name\": \"Developer\" }]}]"

The response from this request is an http 204 status code. There are no additional details provided in the response.

Delete a group

You are able to delete Identity Provider managed groups in your tenant, but note that if you have enabled automatic group creation on login, these groups will be recreated the next time a user with that group in their claim logs in.

To delete a group, first retrieve the group ID using the List Groups endpoint, and then call:

curl -L "https://<TENANT>/api/v1/groups/<GROUP_ID>" ^
-X DELETE ^
--header "Authorization: Bearer <ACCESS_TOKEN>" ^
--header "Content-type: application/json"

The response from this request is an http 204 status code. There are no additional details provided in the response.

Delete all groups

You may also need to remove all groups in a tenant to support scenarios such as when your Identity Provider has sent:

• GUIDs rather than friendly group names
• All groups, rather than groups related to Qlik Cloud
• Groups that you need to remove prior to configuring a different Identity Provider

You are going to learn how to use qlik-cli in PowerShell and Application Automation to delete one or more unwanted groups.

# Retrieve the list of groups
$groups=$(qlik group ls --limit 1000) | ConvertFrom-Json

# Write out count of groups returned
Write-Host $groups.count "groups returned."

# Loop over each group if you have more than 0
if ($groups.count -ne 0) {

    $groups | ForEach {

        $group = $_.id
        Write-Host "Deleting group" $_.name
        $deleteResponse=$(qlik group rm $_.id)
    }
} else {
    Write-Host "No groups found."
}

# Retrieve the list of groups
$groups=$(qlik group filter --filter 'name eq ""DeleteMeGroup""' --limit 1000) | ConvertFrom-Json

# Write out count of groups returned
Write-Host $groups.count "groups returned."

# Loop over each group if you have more than 0
if ($groups.count -ne 0) {

    $groups | ForEach {

        $group = $_.id
        Write-Host "Deleting group" $_.name
        $deleteResponse=$(qlik group rm $_.id)
    }
} else {
    Write-Host "No groups found."
}

Delete all groups (no-code)

If you prefer no-code methods, consider leveraging no-code tools such as the Qlik Cloud or Platform Operations connectors in Application Automation.

This example will loop over every group in the tenant running the automation and delete each group as it goes.

To recreate this automation, copy the snippet below and paste it into an automation workspace in edit mode.

{"blocks":[{"id":"890DEEAB-7B43-4A03-BCA0-D5391B8F0CDF","type":"StartBlock","disabled":false,"name":"Start","displayName":"Start","comment":"","childId":"12D0C652-2AE2-4D9B-A5FD-692FFFB0CEBF","inputs":[{"id":"run_mode","value":"manual","type":"select","structure":{}}],"settings":[],"collapsed":[{"name":"loop","isCollapsed":false}],"x":0,"y":0},{"id":"416F1CEE-6226-42ED-9081-4639A939DE94","type":"EndpointBlock","disabled":false,"name":"rawAPIRequest2","displayName":"Qlik Cloud Services - Raw API Request 2","comment":"Call DELETE /api/v1/groups/group-id to delete each group","childId":null,"inputs":[{"id":"4add8960-2078-11ec-be2c-7fc55d771fe6","value":"groups/{$.rawAPIListRequest.item.id}","type":"string","structure":[]},{"id":"3b992a40-2072-11ec-9f0e-ed01586a7e1b","value":"3ba2a970-2072-11ec-be02-2dd5c73abb12","type":"select","displayValue":"DELETE","structure":[]},{"id":"3b8b9090-2072-11ec-8c77-5195fbb0ca65","value":null,"type":"object","mode":"keyValue","structure":[]},{"id":"993585d0-2839-11ec-b431-df4deed6c1ae","value":null,"type":"object","mode":"keyValue","structure":[]}],"settings":[{"id":"blendr_on_error","value":"stop","type":"select","structure":[]},{"id":"cache","value":"0","type":"select","structure":[]}],"collapsed":[{"name":"loop","isCollapsed":false}],"x":526,"y":220,"datasourcetype_guid":"61a87510-c7a3-11ea-95da-0fb0c241e75c","endpoint_guid":"3b75dd80-2072-11ec-9043-3b2aff6123af","endpoint_role":"get"},{"id":"12D0C652-2AE2-4D9B-A5FD-692FFFB0CEBF","type":"EndpointBlock","disabled":false,"name":"rawAPIListRequest","displayName":"Qlik Cloud Services - Raw API List Request","comment":"Call /api/v1/groups to get list of groups","childId":null,"inputs":[{"id":"c3a1c780-2076-11ec-98c4-dd329f9ef682","value":"groups","type":"string","structure":[]},{"id":"c6915fb0-2839-11ec-a450-03c7d8aebbe7","value":null,"type":"object","mode":"keyValue","structure":[]}],"settings":[{"id":"maxitemcount","value":"","type":"string","structure":[]},{"id":"blendr_on_error","value":"stop","type":"select","structure":[]},{"id":"cache","value":"0","type":"select","structure":[]}],"collapsed":[{"name":"loop","isCollapsed":false}],"x":-258,"y":149,"loopBlockId":"416F1CEE-6226-42ED-9081-4639A939DE94","datasourcetype_guid":"61a87510-c7a3-11ea-95da-0fb0c241e75c","endpoint_guid":"4b993580-2072-11ec-8f59-e5aaa8656a36","endpoint_role":"list"}],"variables":[]}