Provisioning Users to Domains and Projects

This article discusses the user provisioning process within the GoodData platform.

User provisioning covers all aspects of creating, updating, and deleting users in your GoodData domain and provisioning them to projects.

Contents:

The following illustration provides the relationship between a domain and a project, and their respective administrators:

For more information about domains, see Your GoodData Domain.

Using GoodData APIs for User Provisioning

GoodData API allows you to automate user provisioning tasks on both the domain and the project level.

Using This process essentially involves two steps:

1. Build User Provisioning - To enable user provisioning within your GoodData domain, you can use scripts provided by GoodData to interact with the GoodData APIs, or you can build your own tools to manage the API calls. For more information, see Powered by GoodData Quick Start - Build User Provisioning.
2. Execute User Provisioning - After you have built the user provisioning mechanism and tested it, you need to use it to add your users. For more information, see Powered by GoodData Quick Start - Execute User Provisioning.

Creating a User in a Domain

Before you can add or invite a user to a project, you must create them in your domain. Domain administrators can create, manage and delete users in a domain. 

When a user is created to the domain, they cannot access data in any of the projects.

Body:

{
  "accountSetting": {
    "login": "{added_user_email@company.com}",
    "password": "{password}",
    "verifyPassword": "{password}",
    "firstName": "{first_name}",
    "lastName": "{last_name}
  }
}

Response:

Adding or Inviting Users to a Project

Domain users cannot access a particular project, unless they are invited or added to that project. The two methods differ in how the user is notified about being added.

• When you add a user to a project, the user is not immediately informed of the access.
• When you invite a user to a project, the user receives an email with a link. When the user clicks the link, they can immediately access the project and its contents.

There are two ways to add a user to project on the GoodData platform.

• You can invite users through the GoodData Portal's user interface.
• You can add or invite users through the GoodData REST APIs.

Project administrators who are not also domain administrators can only invite users to their project.

Adding Users Using Rest APIs

After the user is added to the domain, you can add or invite the user to individual projects.

When you are adding or inviting a user to a project, assign the user a specific user role in the project. A user role defines the permissions available to the assigned user account. For more information, see User Roles.

User roles are referenced by their IDs. These IDs are specific to a project. For each project where you are adding or inviting a user, acquire the user role ID to assign to the user.

Steps:

1. Acquire all user roles from the project.

   Method	GET
   End Point	https://secure.gooddata.com/gdc/projects/{project_id}/roles
   Response	Includes the IDs for each user role in the project in the following format: /gdc/projects/{project_id}/roles/{role_id} Retain the user role ID values.
   API documentation	See the API for obtaining project user roles.

2. Acquire information about the user role that you want to give to the user.

   Method	GET
   End Point	https://secure.gooddata.com/gdc/projects/{project_id}/roles/{role_id }
   Response	Includes permissions for the specific role
   API documentation	See the API for a specific user role.

3. Do one of the following:
   • Add the user: The user is added to the project silently and does not know that access has been provided. This information must be communicated through a different mechanism (for example, inviting the user to the project).
   • Invite the user to the project: The user receives an email invitation and can access the project immediately.

Add the User to the Project

Body:

{
  "user": {
    "content": {
      "status": "ENABLED",
      "userRoles": ["/gdc/projects/{project_id}/roles/{role_id}"]
    },
    "links": {
      "self": "/gdc/account/profile/{user_id}"
    }
  }
}

Invite the User to the Project

Body:

{
  "invitations": [
    {
      "invitation": {
        "content": {
          "email": "{invited-user-email@company.com}",
          "userFilters": [ "/gdc/md/{project_id}/obj/{filter_object_id}" ], 
          "role": "/gdc/projects/{project_id}/roles/{role_id}",
          "firstname": "{first_name}",
          "lastname": "{last_name}",
          "action": {
            "setMessage": "{message_for_invited_user}"
          }
        }
      }
    }
  ]
}

Response:

User roles

When a user is added to a project, the user must be assigned a role within the project. For more information, see User Roles.