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:
- 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.
- 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.
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 |
End Point |
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} Retain the user ID value. |
API documentation | See the API for adding users to a domain. |
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
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:
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. 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. - 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
Method | POST |
End Point |
https://secure.gooddata.com/gdc/projects/{project_id}/users
|
Response | 200 Ok |
API documentation | See the API for adding users. |
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
Method | POST |
End Point |
https://secure.gooddata.com/gdc/projects/{project_id}/invitations
|
Response | 200 Ok |
API documentation | See the API for inviting users. |
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.