mirror of
https://github.com/grafana/grafana.git
synced 2025-02-25 18:55:37 -06:00
Service accounts: Update documentation with new changes (#52015)
* Service accounts: Update documentation with new changes * Apply suggestions from code review Co-authored-by: Ieva <ieva.vasiljeva@grafana.com> * Add sections about migration, handle comments Co-authored-by: Ieva <ieva.vasiljeva@grafana.com>
This commit is contained in:
Vardan Torosyan
GitHub
parent
254159ad69
commit
73f4d7ac05
@ -18,7 +18,7 @@ An API key is a randomly generated string that external systems use to interact
|
||||
|
||||
When you create an API key, you specify a **Role** that determines the permissions associated with the API key. Role permissions control that actions the API key can perform on Grafana resources.
|
||||
|
||||
> **Note:** If you use Grafana v8.5 or newer, use service accounts instead of API keys. For more information, refer to [Service accounts]({{< relref "../service-accounts/" >}}).
|
||||
> **Note:** If you use Grafana v8.5 or newer, use service accounts instead of API keys. For more information, refer to [Grafana service accounts]({{< relref "../service-accounts/" >}}).
|
||||
|
||||
{{< section >}}
|
||||
|
||||
@ -30,7 +30,7 @@ This topic shows you how to create an API key using the Grafana UI. You can also
|
||||
|
||||
### Before you begin:
|
||||
|
||||
- Ensure you have permission to create and edit API keys. For more information about permissions, refer to [About users and permissions]({{< relref "../roles-and-permissions/#" >}}).
|
||||
- Ensure you have permission to create and edit API keys. For more information about permissions, refer to [Roles and permissions]({{< relref "../roles-and-permissions/#" >}}).
|
||||
|
||||
**To create an API key:**
|
||||
|
||||
@ -44,3 +44,28 @@ This topic shows you how to create an API key using the Grafana UI. You can also
|
||||
- The maximum length of time is 30 days (one month). You enter a number and a letter. Valid letters include `s` for seconds,`m` for minutes, `h` for hours, `d `for days, `w` for weeks, and `M `for month. For example, `12h` is 12 hours and `1M` is 1 month (30 days).
|
||||
- If you are unsure about how long an API key should be valid, we recommend that you choose a short duration, such as a few hours. This approach limits the risk of having API keys that are valid for a long time.
|
||||
1. Click **Add**.
|
||||
|
||||
## Migrate API Keys to Grafana service accounts
|
||||
|
||||
You can migrate one or all API keys to [Grafana service accounts]({{< relref "../service-accounts/" >}}). When you migrate an API key to a service account, a service account will be created with a service account token.
|
||||
The API key will continue to work, and you can find it in the [Grafana service account tokens]({{< relref "../service-accounts/#service-account-benefits/#service-account-tokens" >}}) details.
|
||||
For more information about benefits of service accounts, refer to [Grafana service account benefits]({{< relref "../service-accounts/#service-account-benefits" >}}).
|
||||
|
||||
You can choose to migrate a single API key or all API keys. Note that when you migrate all API keys, you can't create new API keys anymore and will have to use service accounts instead.
|
||||
|
||||
### Before you begin
|
||||
|
||||
- Ensure you have permission to create Grafana service accounts. For more information about permissions, refer to [Roles and permissions]({{< relref "../roles-and-permissions/#" >}}).
|
||||
|
||||
**To migrate all API keys to service accounts:**
|
||||
|
||||
1. Sign in to Grafana, hover your cursor over **Configuration** (the gear icon), and click **API Keys**.
|
||||
1. In the top of the page, find the section which says **Switch from API keys to service accounts**
|
||||
1. Click **Migrate now**.
|
||||
1. Once migration is successful, you can choose to forever hide the API keys tab and use service accounts from there on. Click **Go to service accounts tab and never show API keys tab again** if you want to do that.
|
||||
|
||||
**To migrate single API key to a service account:**
|
||||
|
||||
1. Sign in to Grafana, hover your cursor over **Configuration** (the gear icon), and click **API Keys**.
|
||||
1. Find the API Key you want to migrate.
|
||||
1. Click **Migrate**.
|
||||
|
||||
@ -17,39 +17,37 @@ In this topic you'll learn how to use the role picker, provisioning, and the HTT
|
||||
|
||||
This section describes how to:
|
||||
|
||||
- Assign a fixed role to a user or team as an organization administrator.
|
||||
- Assign a fixed role to a user, team or service account as an organization administrator.
|
||||
- Assign a fixed role to a user as a server administrator. This approach enables you to assign a fixed role to a user in multiple organizations, without needing to switch organizations.
|
||||
|
||||
In both cases, the assignment applies only to the user or team within the affected organization, and no other organizations. For example, if you grant the user the **Data source editor** role in the **Main** organization, then the user can edit data sources in the **Main** organization, but not in other organizations.
|
||||
|
||||
> **Note:** After you apply your changes, user and team permissions update immediately, and the UI reflects the new permissions the next time they reload their browser or visit another page.
|
||||
In both cases, the assignment applies only to the user, team or service account within the affected organization, and no other organizations. For example, if you grant the user the **Data source editor** role in the **Main** organization, then the user can edit data sources in the **Main** organization, but not in other organizations.
|
||||
|
||||
<br/>
|
||||
|
||||
**Before you begin:**
|
||||
|
||||
- [Plan your RBAC rollout strategy]({{< relref "./plan-rbac-rollout-strategy/" >}}).
|
||||
- Identify the fixed roles that you want to assign to the user or team.
|
||||
- Identify the fixed roles that you want to assign to the user, team or service account.
|
||||
|
||||
For more information about available fixed roles, refer to [RBAC role definitions]({{< relref "./rbac-fixed-basic-role-definitions/" >}}).
|
||||
|
||||
- Ensure that your own user account has the correct permissions:
|
||||
- If you are assigning permissions to a user or team within an organization, you must have organization administrator or server administrator permissions.
|
||||
- If you are assigning permissions to a user, team or service account within an organization, you must have organization administrator or server administrator permissions.
|
||||
- If you are assigning permissions to a user who belongs to multiple organizations, you must have server administrator permissions.
|
||||
- Your Grafana user can also assign fixed role if it has either the `fixed:roles:writer` fixed role assigned to the same organization to which you are assigning RBAC to a user, or a custom role with `users.roles:add` and `users.roles:remove` permissions.
|
||||
- Your own user account must have the roles you are granting. For example, if you would like to grant the `fixed:users:writer` role to a team, you must have that role yourself.
|
||||
|
||||
<br/>
|
||||
|
||||
**To assign a fixed role to a user or team:**
|
||||
**To assign a fixed role to a user, team or service account:**
|
||||
|
||||
1. Sign in to Grafana.
|
||||
2. Switch to the organization that contains the user or team.
|
||||
2. Switch to the organization that contains the user, team or service account.
|
||||
|
||||
For more information about switching organizations, refer to [Switch organizations]({{< relref "../../user-management/user-preferences/_index.md#switch-organizations" >}}).
|
||||
|
||||
3. Hover your cursor over **Configuration** (the gear icon) in the left navigation menu, and click **Users** or **Teams**.
|
||||
4. In the **Role** column, select the fixed role that you want to assign to the user or team.
|
||||
3. Hover your cursor over **Configuration** (the gear icon) in the left navigation menu, and click **Users** or **Teams** or **Service Accounts**.
|
||||
4. In the **Role** column, select the fixed role that you want to assign to the user, team or service account.
|
||||
5. Click **Update**.
|
||||
|
||||
|
||||
|
||||
@ -101,6 +101,12 @@ The following list contains role-based access control actions.
|
||||
| `roles:write` | `permissions:type:delegate` | Create or update a custom role. |
|
||||
| `roles:write` | `permissions:type:escalate` | Reset basic roles to their default permissions. |
|
||||
| `server.stats:read` | n/a | Read Grafana instance statistics. |
|
||||
| `serviceaccounts:write` | `serviceaccounts:*` | Create Grafana service accounts. |
|
||||
| `serviceaccounts:create` | n/a | Update Grafana service accounts. |
|
||||
| `serviceaccounts:delete` | `serviceaccounts:*` | Delete Grafana service accounts. |
|
||||
| `serviceaccounts:read` | `serviceaccounts:*` | Read Grafana service accounts. |
|
||||
| `serviceaccounts.permissions:write` | `serviceaccounts:*` | Update Grafana service account permissions to control who can do what with the service account. |
|
||||
| `serviceaccounts.permissions:read` | `serviceaccounts:*` | Read Grafana service account permissions to see who can do what with the service account. |
|
||||
| `settings:read` | `settings:*`<br>`settings:auth.saml:*`<br>`settings:auth.saml:enabled` (property level) | Read the [Grafana configuration settings]({{< relref "../../../setup-grafana/configure-grafana/" >}}) |
|
||||
| `settings:write` | `settings:*`<br>`settings:auth.saml:*`<br>`settings:auth.saml:enabled` (property level) | Update any Grafana configuration settings that can be [updated at runtime]({{< relref "../../../enterprise/settings-updates/" >}}). |
|
||||
| `status:accesscontrol` | `services:accesscontrol` | Get access-control enabled status. |
|
||||
@ -120,9 +126,9 @@ The following list contains role-based access control actions.
|
||||
| `users.permissions:write` | `global.users:*` <br> `global.users:id:*` | Update a user’s organization-level permissions. |
|
||||
| `users.quotas:read` | `global.users:*` <br> `global.users:id:*` | List a user’s quotas. |
|
||||
| `users.quotas:write` | `global.users:*` <br> `global.users:id:*` | Update a user’s quotas. |
|
||||
| `users.roles:add` | `permissions:type:delegate` | Assign a role to a user. |
|
||||
| `users.roles:read` | `users:*` | List roles assigned directly to a user. |
|
||||
| `users.roles:remove` | `permissions:type:delegate` | Unassign a role from a user. |
|
||||
| `users.roles:add` | `permissions:type:delegate` | Assign a role to a user or a service account. |
|
||||
| `users.roles:read` | `users:*` | List roles assigned directly to a user or a service account. |
|
||||
| `users.roles:remove` | `permissions:type:delegate` | Unassign a role from a user or a service account. |
|
||||
| `users:create` | n/a | Create a user. |
|
||||
| `users:delete` | `global.users:*` <br> `global.users:id:*` | Delete a user. |
|
||||
| `users:disable` | `global.users:*` <br> `global.users:id:*` | Disable a user. |
|
||||
@ -135,21 +141,22 @@ The following list contains role-based access control actions.
|
||||
|
||||
The following list contains role-based access control scopes.
|
||||
|
||||
| Scopes | Descriptions |
|
||||
| ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `annotations:*`<br>`annotations:type:*` | Restrict an action to a set of annotations. For example, `annotations:*` matches any annotation, `annotations:type:dashboard` matches annotations associated with dashboards and `annotations:type:organization` matches organization annotations. |
|
||||
| `apikeys:*`<br>`apikeys:id:*` | Restrict an action to a set of API keys. For example, `apikeys:*` matches any API key, `apikey:id:1` matches the API key whose id is `1`. |
|
||||
| `dashboards:*`<br>`dashboards:uid:*` | Restrict an action to a set of dashboards. For example, `dashboards:*` matches any dashboard, and `dashboards:uid:1` matches the dashboard whose UID is `1`. |
|
||||
| `datasources:*`<br>`datasources:uid:*` | Restrict an action to a set of data sources. For example, `datasources:*` matches any data source, and `datasources:uid:1` matches the data source whose UID is `1`. |
|
||||
| `folders:*`<br>`folders:uid:*` | Restrict an action to a set of folders. For example, `folders:*` matches any folder, and `folders:uid:1` matches the folder whose UID is `1`. |
|
||||
| `global.users:*` <br> `global.users:id:*` | Restrict an action to a set of global users. For example, `global.users:*` matches any user and `global.users:id:1` matches the user whose ID is `1`. |
|
||||
| `orgs:*` <br> `orgs:id:*` | Restrict an action to a set of organizations. For example, `orgs:*` matches any organization and `orgs:id:1` matches the organization whose ID is `1`. |
|
||||
| `permissions:type:delegate` | The scope is only applicable for roles associated with the Access Control itself and indicates that you can delegate your permissions only, or a subset of it, by creating a new role or making an assignment. |
|
||||
| `permissions:type:escalate` | The scope is required to trigger the reset of basic roles permissions. It indicates that users might acquire additional permissions they did not previously have. |
|
||||
| `provisioners:*` | Restrict an action to a set of provisioners. For example, `provisioners:*` matches any provisioner, and `provisioners:accesscontrol` matches the role-based access control [provisioner]({{< relref "./rbac-provisioning/" >}}). |
|
||||
| `reports:*` <br> `reports:id:*` | Restrict an action to a set of reports. For example, `reports:*` matches any report and `reports:id:1` matches the report whose ID is `1`. |
|
||||
| `roles:*` <br> `roles:uid:*` | Restrict an action to a set of roles. For example, `roles:*` matches any role and `roles:uid:randomuid` matches only the role whose UID is `randomuid`. |
|
||||
| `services:accesscontrol` | Restrict an action to target only the role-based access control service. You can use this in conjunction with the `status:accesscontrol` actions. |
|
||||
| `settings:*` | Restrict an action to a subset of settings. For example, `settings:*` matches all settings, `settings:auth.saml:*` matches all SAML settings, and `settings:auth.saml:enabled` matches the enable property on the SAML settings. |
|
||||
| `teams:*` <br> `teams:id:*` | Restrict an action to a set of teams from an organization. For example, `teams:*` matches any team and `teams:id:1` matches the team whose ID is `1`. |
|
||||
| `users:*` <br> `users:id:*` | Restrict an action to a set of users from an organization. For example, `users:*` matches any user and `users:id:1` matches the user whose ID is `1`. |
|
||||
| Scopes | Descriptions |
|
||||
| ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `annotations:*`<br>`annotations:type:*` | Restrict an action to a set of annotations. For example, `annotations:*` matches any annotation, `annotations:type:dashboard` matches annotations associated with dashboards and `annotations:type:organization` matches organization annotations. |
|
||||
| `apikeys:*`<br>`apikeys:id:*` | Restrict an action to a set of API keys. For example, `apikeys:*` matches any API key, `apikey:id:1` matches the API key whose id is `1`. |
|
||||
| `dashboards:*`<br>`dashboards:uid:*` | Restrict an action to a set of dashboards. For example, `dashboards:*` matches any dashboard, and `dashboards:uid:1` matches the dashboard whose UID is `1`. |
|
||||
| `datasources:*`<br>`datasources:uid:*` | Restrict an action to a set of data sources. For example, `datasources:*` matches any data source, and `datasources:uid:1` matches the data source whose UID is `1`. |
|
||||
| `folders:*`<br>`folders:uid:*` | Restrict an action to a set of folders. For example, `folders:*` matches any folder, and `folders:uid:1` matches the folder whose UID is `1`. |
|
||||
| `global.users:*` <br> `global.users:id:*` | Restrict an action to a set of global users. For example, `global.users:*` matches any user and `global.users:id:1` matches the user whose ID is `1`. |
|
||||
| `orgs:*` <br> `orgs:id:*` | Restrict an action to a set of organizations. For example, `orgs:*` matches any organization and `orgs:id:1` matches the organization whose ID is `1`. |
|
||||
| `permissions:type:delegate` | The scope is only applicable for roles associated with the Access Control itself and indicates that you can delegate your permissions only, or a subset of it, by creating a new role or making an assignment. |
|
||||
| `permissions:type:escalate` | The scope is required to trigger the reset of basic roles permissions. It indicates that users might acquire additional permissions they did not previously have. |
|
||||
| `provisioners:*` | Restrict an action to a set of provisioners. For example, `provisioners:*` matches any provisioner, and `provisioners:accesscontrol` matches the role-based access control [provisioner]({{< relref "./rbac-provisioning/" >}}). |
|
||||
| `reports:*` <br> `reports:id:*` | Restrict an action to a set of reports. For example, `reports:*` matches any report and `reports:id:1` matches the report whose ID is `1`. |
|
||||
| `roles:*` <br> `roles:uid:*` | Restrict an action to a set of roles. For example, `roles:*` matches any role and `roles:uid:randomuid` matches only the role whose UID is `randomuid`. |
|
||||
| `services:accesscontrol` | Restrict an action to target only the role-based access control service. You can use this in conjunction with the `status:accesscontrol` actions. |
|
||||
| `serviceaccounts:*` <br> `serviceaccounts:id:*` | Restrict an action to a set of service account from an organization. For example, `serviceaccounts:*` matches any service account and `serviceaccount:id:1` matches the service account whose ID is `1`. |
|
||||
| `settings:*` | Restrict an action to a subset of settings. For example, `settings:*` matches all settings, `settings:auth.saml:*` matches all SAML settings, and `settings:auth.saml:enabled` matches the enable property on the SAML settings. |
|
||||
| `teams:*` <br> `teams:id:*` | Restrict an action to a set of teams from an organization. For example, `teams:*` matches any team and `teams:id:1` matches the team whose ID is `1`. |
|
||||
| `users:*` <br> `users:id:*` | Restrict an action to a set of users from an organization. For example, `users:*` matches any user and `users:id:1` matches the user whose ID is `1`. |
|
||||
|
||||
@ -71,6 +71,9 @@ The following tables list permissions associated with basic and fixed roles.
|
||||
| `fixed:roles:reader` | `roles:read`<br>`teams.roles:read`<br>`users.roles:read`<br>`users.permissions:read` | Read all access control roles, roles and permissions assigned to users, teams. |
|
||||
| `fixed:roles:writer` | All permissions from `fixed:roles:reader` and <br>`roles:write`<br>`roles:delete`<br>`teams.roles:add`<br>`teams.roles:remove`<br>`users.roles:add`<br>`users.roles:remove` | Create, read, update, or delete all roles, assign or unassign roles to users, teams. |
|
||||
| `fixed:roles:resetter` | `roles:write` with scope `permissions:type:escalate` | Reset basic roles to their default. |
|
||||
| `fixed:serviceaccounts:reader` | `serviceaccounts:read` | Read Grafana service accounts. |
|
||||
| `fixed:serviceaccounts:creator` | `serviceaccounts:create` | Create Grafana service accounts. |
|
||||
| `fixed:serviceaccounts:writer` | `serviceaccounts:read`<br>`serviceaccounts:create`<br>`serviceaccounts:write`<br>`serviceaccounts:delete`<br>`serviceaccounts.permissions:read`<br>`serviceaccounts.permissions:write` | Create, update, read and delete all Grafana service accounts and manage service account permissions. |
|
||||
| `fixed:settings:reader` | `settings:read` | Read Grafana instance settings. |
|
||||
| `fixed:settings:writer` | All permissions from `fixed:settings:reader` and<br>`settings:write` | Read and update Grafana instance settings. |
|
||||
| `fixed:stats:reader` | `server.stats:read` | Read Grafana instance statistics. |
|
||||
|
||||
@ -24,7 +24,7 @@ You can use service accounts to run automated or compute workloads.
|
||||
|
||||
A service account can be used to run automated workloads in Grafana, like dashboard provisioning, configuration, or report generation. Create service accounts and tokens to authenticate applications like Terraform with the Grafana API.
|
||||
|
||||
> **Note:** Service accounts are available in Grafana 8.5+ as a beta feature. To enable service accounts, refer to the [Enable service accounts]({{< ref "#enable-service-accounts" >}}) section. Service accounts will eventually replace [API keys]({{< relref "../api-keys/" >}}) as the primary way to authenticate applications that interact with Grafana.
|
||||
> **Note:** Service accounts will eventually replace [API keys]({{< relref "../api-keys/" >}}) as the primary way to authenticate applications that interact with Grafana.
|
||||
|
||||
A common use case for creating a service account is to perform operations on automated or triggered tasks. You can use service accounts to:
|
||||
|
||||
@ -59,47 +59,16 @@ The added benefits of service accounts to API keys include:
|
||||
- Unlike API keys, service account tokens are not associated with a specific user, which means that applications can be authenticated even if a Grafana user is deleted.
|
||||
- You can grant granular permissions to service accounts by leveraging [role-based access control]({{< relref "../roles-and-permissions/access-control/" >}}). For more information about permissions, refer to [About users and permissions]({{< relref "../roles-and-permissions/" >}}).
|
||||
|
||||
## Enable service accounts in Grafana
|
||||
|
||||
Service accounts are available behind the `serviceAccounts` feature toggle, available in Grafana 8.5+.
|
||||
|
||||
You can enable service accounts by:
|
||||
|
||||
- modifying the Grafana configuration file, or
|
||||
- configuring an environment variable
|
||||
|
||||
### Enable service accounts in the Grafana configuration file
|
||||
|
||||
This topic shows you how to enable service accounts by modifying the Grafana configuration file.
|
||||
|
||||
1. Sign in to the Grafana server and locate the configuration file. For more information about finding the configuration file, refer to LINK.
|
||||
2. Open the configuration file and locate the [feature toggles section]({{< relref "../../setup-grafana/configure-grafana/#feature_toggles" >}}). Add `serviceAccounts` as a [feature_toggle]({{< relref "../../setup-grafana/configure-grafana/#feature_toggle" >}}).
|
||||
|
||||
```
|
||||
[feature_toggles]
|
||||
# enable features, separated by spaces
|
||||
enable = serviceAccounts
|
||||
```
|
||||
|
||||
1. Save your changes, Grafana should recognize your changes; in case of any issues we recommend restarting the Grafana server.
|
||||
|
||||
### Enable service accounts with an environment variable
|
||||
|
||||
This topic shows you how to enable service accounts by setting environment variables before starting Grafana.
|
||||
|
||||
Follow the instructions to [override configuration with environment variables]({{< relref "../../setup-grafana/configure-grafana/#override-configuration-with-environment-variables" >}}). Set the following environment variable: `GF_FEATURE_TOGGLES_ENABLE = serviceAccounts`.
|
||||
|
||||
> **Note:** Environment variables override configuration file settings.
|
||||
|
||||
## Create a service account in Grafana
|
||||
|
||||
A service account can be used to run automated workloads in Grafana, like dashboard provisioning, configuration, or report generation. For more information about how you can use service accounts, refer to [About service accounts]({{< ref "#about-service-accounts" >}}).
|
||||
|
||||
For more information about creating service accounts via the API, refer to [Create a service account in the HTTP API]({{< relref "../../developers/http_api/serviceaccount/#create-service-account" >}}).
|
||||
|
||||
Note that the user who created a service account will also be able to read, update and delete the service account that they created, as well as permissions associated with that service account.
|
||||
|
||||
### Before you begin
|
||||
|
||||
- Ensure you have added the feature toggle for service accounts `serviceAccounts`. For more information about adding the feature toggle, refer to [Enable service accounts]({{< ref "#enable-service-accounts" >}}).
|
||||
- Ensure you have permission to create and edit service accounts. By default, the organization administrator role is required to create and edit service accounts. For more information about user permissions, refer to [About users and permissions]({{< relref "../roles-and-permissions/#" >}}).
|
||||
|
||||
### To create a service account
|
||||
@ -121,7 +90,6 @@ You can create a service account token using the Grafana UI or via the API. For
|
||||
|
||||
### Before you begin
|
||||
|
||||
- Ensure you have added the `serviceAccounts` feature toggle to Grafana. For more information about adding the feature toggle, refer to [Enable service accounts]({{< ref "#enable-service-accounts" >}}).
|
||||
- Ensure you have permission to create and edit service accounts. By default, the organization administrator role is required to create and edit service accounts. For more information about user permissions, refer to [About users and permissions]({{< relref "../roles-and-permissions/#" >}}).
|
||||
|
||||
### To add a token to a service account
|
||||
@ -135,3 +103,22 @@ You can create a service account token using the Grafana UI or via the API. For
|
||||
- The expiry date specifies how long you want the key to be valid.
|
||||
- If you are unsure of an expiration date, we recommend that you set the token to expire after a short time, such as a few hours or less. This limits the risk associated with a token that is valid for a long time.
|
||||
1. Click **Generate service account token**.
|
||||
|
||||
## Assign roles to a service account in Grafana
|
||||
|
||||
You can assign roles to a Grafana service account to control access for the associated service account tokens.
|
||||
You can assign roles to a service account using the Grafana UI or via the API. For more information about assigning a role to a service account via the API, refer to [Update service account using the HTTP API]({{< relref "../../developers/http_api/serviceaccount/#update-service-account" >}}).
|
||||
|
||||
In [Grafana Enterprise]({{< relref "../../enterprise/" >}}), you can also [assign RBAC roles]({{< relref "../roles-and-permissions/access-control/assign-rbac-roles" >}}) to grant very specific permissions to applications that interact with Grafana.
|
||||
|
||||
### Before you begin
|
||||
|
||||
- Ensure you have permission to update service accounts permissions. By default, the organization administrator role is required to update service accounts permissions. For more information about user permissions, refer to [About users and permissions]({{< relref "../roles-and-permissions/#" >}}).
|
||||
|
||||
### To assign a role to a service account
|
||||
|
||||
1. Sign in to Grafana, then hover your cursor over **Configuration** (the gear icon) in the sidebar.
|
||||
1. Click **Service accounts**.
|
||||
1. Click the service account to which you want to assign a role. As an alternative, find the service account in the list view,
|
||||
1. Assign a role using the role picker.
|
||||
1. Click **Update**.
|
||||
|
||||
@ -10,9 +10,9 @@ weight: 400
|
||||
|
||||
# Team management
|
||||
|
||||
A team is a group of users within an organization that have common dashboard and data source permission needs. For example, instead of assigning five users access to the same dashboard, you can create a team that consists of those users and assign dashboard permissions to the team. A user can belong to multiple teams.
|
||||
A team is a group of users or service accounts within an organization that have common dashboard and data source permission needs. For example, instead of assigning five users access to the same dashboard, you can create a team that consists of those users and assign dashboard permissions to the team. A user or a service account can belong to multiple teams.
|
||||
|
||||
A user can be a Member or an Administrator for a given team. Members of a team inherit permissions from the team, but they cannot edit the team itself. Team Administrators can add members to a team and update its settings, such as the team name, team member's team roles, UI preferences, and home dashboard.
|
||||
A user or a service account can be a Member or an Administrator for a given team. Members of a team inherit permissions from the team, but they cannot edit the team itself. Team Administrators can add members to a team and update its settings, such as the team name, team member's team roles, UI preferences, and home dashboard.
|
||||
|
||||
For more information about teams, refer to [Teams and permissions]({{< relref "../roles-and-permissions/#teams-and-permissions" >}}).
|
||||
|
||||
@ -39,7 +39,7 @@ A user can belong to multiple teams.
|
||||
|
||||
## Add a team member
|
||||
|
||||
Add a team member to an existing team whenever you want to provide access to team dashboards and folders to another user.
|
||||
Add a team member to an existing team whenever you want to provide access to team dashboards and folders to another user or a service account.
|
||||
|
||||
### Before you begin
|
||||
|
||||
@ -51,7 +51,9 @@ Add a team member to an existing team whenever you want to provide access to tea
|
||||
1. Sign in to Grafana as an organization administrator.
|
||||
1. Hover your cursor over the **Configuration** (gear) icon in the side menu and click **Teams**.
|
||||
1. Click the name of the team to which you want to add members, and click **Add member**.
|
||||
1. In the **Add team member** field, locate and select a user.
|
||||
1. In the **Add team member** field, choose if you want to add a user or a service account.
|
||||
1. Locate and select a user or a service account.
|
||||
1. Choose if you want to add a user or a service account as a team Member or an Admin.
|
||||
1. Click **Add to team**.
|
||||
|
||||
|
||||
@ -69,14 +71,14 @@ Complete this task when you want to add or modify team member permissions.
|
||||
1. Sign in to Grafana as an organization administrator or a team administrator.
|
||||
1. Hover your cursor over the **Configuration** (gear) icon in the side menu and click **Teams**.
|
||||
1. Click the name of the team for which you want to add or modify team member permissions.
|
||||
1. In the team member list, find and click the user account that you want to change. You can use the search field to filter the list if necessary.
|
||||
1. In the team member list, find and click the user or service account that you want to change. You can use the search field to filter the list if necessary.
|
||||
1. Click the **Permission** list, and then click the new user permission level.
|
||||
|
||||
|
||||
|
||||
## Remove a team member
|
||||
|
||||
You can remove a team member when you no longer want to apply team permissions to the user.
|
||||
You can remove a team member when you no longer want to apply team permissions to the user or service account.
|
||||
|
||||
### Before you begin
|
||||
|
||||
@ -86,8 +88,8 @@ You can remove a team member when you no longer want to apply team permissions t
|
||||
|
||||
1. Sign in to Grafana as an organization administrator or team administrator.
|
||||
1. Hover your cursor over the **Configuration** (gear) icon in the side menu and click **Teams**.
|
||||
1. Click a team from which you want to remove a user.
|
||||
1. Click the **X** next to the name of the user.
|
||||
1. Click a team from which you want to remove a user or a service account.
|
||||
1. Click the **X** next to the name of the user or service account.
|
||||
1. Click **Delete**.
|
||||
|
||||
## Delete a team
|
||||
|
||||
@ -747,6 +747,280 @@ Content-Type: application/json; charset=UTF-8
|
||||
| 404 | Role not found. |
|
||||
| 500 | Unexpected error. Refer to body and/or server logs for more details. |
|
||||
|
||||
## Create and remove service account role assignments
|
||||
|
||||
### List roles assigned to a service account
|
||||
|
||||
`GET /api/access-control/users/:serviceAccountId/roles`
|
||||
|
||||
Lists the roles that have been directly assigned to a given service account. The list does not include basic roles (Viewer, Editor, Admin or Grafana Admin), and it does not include roles that have been inherited from a team.
|
||||
|
||||
Query Parameters:
|
||||
|
||||
- `includeHidden`: Optional. Set to `true` to include roles that are `hidden`.
|
||||
|
||||
#### Required permissions
|
||||
|
||||
| Action | Scope |
|
||||
| ---------------- | ------------------------------- |
|
||||
| users.roles:read | users:id:`<service account ID>` |
|
||||
|
||||
#### Example request
|
||||
|
||||
```http
|
||||
GET /api/access-control/users/1/roles
|
||||
Accept: application/json
|
||||
```
|
||||
|
||||
#### Example response
|
||||
|
||||
```http
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: application/json; charset=UTF-8
|
||||
|
||||
[
|
||||
{
|
||||
"version": 4,
|
||||
"uid": "6dNwJq57z",
|
||||
"name": "fixed:reports:writer",
|
||||
"displayName": "Report writer",
|
||||
"description": "Create, read, update, or delete all reports and shared report settings.",
|
||||
"group": "Reports",
|
||||
"updated": "2021-11-19T10:48:00+01:00",
|
||||
"created": "2021-11-19T10:48:00+01:00",
|
||||
"global": false
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
#### Status codes
|
||||
|
||||
| Code | Description |
|
||||
| ---- | -------------------------------------------------------------------- |
|
||||
| 200 | Set of assigned roles is returned. |
|
||||
| 403 | Access denied. |
|
||||
| 500 | Unexpected error. Refer to body and/or server logs for more details. |
|
||||
|
||||
### List permissions assigned to a service account
|
||||
|
||||
`GET /api/access-control/users/:serviceAccountId/permissions`
|
||||
|
||||
Lists the permissions that a given service account has.
|
||||
|
||||
#### Required permissions
|
||||
|
||||
| Action | Scope |
|
||||
| ---------------------- | ------------------------------- |
|
||||
| users.permissions:read | users:id:`<service account ID>` |
|
||||
|
||||
#### Example request
|
||||
|
||||
```http
|
||||
GET /api/access-control/users/1/permissions
|
||||
Accept: application/json
|
||||
```
|
||||
|
||||
#### Example response
|
||||
|
||||
```http
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: application/json; charset=UTF-8
|
||||
|
||||
[
|
||||
{
|
||||
"action": "ldap.status:read",
|
||||
"scope": ""
|
||||
},
|
||||
{
|
||||
"action": "ldap.user:read",
|
||||
"scope": ""
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
#### Status codes
|
||||
|
||||
| Code | Description |
|
||||
| ---- | -------------------------------------------------------------------- |
|
||||
| 200 | Set of assigned permissions is returned. |
|
||||
| 403 | Access denied. |
|
||||
| 500 | Unexpected error. Refer to body and/or server logs for more details. |
|
||||
|
||||
### Add a service account role assignment
|
||||
|
||||
`POST /api/access-control/users/:serviceAccountId/roles`
|
||||
|
||||
Assign a role to a specific service account.
|
||||
|
||||
For bulk updates consider
|
||||
[Set service account role assignments]({{< ref "#set-service-account-role-assignments" >}}).
|
||||
|
||||
#### Required permissions
|
||||
|
||||
`permissions:type:delegate` scope ensures that users can only assign roles which have same, or a subset of permissions which the user has.
|
||||
For example, if a user does not have required permissions for creating users, they won't be able to assign a role which will allow to do that. This is done to prevent escalation of privileges.
|
||||
|
||||
| Action | Scope |
|
||||
| --------------- | ------------------------- |
|
||||
| users.roles:add | permissions:type:delegate |
|
||||
|
||||
#### Example request
|
||||
|
||||
```http
|
||||
POST /api/access-control/users/1/roles
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"global": false,
|
||||
"roleUid": "XvHQJq57z"
|
||||
}
|
||||
```
|
||||
|
||||
#### JSON body schema
|
||||
|
||||
| Field Name | Data Type | Required | Description |
|
||||
| ---------- | --------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| roleUid | string | Yes | UID of the role. |
|
||||
| global | boolean | No | A flag indicating if the assignment is global or not. If set to `false`, the default org ID of the authenticated user will be used from the request to create organization local assignment. |
|
||||
|
||||
#### Example response
|
||||
|
||||
```http
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: application/json; charset=UTF-8
|
||||
|
||||
{
|
||||
"message": "Role added to the user."
|
||||
}
|
||||
```
|
||||
|
||||
#### Status codes
|
||||
|
||||
| Code | Description |
|
||||
| ---- | -------------------------------------------------------------------- |
|
||||
| 200 | Role is assigned to a user. |
|
||||
| 403 | Access denied. |
|
||||
| 404 | Role not found. |
|
||||
| 500 | Unexpected error. Refer to body and/or server logs for more details. |
|
||||
|
||||
## Remove a service account role assignment
|
||||
|
||||
`DELETE /api/access-control/users/:serviceAccountId/roles/:roleUID`
|
||||
|
||||
Revoke a role from a service account.
|
||||
|
||||
For bulk updates consider
|
||||
[Set service account role assignments]({{< ref "#set-service-account-role-assignments" >}}).
|
||||
|
||||
#### Required permissions
|
||||
|
||||
`permissions:type:delegate` scope ensures that users can only unassign roles which have same, or a subset of permissions which the user has.
|
||||
For example, if a user does not have required permissions for creating users, they won't be able to unassign a role which will allow to do that. This is done to prevent escalation of privileges.
|
||||
|
||||
| Action | Scope |
|
||||
| ------------------ | ------------------------- |
|
||||
| users.roles:remove | permissions:type:delegate |
|
||||
|
||||
#### Query parameters
|
||||
|
||||
| Param | Type | Required | Description |
|
||||
| ------ | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| global | boolean | No | A flag indicating if the assignment is global or not. If set to `false`, the default org ID of the authenticated user will be used from the request to remove assignment. |
|
||||
|
||||
#### Example request
|
||||
|
||||
```http
|
||||
DELETE /api/access-control/users/1/roles/AFUXBHKnk
|
||||
Accept: application/json
|
||||
```
|
||||
|
||||
#### Example response
|
||||
|
||||
```http
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: application/json; charset=UTF-8
|
||||
|
||||
{
|
||||
"message": "Role removed from user."
|
||||
}
|
||||
```
|
||||
|
||||
#### Status codes
|
||||
|
||||
| Code | Description |
|
||||
| ---- | -------------------------------------------------------------------- |
|
||||
| 200 | Role is unassigned. |
|
||||
| 403 | Access denied. |
|
||||
| 500 | Unexpected error. Refer to body and/or server logs for more details. |
|
||||
|
||||
### Set service account role assignments
|
||||
|
||||
`PUT /api/access-control/users/:serviceAccountId/roles`
|
||||
|
||||
Update the service accounts's role assignments to match the provided set of UIDs.
|
||||
This will remove any assigned roles that aren't in the request and add
|
||||
roles that are in the set but are not already assigned to the service account.
|
||||
|
||||
If you want to add or remove a single role, consider using
|
||||
[Add a service account role assignment]({{< ref "#add-a-service-account-role-assignment" >}}) or
|
||||
[Remove a service account role assignment]({{< ref "#remove-a-service-account-role-assignment" >}})
|
||||
instead.
|
||||
|
||||
#### Required permissions
|
||||
|
||||
`permissions:type:delegate` scope ensures that users can only assign or unassign roles which have same, or a subset of permissions which the user has.
|
||||
For example, if a user does not have required permissions for creating users, they won't be able to assign or unassign a role which will allow to do that. This is done to prevent escalation of privileges.
|
||||
|
||||
| Action | Scope |
|
||||
| ------------------ | ------------------------- |
|
||||
| users.roles:add | permissions:type:delegate |
|
||||
| users.roles:remove | permissions:type:delegate |
|
||||
|
||||
#### Example request
|
||||
|
||||
```http
|
||||
PUT /api/access-control/users/1/roles
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"global": false,
|
||||
"roleUids": [
|
||||
"ZiHQJq5nk",
|
||||
"GzNQ1357k"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### JSON body schema
|
||||
|
||||
| Field Name | Date Type | Required | Description |
|
||||
| ------------- | --------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| global | boolean | No | A flag indicating if the assignment is global or not. If set to `false`, the default org ID of the authenticated user will be used from the request. |
|
||||
| roleUids | list | Yes | List of role UIDs. |
|
||||
| includeHidden | boolean | No | Specify whether the hidden role assignments should be updated. |
|
||||
|
||||
#### Example response
|
||||
|
||||
```http
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: application/json; charset=UTF-8
|
||||
|
||||
{
|
||||
"message": "User roles have been updated."
|
||||
}
|
||||
```
|
||||
|
||||
#### Status codes
|
||||
|
||||
| Code | Description |
|
||||
| ---- | -------------------------------------------------------------------- |
|
||||
| 200 | Roles have been assigned. |
|
||||
| 403 | Access denied. |
|
||||
| 404 | Role not found. |
|
||||
| 500 | Unexpected error. Refer to body and/or server logs for more details. |
|
||||
|
||||
## Create and remove team role assignments
|
||||
|
||||
### List roles assigned to a team
|
||||
|
||||
@ -24,9 +24,9 @@ title: 'Service account HTTP API'
|
||||
|
||||
See note in the [introduction]({{< ref "#service-account-api" >}}) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| -------------------- | ------------------------- |
|
||||
| serviceaccounts:read | global:serviceaccounts:\* |
|
||||
| Action | Scope |
|
||||
| -------------------- | ----- |
|
||||
| serviceaccounts:read | n/a |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
@ -91,9 +91,9 @@ Content-Type: application/json
|
||||
|
||||
See note in the [introduction]({{< ref "#service-account-api" >}}) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| --------------------- | ------------------ |
|
||||
| serviceaccounts:write | serviceaccounts:\* |
|
||||
| Action | Scope |
|
||||
| ---------------------- | ----- |
|
||||
| serviceaccounts:create | n/a |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user