This is an older version of Search Guard. Switch to Latest version
Defining Search Guard Roles
Hint: You can also use the Kibana Confguration GUI for configuring Roles and Permissions.
Search Guard roles are the central place to configure access permissions on:
- Cluster level
- Index level
- Document level
- Field level
- Kibana level
Search Guard roles and their associated permissions are defined in the file sg_roles.yml
. The syntax to define a role is as follows:
_sg_meta:
type: "roles"
config_version: 2
<role_name>:
cluster_permissions:
- '<action group or single permission>'
- ...
index_permissions:
- index_patterns:
- <index pattern the allowed actions should be applied to>
- <index pattern the allowed actions should be applied to>
- ...
allowed_actions:
- '<action group or single permission>'
- ...
dls: '<Document level security query>'
fls:
- '<field level security field>'
- '<field level security field>'
- ...
- index_patterns:
- ...
tenant_permissions:
- tenant_patterns:
- <tenant pattern the allowed actions should be applied to>
- <tenant pattern the allowed actions should be applied to>
- ...
allowed_actions:
- SGS_KIBANA_ALL_WRITE
- tenant_patterns:
- ...
Description
Name | Description |
---|---|
cluster_permissions | Permissions that apply on the cluster level, e.g. monitoring the cluster health |
index_permissions | Permissions that apply to one or more index patterns |
allowed_actions | The actions that are allowed for the index or tenant patterns |
dls | The Document-level security filter query that should be applied to the index patterns. Used to filter documents from the result set. |
fls | The fields that should be exluded or included that should be applied to the index patterns. Used to filter fields from the documents in the result set. |
tenant_permissions | Permissions that apply to Kibana tenants. Used to control access to Kibana. |
Cluster-level permissions
The cluster_permissions
entry is used to define permissions on cluster level. Cluster-level permissions are used to allow/disallow actions that affect either the whole cluster, like querying the cluster health or the nodes stats.
They are also used to allow/disallow actions that affect multiple indices, like mget
, msearch
or bulk
requests.
Example:
sg_finance:
cluster_permissions:
- SGS_CLUSTER_COMPOSITE_OPS
index_permissions:
...
Index-level permissions
The index_permissions
entry is used to allow/disallow actions that affect indices matching the configured index patterns.
For example, to apply READ
permissions on a single index called humanresources
the configuration would look like:
<role_name>:
cluster_permissions:
- ...
index_permissions:
- index_patterns:
- "humanresources"
allowed_actions:
- READ
To apply READ
permissions to two indices called humanresources
and finance
you would write:
<role_name>:
cluster_permissions:
- ...
index_permissions:
- index_patterns:
- "humanresources"
- "finance"
allowed_actions:
- READ
To apply READ
and WRITE
permissions to two indices called humanresources
and finance
you would write:
<role_name>:
cluster_permissions:
- ...
index_permissions:
- index_patterns:
- "humanresources"
- "finance"
allowed_actions:
- READ
- WRITE
Dynamic index patterns: Wildcards and regular expressions
When defining index patterns you can use wildcards and regular expressions:
- An asterisk (
*
) will match any character sequence (or an empty sequence)*my*index
will matchmy_first_index
as well asmyindex
but notmyindex1
.
- A question mark (
?
) will match any single character (but NOT empty character)?kibana
will match.kibana
but notkibana
- Regular expressions have to be enclosed in
/
:'/<java regex>/'
'/\S*/'
will match any non whitespace characters
Example:
<role_name>:
cluster_permissions:
- ...
index_permissions:
- index_patterns:
- "logstash-*"
allowed_actions:
- CRUD
Dynamic index patterns: User name substitution
When defining index patterns the placeholder ${user.name}
is allowed to support indices or aliases which contain the name of the user.
<role_name>:
cluster_permissions:
- ...
index_permissions:
- index_patterns:
- "index-${user_name}"
allowed_actions:
- CRUD
Dynamic index patterns: User attributes
Any authentication and authorization backend can add additional user attributes that you can use for variable substitution.
For Active Directory and LDAP, these are all attributes stored in the user’s Active Directory / LDAP record. For JWT, these are all claims from the JWT token. For the internal user database, they are configured in sg_internalusers.yml.
You can use these attributes in index patterns to implement index-level access control based on user attributes:
- for internal users, the attributes start with
attr_internal_*
- for JWT, the attributes start with
attr_jwt_*
- for LDAP they start with
attr_ldap_*
.
If you’re unsure, what attributes are accessible for the current user you can always check the /_searchguard/authinfo
endpoint. This endpoint will list all attribute names for the currently logged in user.
Internal users Example:
If the internal users entry contains an attribute department
:
jdoe:
hash: ...
attributes:
department: "operations"
You can use this department
attribute to control index access like:
sg_own_index:
cluster_permissions:
- CLUSTER_COMPOSITE_OPS
index_permissions:
- index_patterns:
- '${attr_internal_department}':
allowed_actions:
- SGS_CRUD
In this example, Search Guard grants the SGS_CRUD
permissions to the index operations
for the user jdoe
.
JWT Example:
If the JWT contains a claim department
:
{
"sub": "jdoe"
"name": "John Doe",
"roles": "admin, devops",
"department": "operations"
}
You can use this department
claim to control index access like:
sg_own_index:
cluster_permissions:
- CLUSTER_COMPOSITE_OPS
index_permissions:
- index_patterns:
- '${attr_jwt_department}':
allowed_actions:
- SGS_CRUD
In this example, Search Guard grants the SGS_CRUD
permissions to the index operations
for the user jdoe
.
Active Directory / LDAP Example
If the Active Directory / LDAP entry of the current user contains an attribute department
, you can use it in the same way as as a JWT claim, but with the ldap.
prefix:
sg_own_index:
cluster_permissions:
- CLUSTER_COMPOSITE_OPS
index_permissions:
- index_patterns:
- '${attr_ldap_department}':
allowed_actions:
- SGS_CRUD
In this example, Search Guard grants the SGS_CRUD
permissions to the index operations
.
Multiple Variables
You can use as many variables, wildcards and regular expressions as needed, for example:
sg_own_index:
cluster_permissions:
- CLUSTER_COMPOSITE_OPS
index_permissions:
- index_patterns:
- 'logfiles-${attr_ldap_department}-${user_name}-*':
allowed_actions:
- SGS_CRUD
Built-in Roles
Search Guard ships with the following built-in (static) roles:
Role name | Description |
---|---|
SGS_ALL_ACCESS | All cluster permissions and all index permissions on all indices |
SGS_READALL | Read permissions on all indices, but no write permissions |
SGS_READALL_AND_MONITOR | Read and monitor permissions on all indices, but no write permissions |
SGS_KIBANA_SERVER | Role for the internal Kibana server user, please refer to the Kibana setup chapter for explanation |
SGS_KIBANA_USER | Minimum permission set for regular Kibana users. In addition to this role, you need to also grant READ permissions on indices the user should be able to access in Kibana. |
SGS_LOGSTASH | Role for logstash and beats users, grants full access to all logstash and beats indices. |
SGS_MANAGE_SNAPSHOTS | Grants full permissions on snapshot, restore and repositories operations |
SGS_OWN_INDEX | Grants full permissions on an index named after the authenticated user’s username. |
SGS_XP_MONITORING | Role for X-Pack Monitoring. Users who wish to use X-Pack Monitoring need this role in addition to the sg_kibana_user role |
SGS_XP_ALERTING | Role for X-Pack Alerting. Users who wish to use X-Pack Alerting need this role in addition to the sg_kibana role |
SGS_XP_MACHINE_LEARNING | Role for X-Pack Machine Learning. Users who wish to use X-Pack Machine Learning need this role in addition to the sg_kibana role |