This is an older version of Search Guard. Switch to Latest version
Defining Roles and permissions
Content
Hint: You can also use the Kibana Confguration GUI for configuring Roles and Permissions.
Search Guard roles and their associated permissions are defined in the file sg_roles.yml
. You can define as many roles as you like. The syntax to define a role, and associate permissions with it, is as follows:
<sg_role_name>:
cluster:
- '<action group or single permission>'
- ...
indices:
'<indexname or alias>':
'<document type>':
- '<action group or single permission>'
- ...
'<document type>':
- '<action group or single permission>'
- ...
_dls_: '<Document level security query>'
_fls_:
- '<field level security fiels>'
- ...
tenants:
<tenantname>: <RW|RO>
<tenantname>: <RW|RO>
The Search Guard role name must not contain dots.
The keys _dls_
and _fls_
are used to configure Document- and Field-level security. Please refer to this chapter for details.
The key tenants
is used to configure Kibana multi-tenancy. Please refer to this chapter for details.
Document types are deprecated in Elasticsearch 6 and will be removed with Elasticsearch 7. Search Guard still supports document types for backwards compatibility. This support will be removed in Search Guard 7. To define permissions for all document types, use an asterisk (‘*’) as document type.
Cluster-level permissions
The cluster
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:
- CLUSTER_COMPOSITE_OPS_RO
indices:
...
Index-level permissions
The indices
entry is used to allow/disallow actions that affect a single index. You can define permissions for each document type in your index separately.
Document types are deprecated in Elasticsearch 6 and will be removed with Elasticsearch 7. Search Guard still supports document types for backwards compatibility. This support will be removed in Search Guard 7. To define permissions for all document types, use an asterisk (‘*’) as document type.
Dynamic index names: Wildcards and regular expressions
The index name supports (filtered) index aliases. Both the index name and the document type entries support 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
Note: The index name cannot contain dots. Instead, use the ?
wildcard, as in ?kibana
.
Example:
sg_kibana:
cluster:
- CLUSTER_COMPOSITE_OPS_RO
indices:
'?kibana':
'*':
- INDICES_ALL
Dynamic index names: User name substitution
For <indexname or alias>
also the placeholder ${user.name}
is allowed to support indices or aliases which contain the name of the user. During evaluation of the permissions, the placeholder is replaced with the username of the authenticated user for this request. Example:
sg_own_index:
cluster:
...
indices:
'${user_name}':
'*':
- INDICES_ALL
Dynamic index names: User attributes
Any authentication and authorization backend can add additional user attributes that you can then 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 internal users, these are the keys/values configured in the attributes
section of the user.
You can use these attributes in index names to implement index-level access control based on user attributes. For JWT, the attributes start with attr_jwt_*
, for LDAP they start with attr_ldap_*
. For internal users, they start with attr_internal_*
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.
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:
- CLUSTER_COMPOSITE_OPS
indices:
'${attr_jwt_department}':
'*':
- INDICES_ALL
In this example, Search Guard grants the INDICES_ALL
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_department_index:
cluster:
- CLUSTER_COMPOSITE_OPS
indices:
'${attr_ldap_department}':
'*':
- INDICES_ALL
In this example, Search Guard grants the INDICES_ALL
permissions to the index operations
.
Internal users Example
If the attributes 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 internal.
prefix:
admin:
hash: $2a$12$xZOcnwYPYQ3zIadnlQIJ0eNhX1ngwMkTN.oMwkKxoGvDVPn4/6XtO
roles:
- readall
- writeall
attributes:
department: operations
sg_department_index:
cluster:
- CLUSTER_COMPOSITE_OPS
indices:
'${attr_internal_department}':
'*':
- INDICES_ALL
In this example, Search Guard grants the INDICES_ALL
permissions to the index operations
.
Multiple Variables
You can use as many variables, wildcards and regular expressions as needed, for example:
sg_department_index:
cluster:
- CLUSTER_COMPOSITE_OPS
indices:
'logfiles-${attr_ldap_department}-${user_name}-*':
'*':
- INDICES_ALL
Using action groups to assign permissions
Search Guard comes with the ability to group permissions and give them a telling name. These groups are called action groups and are the preferred way of assigning permissions to roles. Search Guard ships with a predefined set of action groups that will cover most use cases. See chapter action groups for an overview. Action groups are written in upper case by convention.
Example:
myrole:
cluster:
- CLUSTER_COMPOSITE_OPS_RO
indices:
'index1':
'*':
- SEARCH
'index2':
'*':
- CRUD
Using single permissions
If you need to apply a more fine-grained permission schema, Search Guard also supports assigning single permissions to a role.
Single permissions either start with cluster:
or indices:
, followed by a REST-style path that further defines the exact action the permission grants access to.
For example, this permission would grant the right to execute a search on an index:
indices:data/read/search
While this permission grants the right to write to the index:
indices:data/write/index
On cluster-level, this permission grants the right to display the cluster health:
cluster:monitor/health
Single permissions also support wildcards. The following permission grants all admin actions on the index:
indices:admin/*