public/grafana
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

PackageJson: Prettify markdown/mdx on commit with lint-staged (#37616)

Browse Source 
* Format md,mdx files with prettier on lint-staged

* Manually run prettier on docs/sources
This commit is contained in:
Connor Lindsey
2021-08-06 07:52:36 -06:00
committed by GitHub
parent e9c032f10f
commit b78a67cec7
301 changed files with 3216 additions and 2980 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/sources/enterprise/access-control/_index.md
+1 -1
View File
@@ -9,7 +9,7 @@ weight = 100
> **Note:** Fine-grained access control is in beta, and you can expect changes in future releases.
Fine-grained access control provides a standardized way of granting, changing, and revoking access when it comes to viewing and modifying Grafana resources, such as users and reports.
Fine-grained access control provides a standardized way of granting, changing, and revoking access when it comes to viewing and modifying Grafana resources, such as users and reports.
Fine-grained access control works alongside the current [Grafana permissions]({{< relref "../../permissions/_index.md" >}}), and it allows you granular control of users’ actions.
To learn more about how fine-grained access control works, refer to [Roles]({{< relref "./roles.md" >}}) and [Permissions]({{< relref "./permissions.md" >}}).
docs/sources/enterprise/access-control/fine-grained-access-control-references.md
+22 -21
View File
@@ -6,31 +6,32 @@ weight = 130
+++
# Fine-grained access control references
The reference information that follows complements conceptual information about [Roles]({{< relref "./roles.md" >}}).
## Fine-grained access fixed roles
Fixed roles | Permissions | Descriptions
--- | --- | ---
`fixed:permissions:admin:read` | `roles:read`<br>`roles:list`<br>`roles.builtin:list` | Allows to list and get available roles and built-in role assignments.
`fixed:permissions:admin:edit` | All permissions from `fixed:permissions:admin:read` and <br>`roles:write`<br>`roles:delete`<br>`roles.builtin:add`<br>`roles.builtin:remove` | Allows every read action and in addition allows to create, change and delete custom roles and create or remove built-in role assignments.
`fixed:reporting:admin:read` | `reports:read`<br>`reports:send`<br>`reports.settings:read` | Allows to read reports and report settings.
`fixed:reporting:admin:edit` | All permissions from `fixed:reporting:admin:read` and <br>`reports.admin:write`<br>`reports:delete`<br>`reports.settings:write` | Allows every read action for reports and in addition allows to administer reports.
`fixed:users:admin:read` | `users.authtoken:list`<br>`users.quotas:list`<br>`users:read`<br>`users.teams:read` | Allows to list and get users and related information.
`fixed:users:admin:edit` | All permissions from `fixed:users:admin:read` and <br>`users.password:update`<br>`users:write`<br>`users:create`<br>`users:delete`<br>`users:enable`<br>`users:disable`<br>`users.permissions:update`<br>`users:logout`<br>`users.authtoken:update`<br>`users.quotas:update` | Allows every read action for users and in addition allows to administer users.
`fixed:users:org:read` | `org.users:read` | Allows to get user organizations.
`fixed:users:org:edit` | All permissions from `fixed:users:org:read` and <br>`org.users:add`<br>`org.users:remove`<br>`org.users.role:update` | Allows every read action for user organizations and in addition allows to administer user organizations.
`fixed:ldap:admin:read` | `ldap.user:read`<br>`ldap.status:read` | Allows to read LDAP information and status.
`fixed:ldap:admin:edit` | All permissions from `fixed:ldap:admin:read` and <br>`ldap.user:sync`<br>`ldap.config:reload` | Allows every read action for LDAP and in addition allows to administer LDAP.
`fixed:server:admin:read` | `server.stats:read` | Read server stats
`fixed:settings:admin:read` | `settings:read` | Read settings
`fixed:settings:admin:edit` | All permissions from `fixed:settings:admin:read` and<br>`settings:write` | Update settings
`fixed:datasource:editor:read` | `datasources:explore` | Explore datasources
| Fixed roles | Permissions | Descriptions |
| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `fixed:permissions:admin:read` | `roles:read`<br>`roles:list`<br>`roles.builtin:list` | Allows to list and get available roles and built-in role assignments. |
| `fixed:permissions:admin:edit` | All permissions from `fixed:permissions:admin:read` and <br>`roles:write`<br>`roles:delete`<br>`roles.builtin:add`<br>`roles.builtin:remove` | Allows every read action and in addition allows to create, change and delete custom roles and create or remove built-in role assignments. |
| `fixed:reporting:admin:read` | `reports:read`<br>`reports:send`<br>`reports.settings:read` | Allows to read reports and report settings. |
| `fixed:reporting:admin:edit` | All permissions from `fixed:reporting:admin:read` and <br>`reports.admin:write`<br>`reports:delete`<br>`reports.settings:write` | Allows every read action for reports and in addition allows to administer reports. |
| `fixed:users:admin:read` | `users.authtoken:list`<br>`users.quotas:list`<br>`users:read`<br>`users.teams:read` | Allows to list and get users and related information. |
| `fixed:users:admin:edit` | All permissions from `fixed:users:admin:read` and <br>`users.password:update`<br>`users:write`<br>`users:create`<br>`users:delete`<br>`users:enable`<br>`users:disable`<br>`users.permissions:update`<br>`users:logout`<br>`users.authtoken:update`<br>`users.quotas:update` | Allows every read action for users and in addition allows to administer users. |
| `fixed:users:org:read` | `org.users:read` | Allows to get user organizations. |
| `fixed:users:org:edit` | All permissions from `fixed:users:org:read` and <br>`org.users:add`<br>`org.users:remove`<br>`org.users.role:update` | Allows every read action for user organizations and in addition allows to administer user organizations. |
| `fixed:ldap:admin:read` | `ldap.user:read`<br>`ldap.status:read` | Allows to read LDAP information and status. |
| `fixed:ldap:admin:edit` | All permissions from `fixed:ldap:admin:read` and <br>`ldap.user:sync`<br>`ldap.config:reload` | Allows every read action for LDAP and in addition allows to administer LDAP. |
| `fixed:server:admin:read` | `server.stats:read` | Read server stats |
| `fixed:settings:admin:read` | `settings:read` | Read settings |
| `fixed:settings:admin:edit` | All permissions from `fixed:settings:admin:read` and<br>`settings:write` | Update settings |
| `fixed:datasource:editor:read` | `datasources:explore` | Explore datasources |
## Default built-in role assignments
Built-in roles | Associated roles | Descriptions
--- | --- | ---
Grafana Admin | `fixed:permissions:admin:edit`<br>`fixed:permissions:admin:read`<br>`fixed:reporting:admin:edit`<br>`fixed:reporting:admin:read`<br>`fixed:users:admin:edit`<br>`fixed:users:admin:read`<br>`fixed:users:org:edit`<br>`fixed:users:org:read`<br>`fixed:ldap:admin:edit`<br>`fixed:ldap:admin:read`<br>`fixed:server:admin:read`<br>`fixed:settings:admin:read`<br>`fixed:settings:admin:edit` | Allows access to resources which [Grafana Server Admin]({{< relref "../../permissions/_index.md#grafana-server-admin-role" >}}) has permissions by default.
Admin | `fixed:users:org:edit`<br>`fixed:users:org:read`<br>`fixed:reporting:admin:edit`<br>`fixed:reporting:admin:read` | Allows access to resource which [Admin]({{< relref "../../permissions/organization_roles.md" >}}) has permissions by default.
Editor | `fixed:datasource:editor:read`
| Built-in roles | Associated roles | Descriptions |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Grafana Admin | `fixed:permissions:admin:edit`<br>`fixed:permissions:admin:read`<br>`fixed:reporting:admin:edit`<br>`fixed:reporting:admin:read`<br>`fixed:users:admin:edit`<br>`fixed:users:admin:read`<br>`fixed:users:org:edit`<br>`fixed:users:org:read`<br>`fixed:ldap:admin:edit`<br>`fixed:ldap:admin:read`<br>`fixed:server:admin:read`<br>`fixed:settings:admin:read`<br>`fixed:settings:admin:edit` | Allows access to resources which [Grafana Server Admin]({{< relref "../../permissions/_index.md#grafana-server-admin-role" >}}) has permissions by default. |
| Admin | `fixed:users:org:edit`<br>`fixed:users:org:read`<br>`fixed:reporting:admin:edit`<br>`fixed:reporting:admin:read` | Allows access to resource which [Admin]({{< relref "../../permissions/organization_roles.md" >}}) has permissions by default. |
| Editor | `fixed:datasource:editor:read` |
docs/sources/enterprise/access-control/permissions.md
+54 -54
View File
@@ -9,7 +9,7 @@ weight = 115
A permission is an action and a scope. When creating a fine-grained access control, consider what specific action a user should be allowed to perform, and on what resources (its scope).
To grant permissions to a user, you create a built-in role assignment to map a role to a built-in role. A built-in role assignment *modifies* to one of the existing built-in roles in Grafana (Viewer, Editor, Admin). For more information, refer to [Built-in role assignments]({{< relref "./roles.md#built-in-role-assignments" >}}).
To grant permissions to a user, you create a built-in role assignment to map a role to a built-in role. A built-in role assignment _modifies_ to one of the existing built-in roles in Grafana (Viewer, Editor, Admin). For more information, refer to [Built-in role assignments]({{< relref "./roles.md#built-in-role-assignments" >}}).
To learn more about which permissions are used for which resources, refer to [Resources with fine-grained permissions]({{< relref "./_index.md#resources-with-fine-grained-permissions" >}}).
@@ -23,61 +23,61 @@ scope
The following list contains fine-grained access control actions.
Actions | Applicable scopes | Descriptions
--- | --- | ---
`roles:list` | `roles:*` | List available roles without permissions.
`roles:read` | `roles:*` | Read a specific role with it's permissions.
`roles:write` | `permissions:delegate` | Create or update a custom role.
`roles:delete` | `permissions:delegate` | Delete a custom role.
`roles.builtin:list` | `roles:*` | List built-in role assignments.
`roles.builtin:add` | `permissions:delegate` | Create a built-in role assignment.
`roles.builtin:remove` | `permissions:delegate` | Delete a built-in role assignment.
`reports.admin:create` | `reports:*` | Create reports.
`reports.admin:write` | `reports:*` | Update reports.
`reports:delete` | `reports:*` | Delete reports.
`reports:read` | `reports:*` | List all available reports or get a specific report.
`reports:send` | `reports:*` | Send a report email.
`reports.settings:write` | n/a | Update report settings.
`reports.settings:read` | n/a | Read report settings.
`provisioning:reload` | `service:accesscontrol` | Reload provisioning files.
`users:read` | `global:users:*` | Read or search user profiles.
`users:write` | `global:users:*` | Update a user’s profile.
`users.teams:read` | `global:users:*` | Read a user’s teams.
`users.authtoken:list` | `global:users:*` | List authentication tokens that are assigned to a user.
`users.authtoken:update` | `global:users:*` | Update authentication tokens that are assigned to a user.
`users.password:update` | `global:users:*` | Update a user’s password.
`users:delete` | `global:users:*` | Delete a user.
`users:create` | n/a | Create a user.
`users:enable` | `global:users:*` | Enable a user.
`users:disable` | `global:users:*` | Disable a user.
`users.permissions:update` | `global:users:*` | Update a user’s organization-level permissions.
`users:logout` | `global:users:*` | Log out a user.
`users.quotas:list` | `global:users:*` | List a user’s quotas.
`users.quotas:update` | `global:users:*` | Update a user’s quotas.
`org.users.read` | `users:*` | Get user profiles within an organization.
`org.users.add` | `users:*` | Add a user to an organization.
`org.users.remove` | `users:*` | Remove a user from an organization.
`org.users.role:update` | `users:*` | Update the organization role (`Viewer`, `Editor`, `Admin`) for an organization.
`ldap.user:read` | n/a | Get a user via LDAP.
`ldap.user:sync` | n/a | Sync a user via LDAP.
`ldap.status:read` | n/a | Verify the LDAP servers’ availability.
`ldap.config:reload` | n/a | Reload the LDAP configuration.
`status:accesscontrol` | `service:accesscontrol` | Get access-control enabled status.
`settings:read` | `settings:**`<br>`settings:auth.saml:*`<br>`settings:auth.saml:enabled` (property level) | Read settings
`settings:write` | `settings:**`<br>`settings:auth.saml:*`<br>`settings:auth.saml:enabled` (property level) | Update settings
`server.stats:read` | n/a | Read server stats
`datasources:explore` | n/a | Enable explore
| Actions | Applicable scopes | Descriptions |
| -------------------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| `roles:list` | `roles:*` | List available roles without permissions. |
| `roles:read` | `roles:*` | Read a specific role with it's permissions. |
| `roles:write` | `permissions:delegate` | Create or update a custom role. |
| `roles:delete` | `permissions:delegate` | Delete a custom role. |
| `roles.builtin:list` | `roles:*` | List built-in role assignments. |
| `roles.builtin:add` | `permissions:delegate` | Create a built-in role assignment. |
| `roles.builtin:remove` | `permissions:delegate` | Delete a built-in role assignment. |
| `reports.admin:create` | `reports:*` | Create reports. |
| `reports.admin:write` | `reports:*` | Update reports. |
| `reports:delete` | `reports:*` | Delete reports. |
| `reports:read` | `reports:*` | List all available reports or get a specific report. |
| `reports:send` | `reports:*` | Send a report email. |
| `reports.settings:write` | n/a | Update report settings. |
| `reports.settings:read` | n/a | Read report settings. |
| `provisioning:reload` | `service:accesscontrol` | Reload provisioning files. |
| `users:read` | `global:users:*` | Read or search user profiles. |
| `users:write` | `global:users:*` | Update a user’s profile. |
| `users.teams:read` | `global:users:*` | Read a user’s teams. |
| `users.authtoken:list` | `global:users:*` | List authentication tokens that are assigned to a user. |
| `users.authtoken:update` | `global:users:*` | Update authentication tokens that are assigned to a user. |
| `users.password:update` | `global:users:*` | Update a user’s password. |
| `users:delete` | `global:users:*` | Delete a user. |
| `users:create` | n/a | Create a user. |
| `users:enable` | `global:users:*` | Enable a user. |
| `users:disable` | `global:users:*` | Disable a user. |
| `users.permissions:update` | `global:users:*` | Update a user’s organization-level permissions. |
| `users:logout` | `global:users:*` | Log out a user. |
| `users.quotas:list` | `global:users:*` | List a user’s quotas. |
| `users.quotas:update` | `global:users:*` | Update a user’s quotas. |
| `org.users.read` | `users:*` | Get user profiles within an organization. |
| `org.users.add` | `users:*` | Add a user to an organization. |
| `org.users.remove` | `users:*` | Remove a user from an organization. |
| `org.users.role:update` | `users:*` | Update the organization role (`Viewer`, `Editor`, `Admin`) for an organization. |
| `ldap.user:read` | n/a | Get a user via LDAP. |
| `ldap.user:sync` | n/a | Sync a user via LDAP. |
| `ldap.status:read` | n/a | Verify the LDAP servers’ availability. |
| `ldap.config:reload` | n/a | Reload the LDAP configuration. |
| `status:accesscontrol` | `service:accesscontrol` | Get access-control enabled status. |
| `settings:read` | `settings:**`<br>`settings:auth.saml:*`<br>`settings:auth.saml:enabled` (property level) | Read settings |
| `settings:write` | `settings:**`<br>`settings:auth.saml:*`<br>`settings:auth.saml:enabled` (property level) | Update settings |
| `server.stats:read` | n/a | Read server stats |
| `datasources:explore` | n/a | Enable explore |
## Scope definitions
The following list contains fine-grained access control scopes.
Scopes | Descriptions
--- | ---
`roles:*` | Restrict an action to a set of roles. For example, `roles:*` matches any role, `roles:randomuid` matches only the role with UID `randomuid` and `roles:custom:reports:{editor,viewer}` matches both `custom:reports:editor` and `custom:reports:viewer` roles.
`permissions: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.
`reports:*` | Restrict an action to a set of reports. For example, `reports:*` matches any report and `reports:1` matches the report with id `1`.
`service:accesscontrol` | Restrict an action to target only the fine-grained access control service. For example, you can use this in conjunction with the `provisioning:reload` or the `status:accesscontrol` actions.
`global:users:*` | Restrict an action to a set of global users.
`users:*` | Restrict an action to a set of users from an organization.
`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.
| Scopes | Descriptions |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `roles:*` | Restrict an action to a set of roles. For example, `roles:*` matches any role, `roles:randomuid` matches only the role with UID `randomuid` and `roles:custom:reports:{editor,viewer}` matches both `custom:reports:editor` and `custom:reports:viewer` roles. |
| `permissions: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. |
| `reports:*` | Restrict an action to a set of reports. For example, `reports:*` matches any report and `reports:1` matches the report with id `1`. |
| `service:accesscontrol` | Restrict an action to target only the fine-grained access control service. For example, you can use this in conjunction with the `provisioning:reload` or the `status:accesscontrol` actions. |
| `global:users:*` | Restrict an action to a set of global users. |
| `users:*` | Restrict an action to a set of users from an organization. |
| `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. |
docs/sources/enterprise/access-control/provisioning.md
+65 -62
View File
@@ -6,7 +6,7 @@ weight = 120
+++
# Provisioning
You can create, change or remove [Custom roles]({{< relref "./roles.md#custom-roles" >}}) and create or remove [built-in role assignments]({{< relref "./roles.md#built-in-role-assignments" >}}), by adding one or more YAML configuration files in the [`provisioning/access-control/`]({{< relref "../../administration/configuration/#provisioning" >}}) directory.
Refer to [Grafana provisioning]({{< relref "../../administration/configuration/#provisioning" >}}) to learn more about provisioning.
@@ -38,16 +38,16 @@ apiVersion: 1
# Roles to insert into the database, or roles to update in the database
roles:
- name: custom:users:editor
description: "This role allows users to list, create, or update other users within the organization."
description: 'This role allows users to list, create, or update other users within the organization.'
version: 1
orgId: 1
permissions:
- action: "users:read"
scope: "users:*"
- action: "users:write"
scope: "users:*"
- action: "users:create"
scope: "users:*"
- action: 'users:read'
scope: 'users:*'
- action: 'users:write'
scope: 'users:*'
- action: 'users:create'
scope: 'users:*'
```
Here is an example YAML file to create a global role with a set of permissions, where the `global:true` option makes a role global:
@@ -59,26 +59,28 @@ apiVersion: 1
# Roles to insert into the database, or roles to update in the database
roles:
- name: custom:users:editor
description: "This role allows users to list, create, or update other users within the organization."
description: 'This role allows users to list, create, or update other users within the organization.'
version: 1
global: true
permissions:
- action: "users:read"
scope: "users:*"
- action: "users:write"
scope: "users:*"
- action: "users:create"
scope: "users:*"
- action: 'users:read'
scope: 'users:*'
- action: 'users:write'
scope: 'users:*'
- action: 'users:create'
scope: 'users:*'
```
The `orgId` is lost when the role is set to global.
### Delete roles
### Delete roles
To delete a role, add a list of roles under the `deleteRoles` section in the configuration file.
To delete a role, add a list of roles under the `deleteRoles` section in the configuration file.
> **Note:** Any role in the `deleteRoles` section is deleted before any role in the `roles` section is saved.
Here is an example YAML file to delete a role:
```yaml
# config file version
apiVersion: 1
@@ -105,19 +107,19 @@ apiVersion: 1
# Roles to insert/update in the database
roles:
- name: custom:users:editor
description: "This role allows users to list/create/update other users in the organization"
description: 'This role allows users to list/create/update other users in the organization'
version: 1
orgId: 1
permissions:
- action: "users:read"
scope: "users:*"
- action: "users:write"
scope: "users:*"
- action: "users:create"
scope: "users:*"
- action: 'users:read'
scope: 'users:*'
- action: 'users:write'
scope: 'users:*'
- action: 'users:create'
scope: 'users:*'
builtInRoles:
- name: "Editor"
- name: "Admin"
- name: 'Editor'
- name: 'Admin'
```
## Manage default built-in role assignments
@@ -129,15 +131,15 @@ During startup, Grafana creates [default built-in role assignments]({{< relref "
To remove default built-in role assignments, use the `removeDefaultAssignments` element in the configuration file. You need to provide the built-in role name and fixed role name.
Here is an example:
```yaml
# config file version
apiVersion: 1
# list of default built-in role assignments that should be removed
removeDefaultAssignments:
- builtInRole: "Grafana Admin"
fixedRole: "fixed:permissions:admin"
- builtInRole: 'Grafana Admin'
fixedRole: 'fixed:permissions:admin'
```
### Restore default assignment
@@ -145,14 +147,15 @@ removeDefaultAssignments:
To restore the default built-in role assignment, use the `addDefaultAssignments` element in the configuration file. You need to provide the built-in role name and the fixed-role name.
Here is an example:
```yaml
# config file version
apiVersion: 1
# list of default built-in role assignments that should be added back
addDefaultAssignments:
- builtInRole: "Admin"
fixedRole: "fixed:reporting:admin:read"
- builtInRole: 'Admin'
fixedRole: 'fixed:reporting:admin:read'
```
## Full example of a role configuration file
@@ -164,29 +167,29 @@ apiVersion: 1
# list of default built-in role assignments that should be removed
removeDefaultAssignments:
# <string>, must be one of the Organization roles (`Viewer`, `Editor`, `Admin`) or `Grafana Admin`
- builtInRole: "Grafana Admin"
- builtInRole: 'Grafana Admin'
# <string>, must be one of the existing fixed roles
fixedRole: "fixed:permissions:admin"
fixedRole: 'fixed:permissions:admin'
# list of default built-in role assignments that should be added back
addDefaultAssignments:
# <string>, must be one of the Organization roles (`Viewer`, `Editor`, `Admin`) or `Grafana Admin`
- builtInRole: "Admin"
- builtInRole: 'Admin'
# <string>, must be one of the existing fixed roles
fixedRole: "fixed:reporting:admin:read"
fixedRole: 'fixed:reporting:admin:read'
# list of roles that should be deleted
deleteRoles:
# <string> name of the role you want to create. Required if no uid is set
- name: "custom:reports:editor"
- name: 'custom:reports:editor'
# <string> uid of the role. Required if no name
uid: "customreportseditor1"
uid: 'customreportseditor1'
# <int> org id. will default to Grafana's default if not specified
orgId: 1
# <bool> force deletion revoking all grants of the role
force: true
- name: "custom:global:reports:reader"
uid: "customglobalreportsreader1"
- name: 'custom:global:reports:reader'
uid: 'customglobalreportsreader1'
# <bool> overwrite org id and removes a global role
global: true
force: true
@@ -194,44 +197,44 @@ deleteRoles:
# list of roles to insert/update depending on what is available in the database
roles:
# <string, required> name of the role you want to create. Required
- name: "custom:users:editor"
- name: 'custom:users:editor'
# <string> uid of the role. Has to be unique for all orgs.
uid: customuserseditor1
# <string> description of the role, informative purpose only.
description: "Role for our custom user editors"
description: 'Role for our custom user editors'
# <int> version of the role, Grafana will update the role when increased
version: 2
# <int> org id. will default to Grafana's default if not specified
orgId: 1
orgId: 1
# <list> list of the permissions granted by this role
permissions:
# <string, required> action allowed
- action: "users:read"
- action: 'users:read'
#<string> scope it applies to
scope: "users:*"
- action: "users:write"
scope: "users:*"
- action: "users:create"
scope: "users:*"
scope: 'users:*'
- action: 'users:write'
scope: 'users:*'
- action: 'users:create'
scope: 'users:*'
# <list> list of builtIn roles the role should be assigned to
builtInRoles:
# <string, required> name of the builtin role you want to assign the role to
- name: "Editor"
- name: 'Editor'
# <int> org id. will default to the role org id
orgId: 1
- name: "custom:global:users:reader"
uid: "customglobalusersreader1"
description: "Global Role for custom user readers"
orgId: 1
- name: 'custom:global:users:reader'
uid: 'customglobalusersreader1'
description: 'Global Role for custom user readers'
version: 1
# <bool> overwrite org id and creates a global role
global: true
permissions:
- action: "users:read"
scope: "users:*"
- action: 'users:read'
scope: 'users:*'
builtInRoles:
- name: "Viewer"
orgId: 1
- name: "Editor"
- name: 'Viewer'
orgId: 1
- name: 'Editor'
# <bool> overwrite org id and assign role globally
global: true
```
@@ -251,7 +254,7 @@ A basic set of validation rules are applied to the input `yaml` files.
### Roles
- `name` must not be empty
- `name` must not have `fixed:` prefix.
- `name` must not have `fixed:` prefix.
### Permissions
@@ -259,9 +262,9 @@ A basic set of validation rules are applied to the input `yaml` files.
### Built-in role assignments
- `name` must be one of the Organization roles (`Viewer`, `Editor`, `Admin`) or `Grafana Admin`.
- `name` must be one of the Organization roles (`Viewer`, `Editor`, `Admin`) or `Grafana Admin`.
- When `orgId` is not specified, it inherits the `orgId` from `role`. For global roles the default `orgId` is used.
- `orgId` in the `role` and in the assignment must be the same for none global roles.
- `orgId` in the `role` and in the assignment must be the same for none global roles.
### Role deletion
docs/sources/enterprise/access-control/roles.md
+4 -3
View File
@@ -10,6 +10,7 @@ weight = 105
A role represents set of permissions that allow you to perform specific actions on Grafana resources. Refer to [Permissions]({{< relref "./permissions.md" >}}) to understand how permissions work.
There are two types of roles:
- [Fixed roles]({{< relref "./roles.md#fixed-roles" >}}), which provide granular access for specific resources within Grafana and are managed by the Grafana itself.
- [Custom roles]({{< relref "./roles.md#custom-roles.md" >}}), which provide granular access based on the user specified set of permissions.
@@ -25,7 +26,7 @@ Fixed roles provide convenience and guarantee of consistent behaviour by combini
There are few basic rules for fixed roles:
- All fixed roles are _global_.
- All fixed roles have a `fixed:` prefix.
- All fixed roles have a `fixed:` prefix.
- You can’t change or delete a fixed role.
For more information, refer to [Fine-grained access control references]({{< relref "./fine-grained-access-control-references.md#fine-grained-access-fixed-roles" >}}).
@@ -68,7 +69,7 @@ Note that you won't be able to create, update or delete a custom role with permi
## Built-in role assignments
To control what your users can access or not, you can assign or unassign [Custom roles]({{< ref "#custom-roles" >}}) or [Fixed roles]({{< ref "#fixed-roles" >}}) to the existing [Organization roles]({{< relref "../../permissions/organization_roles.md" >}}) or to [Grafana Server Admin]({{< relref "../../permissions/_index.md#grafana-server-admin-role" >}}) role.
To control what your users can access or not, you can assign or unassign [Custom roles]({{< ref "#custom-roles" >}}) or [Fixed roles]({{< ref "#fixed-roles" >}}) to the existing [Organization roles]({{< relref "../../permissions/organization_roles.md" >}}) or to [Grafana Server Admin]({{< relref "../../permissions/_index.md#grafana-server-admin-role" >}}) role.
These assignments are called built-in role assignments.
During startup, Grafana will create default assignments for you. When you make any changes to the built-on role assignments, Grafana will take them into account and won’t overwrite during next start.
@@ -82,4 +83,4 @@ You can create or remove built-in role assignments using [Fine-grained access co
### Scope of assignments
A built-in role assignment can be either _global_ or _organization local_. _Global_ assignments are not mapped to any specific organization and will be applied to all organizations, whereas _organization local_ assignments are only applied for that specific organization.
You can only create _organization local_ assignments for _organization local_ roles.
You can only create _organization local_ assignments for _organization local_ roles.
docs/sources/enterprise/access-control/usage-scenarios.md
+13 -10
View File
@@ -13,15 +13,17 @@ Before you get started, make sure to [enable fine-grained access control]({{< re
## Check all built-in role assignments
You can use the [Fine-grained access control HTTP API]({{< relref "../../http_api/access_control.md#get-all-built-in-role-assignments" >}}) to see all available built-in role assignments.
You can use the [Fine-grained access control HTTP API]({{< relref "../../http_api/access_control.md#get-all-built-in-role-assignments" >}}) to see all available built-in role assignments.
The response contains a mapping between one of the organization roles (`Viewer`, `Editor`, `Admin`) or `Grafana Admin` to the custom or fixed roles.
Example request:
```
curl --location --request GET '<grafana_url>/api/access-control/builtin-roles' --header 'Authorization: Basic YWRtaW46cGFzc3dvcmQ='
```
Example response:
```
{
"Admin": [
@@ -34,7 +36,7 @@ Example response:
"global": true,
"updated": "2021-05-17T20:49:18+02:00",
"created": "2021-05-13T16:24:26+02:00"
},
},
{
"version": 1,
"uid": "Kz9m_YjGz",
@@ -56,7 +58,7 @@ Example response:
"global": true,
"updated": "2021-05-17T20:49:18+02:00",
"created": "2021-05-13T16:24:26+02:00"
},
},
{
"version": 2,
"uid": "ajum_YjGk",
@@ -74,8 +76,8 @@ Example response:
"global": true,
"updated": "2021-05-17T20:49:17+02:00",
"created": "2021-05-13T16:24:26+02:00"
},
...
},
...
]
}
```
@@ -134,6 +136,7 @@ You can create your custom role by either using an [HTTP API]({{< relref "../../
You can take a look at [actions and scopes]({{< relref "./provisioning.md#action-definitions" >}}) to decide what permissions would you like to map to your role.
Example HTTP request:
```
curl --location --request POST '<grafana_url>/api/access-control/roles/' \
--header 'Authorization: Basic YWRtaW46cGFzc3dvcmQ=' \
@@ -163,7 +166,7 @@ Example response:
"global": true,
"permissions": [
{
"action": "users:create"
"action": "users:create"
"updated": "2021-05-17T22:07:31.569936+02:00",
"created": "2021-05-17T22:07:31.569935+02:00"
}
@@ -173,7 +176,7 @@ Example response:
}
```
Once the custom role is created, you can create a built-in role assignment by using an [HTTP API]({{< relref "../../http_api/access_control.md#create-a-built-in-role-assignment" >}}).
Once the custom role is created, you can create a built-in role assignment by using an [HTTP API]({{< relref "../../http_api/access_control.md#create-a-built-in-role-assignment" >}}).
If you created your role using [Grafana provisioning]({{< relref "./provisioning.md" >}}), you can also create the assignment with it.
Example HTTP request:
@@ -212,8 +215,8 @@ In order to create users, you would need to have `users:create` permission. By d
If you want to prevent Grafana Admin from creating users, you can do the following:
1. [Check all built-in role assignments]({{< ref "#check-all-built-in-role-assignments" >}}) to see what built-in role assignments are available.
1. From built-in role assignments, find the role which gives `users:create` permission. Refer to [fixed roles]({{< relref "./roles.md#fixed-roles" >}}) for full list of permission assignments.
1. [Check all built-in role assignments]({{< ref "#check-all-built-in-role-assignments" >}}) to see what built-in role assignments are available.
1. From built-in role assignments, find the role which gives `users:create` permission. Refer to [fixed roles]({{< relref "./roles.md#fixed-roles" >}}) for full list of permission assignments.
1. Remove the built-in role assignment by using an [Fine-grained access control HTTP API]({{< relref "../../http_api/access_control.md" >}}) or by using [Grafana provisioning]({{< relref "./provisioning" >}}).
## Allow Editors to create new custom roles
@@ -223,4 +226,4 @@ By default, Grafana Server Admin is the only user who can create and manage cust
1. First option is to create a built-in role assignment and map `fixed:permissions:admin:edit` and `fixed:permissions:admin:read` fixed roles to the `Editor` built-in role.
1. Second option is to [create a custom role]({{< ref "#create-your-custom-role" >}}) with `roles.builtin:add` and `roles:write` permissions, and create a built-in role assignment for `Editor` organization role.
Note that in any scenario, your `Editor` would be able to create and manage roles only with the permissions they have, or with a subset of them.
Note that in any scenario, your `Editor` would be able to create and manage roles only with the permissions they have, or with a subset of them.