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.

Domain-level provisioning is not available in the GooData Free plan.


Contents:

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

The image illustrates the relationship between projects and domains within the GoodData platform.

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 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.
  2. Execute User Provisioning - After you have built the user provisioning mechanism and tested it, you need to use it to add your users.

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. 

Only the domain administrator can create a user in the domain.

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

  • Method: POST
  • URL: https://secure.gooddata.com/gdc/account/domains/{domain_name}/users
  • Response: 201 Created
    Includes the URI of the newly created user in the following format: /account/profile/{user_id}

Body:

{
  "accountSetting": {
    "login": "{user_login@company.com}",
    "firstName": "{first_name}",
    "lastName": "{last_name}
  }
}

In the request body, specify the following mandatory parameters:

  • login (string in the format of an email address) is the user login. Once created, this property cannot be updated.
    The login must be a string in the format of an email address but does not have to be an actual working email address. You can generate logins from unique user IDs used on your site (for example, 123456@gd.example.com, 234567@gd.example.com, and so on).
    For receiving emails sent by GoodData (such as notifications or scheduled emails), you set the email for each user via the optional email property. A user's email can (but does not have to) be the same as the login. The email does not have to be unique within the domain.
    The login is case-sensitive and must be written in lowercase.

    • Correct: john.doe@example.com

    • Incorrect: John.Doe@example.com

  • firstName (string) is the user's first name.

  • lastName (string) is the user's last name.

For more information about these mandatory parameters and the optional parameters that you can add to the user, see the API for adding users to a domain.

Response:

Adding or Inviting Users to a Project

Domain users cannot access a particular project, unless they are invited or add ed 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

Only a project administrator who is also a domain administrator can add a user to the project via the API.

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 (see the API for obtaining project user roles).

    • Method: GET

    • URL: https://secure.gooddata.com/gdc/projects/{project_id}/roles

    • The response includes the IDs for each user role in the project in the following format: /gdc/projects/{project_id}/roles/{role_id}

  2. Acquire information about the user role that you want to give to the user (see the API for a specific user role).

    • Method: GET

    • URL: https://secure.gooddata.com/gdc/projects/{project_id}/roles/{role_id}

    • The response includes permissions for the specific 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

See the API for adding users.

  • Method: POST
  • URL: https://secure.gooddata.com/gdc/projects/{project_id}/users
  • Response: 200 OK

Body:

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

If you set the user's status to DISABLED, the user cannot access the project after having been added.


Response:

Invite the User to the Project

See the API for inviting users.

  • Method: POST
  • URL: https://secure.gooddata.com/gdc/projects/{project_id}/invitations
  • Response: 200 OK

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.

Powered by Atlassian Confluence and Scroll Viewport.