Manage Users and UserGroups Together

Instead of managing the declarative layout for users and user groups individually, you can manage the declarative layout four users and user groups together through the following endpoint:

• /api/v1/layout/usersAndUserGroups

The default hostname for the application endpoint is determined by which edition of GoodData.CN you use:

• GoodData.CN
  https://{organization-hostname}/api/v1/layout/usersAndUserGroups
• GoodData.CN Container Edition
  http://localhost:{port}/api/v1/layout/userAndUserGroups

Where:

• {organization-hostname}
  Specifies the hostname for your organization with GoodData.CN. For example gooddata.com.
• {port}
  Specifies the port to access your installation of GoodData.CN Container Edition. The default port is 3000.

usersAndUserGroups Considerations

GoodData.CN expects all user details to be managed and stored in an external OIDC compatible service. The only details about users that are stored within the GoodData.CN platform are the user ID, the user authentication ID for the OIDC authentication provider, and any groups that the user belongs to. The only details available for the user groups are the identifier and a list of parents (user groups).

Write Operations

The following details must be present in the declarative payload when you issue a PUT request:

• The adminUser that was used to create the bootstrap token for the organization must always be present.
• The authentication identifier (authId) so that users can be authenticated through the OIDC provider.
• The user group that was used to create the bootstrap token for the organization must always be present.

Users and User Groups Layout Document Structure

The following example shows the layout for users and user groups when you issue a GET request to the declarative endpoint. AuthId is replaced by a dummy value.

{
   "userGroups" : [
      {
         "id" : "adminGroup"
      },
      {
         "id" : "develGroup"
      }
   ],
   "users" : [
      {
         "id" : "admin",
         "settings": [
            {
               "id": "timezone",
               "content": {
                  "value": "Europe/Prague"
               }
            }
         ],
         "userGroups" : [
            {
               "id" : "adminGroup",    
               "type" : "userGroup"
            }
         ]
      },
      {
         "authId": "<your-client-id>",
         "email": "<your-email>",
         "firstname": "<your-first-name>",
         "lastname": "<your-last-name>",
         "id" : "test",
         "settings": [
            {
               "id": "timezone",
               "content": {
                  "value": "Europe/Prague"
               }
            }
         ],
         "userGroups" : [
            {
               "id" : "develGroup",
               "type" : "userGroup"
            }
         ]
      }
   ]
}

Backup and Restore Users and User Groups

Here is how you can backup and restore your users and user groups data:

Create a Backup of All Users and User Groups

To back up all users and user groups in your organization:

1. Use the following API call to retrieve the current configuration of the organization:

   curl -H "Authorization: Bearer YWRtaW46Ym9vdHN0cmFwOmFkbWluMTIz" \
   $HOST_URL/api/v1/layout/usersAndUserGroups > usersAndGroups-layout.json
   

   The ouput is stored in a JSON file named usersAndGroups-layout.json.

2. Store the returned JSON output securely as your backup.

Restore a Backup of All Users and User Groups

To restore users and user groups in your organization:

1. Ensure you have the backup JSON of your user data at hand.

2. Use the following API call to restore the organization configuration from your backup:

   curl -H "Authorization: Bearer YWRtaW46Ym9vdHN0cmFwOmFkbWluMTIz" \
   -H "Content-Type: application/json" \
   -X PUT \
   $HOST_URL/api/v1/layout/usersAndUserGroups -d @usersAndGroups-layout.json
   

   Replace usersAndGroups-layout.json with the path to your backup JSON file.