用户授权

以下描述了索引权限条目的结构：

{
  "names": [ ... ], 
  "privileges": [ ... ], 
  "field_security" : { ... }, 
  "query": "...", 
  "allow_restricted_indices": false 
}

"foo-bar":               # match the literal `foo-bar`
"foo-*":                 # match anything beginning with "foo-"
"logstash-201?-*":       # ? matches any one character
"/.*-201[0-9]-.*/":      # use a regex to match anything containing 2010-2019
"/foo":                  # syntax error - missing final /

以下描述了全局权限条目的结构：

{
  "application": {
    "manage": {    
      "applications": [ ... ] 
    }
  },
  "profile": {
    "write": { 
      "applications": [ ... ] 
    }
  }
}

以下描述了应用程序权限条目的结构：

{
  "application": "my_app", 
  "privileges": [ ... ],   
  "resources": [ ... ]     
}

有关这些字段的验证规则的详细信息，请参阅添加应用程序权限 API。

角色可能引用不存在的应用程序权限——也就是说，它们尚未通过添加应用程序权限API定义（或者它们曾经被定义，但后来被删除了）。在这种情况下，该权限没有任何效果，并且不会在has privileges API中授予任何操作。

对于使用基于API密钥模型的远程集群，远程索引权限可用于指定匹配远程集群所需的索引权限。最终的有效索引权限将是远程索引权限与跨集群API密钥的索引权限的交集。

远程索引权限条目相比索引权限条目多了一个额外的强制性clusters字段。否则，两者的结构是相同的。 以下描述了远程索引权限条目的结构：

{
  "clusters": [ ... ], 
  "names": [ ... ], 
  "privileges": [ ... ], 
  "field_security" : { ... }, 
  "query": "...", 
  "allow_restricted_indices": false 
}

对于使用基于API密钥模型配置的远程集群，远程集群权限可以用于为匹配的远程集群指定额外的集群权限。

以下描述了远程集群权限条目的结构：

{
  "clusters": [ ... ], 
  "privileges": [ ... ] 
}

远程集群的 monitor_enrich 权限在版本 8.15.0 中引入。目前，这是唯一可用于远程集群的权限，并且需要启用用户在跨集群的 ES|QL 查询中使用 ENRICH 关键字。

以下代码片段展示了一个clicks_admin角色的示例定义：

POST /_security/role/clicks_admin
{
  "run_as": [ "clicks_watcher_1" ],
  "cluster": [ "monitor" ],
  "indices": [
    {
      "names": [ "events-*" ],
      "privileges": [ "read" ],
      "field_security" : {
        "grant" : [ "category", "@timestamp", "message" ]
      },
      "query": "{\"match\": {\"category\": \"click\"}}"
    }
  ]
}

根据上述定义，拥有clicks_admin角色的用户可以：

有两种可用的机制来定义角色：使用角色管理API或在本地的Elasticsearch节点文件中定义。您还可以实现自定义角色提供者。如果您需要与另一个系统集成以检索用户角色，您可以构建一个自定义角色提供者插件。更多信息，请参阅自定义角色和授权。

您可以在 Kibana 中轻松管理用户和角色。要管理角色，请登录 Kibana 并转到 管理 / 安全 / 角色。

通过角色管理API，您可以动态地添加、更新、删除和检索角色。当您使用这些API在native领域中管理角色时，角色会存储在Elasticsearch的内部索引中。更多信息和示例，请参见Roles。

除了角色管理API之外，角色也可以在本地roles.yml文件中定义，该文件位于ES_PATH_CONF中。这是一个YAML文件，其中每个角色定义都以其名称作为键。

虽然角色管理API是定义角色的首选机制，但如果您想定义固定角色，即除了拥有物理访问Elasticsearch节点权限的管理员之外，没有人能够更改这些角色，那么使用roles.yml文件会变得很有用。但请注意，roles.yml文件仅作为最小的管理功能提供，并不旨在涵盖所有用例的角色定义。

以下代码片段展示了 roles.yml 文件配置的示例：

click_admins:
  run_as: [ 'clicks_watcher_1' ]
  cluster: [ 'monitor' ]
  indices:
    - names: [ 'events-*' ]
      privileges: [ 'read' ]
      field_security:
        grant: ['category', '@timestamp', 'message' ]
      query: '{"match": {"category": "click"}}'

Elasticsearch 持续监控 roles.yml 文件，并自动获取和应用对其所做的任何更改。

工作流允许将角色限制为仅在调用某些REST API时有效。 调用工作流不允许的REST API将导致角色被禁用。 以下部分列出了您可以限制角色的工作流：

以下示例创建了一个API密钥，该密钥具有对角色限制的search_application_query工作流的限制， 该限制仅允许调用搜索应用程序搜索API：

POST /_security/api_key
{
  "name": "my-restricted-api-key",
  "role_descriptors": {
    "my-restricted-role-descriptor": {
      "indices": [
        {
          "names": ["my-search-app"],
          "privileges": ["read"]
        }
      ],
      "restriction":  {
        "workflows": ["search_application_query"]
      }
    }
  }
}

使用索引权限来控制对数据流的访问。授予数据流的权限会同时授予其支持索引的相同权限。

例如，my-data-stream 由两个后备索引组成： .ds-my-data-stream-2099.03.07-000001 和 .ds-my-data-stream-2099.03.08-000002。

用户被授予对 my-data-stream 的 read 权限。

{
  "names" : [ "my-data-stream" ],
  "privileges" : [ "read" ]
}

因为用户自动获得了与数据流后备索引相同的权限，用户可以直接从 .ds-my-data-stream-2099.03.08-000002中检索文档：

GET .ds-my-data-stream-2099.03.08-000002/_doc/2

稍后 my-data-stream 滚动。这将创建一个新的后备索引：.ds-my-data-stream-2099.03.09-000003。因为用户仍然拥有 my-data-stream 的 read 权限，用户可以直接从 .ds-my-data-stream-2099.03.09-000003 检索文档：

GET .ds-my-data-stream-2099.03.09-000003/_doc/2

使用索引权限来控制对别名的访问。对索引或数据流的权限不会授予对其别名的权限。有关管理别名的信息，请参阅别名。

例如，current_year 别名仅指向 2015 索引。用户被授予 2015 索引的 read 权限。

{
  "names" : [ "2015" ],
  "privileges" : [ "read" ]
}

当用户尝试从current_year别名中检索文档时，Elasticsearch会拒绝该请求。

GET current_year/_doc/1

要从current_year中检索文档，用户必须对该别名具有read索引权限。

{
  "names" : [ "current_year" ],
  "privileges" : [ "read" ]
}

您可以通过添加角色映射 API来定义角色映射。

要使用基于文件的角色映射，您必须在 YAML 文件中配置映射，并将其复制到集群中的每个节点。像 Puppet 或 Chef 这样的工具可以帮助完成此操作。

默认情况下，角色映射存储在 ES_PATH_CONF/role_mapping.yml 中， 其中 ES_PATH_CONF 是 ES_HOME/config（zip/tar 安装）或 /etc/elasticsearch（包安装）。要指定不同的位置， 您可以在 Active Directory、 LDAP 和 PKI 领域设置中配置 elasticsearch.yml 中的 files.role_mapping 设置。

在角色映射文件中，安全角色是键，组和用户是值。映射可以具有多对多的关系。当您将角色映射到组时，该组中用户的角色是分配给该组的角色和分配给该用户的角色的组合。

默认情况下，Elasticsearch 每 5 秒检查一次角色映射文件的更改。 您可以通过更改 elasticsearch.yml 文件中的 resource.reload.interval.high 设置来更改此默认行为。由于 这是 Elasticsearch 中的常见设置，更改其值可能会影响系统中的其他 调度。

虽然角色映射API是管理角色映射的首选方式，但在以下几种情况下，使用role_mapping.yml文件会变得非常有用：

请注意，role_mapping.yml 文件作为最小的管理功能提供，并不旨在涵盖所有用例并用于定义角色。

要在角色映射中指定用户和组，您可以使用它们的专有名称（DN）。DN是一个唯一标识用户或组的字符串，例如"cn=John Doe,cn=contractors,dc=example,dc=com"。

例如，以下代码片段使用基于文件的方法将admins组映射到monitoring角色，并将John Doe用户、users组和admins组映射到user角色。

monitoring: 
  - "cn=admins,dc=example,dc=com" 
user:
  - "cn=John Doe,cn=contractors,dc=example,dc=com" 
  - "cn=users,dc=example,dc=com"
  - "cn=admins,dc=example,dc=com"

您可以使用角色映射 API 来定义等效映射，如下所示：

PUT /_security/role_mapping/admins
{
  "roles" : [ "monitoring", "user" ],
  "rules" : { "field" : { "groups" : "cn=admins,dc=example,dc=com" } },
  "enabled": true
}

PUT /_security/role_mapping/basic_users
{
  "roles" : [ "user" ],
  "rules" : { "any" : [
      { "field" : { "dn" : "cn=John Doe,cn=contractors,dc=example,dc=com" } },
      { "field" : { "groups" : "cn=users,dc=example,dc=com" } }
  ] },
  "enabled": true
}

PKI 领域支持将用户映射到角色，但不能映射组，因为 PKI 领域没有组的概。

这是一个使用基于文件的映射的示例：

monitoring:
  - "cn=Admin,ou=example,o=com"
user:
  - "cn=John Doe,ou=example,o=com"

以下示例使用API创建等效映射：

PUT /_security/role_mapping/admin_user
{
  "roles" : [ "monitoring" ],
  "rules" : { "field" : { "dn" : "cn=Admin,ou=example,o=com" } },
  "enabled": true
}

PUT /_security/role_mapping/basic_user
{
  "roles" : [ "user" ],
  "rules" : { "field" : { "dn" : "cn=John Doe,ou=example,o=com" } },
  "enabled": true
}

用户可以拥有多个角色，每个角色可以对相同的数据流或索引定义不同的权限。在这种情况下，理解文档级和字段级安全性的行为非常重要。

文档级安全考虑用户持有的每个角色，并将给定数据流或索引的每个文档级安全查询与“或”组合。这意味着只需一个角色查询匹配即可返回文档。例如，如果一个角色授予对没有文档级安全的索引的访问权限，而另一个角色授予具有文档级安全的访问权限，则不会应用文档级安全；同时拥有这两个角色的用户可以访问索引中的所有文档。

字段级安全考虑用户拥有的每个角色，并将所有列出的字段组合成每个数据流或索引的单一集合。例如，如果一个角色授予对索引的访问权限而没有字段级安全，而另一个角色授予带有字段级安全的访问权限，则不会对该索引应用字段级安全；拥有这两个角色的用户可以访问该索引中的所有字段。

例如，假设role_a仅授予对index1文档中的address字段的访问权限；它没有指定任何文档限制。相反，role_b限制了对index1文档子集的访问；它没有指定任何字段限制。如果你为用户分配了这两个角色，role_a使用户可以访问所有文档，而role_b使用户可以访问所有字段。

当您创建角色时，您可以指定一个查询来定义 文档级安全权限。您可以选择在角色查询中使用 Mustache 模板，将当前经过身份验证的用户的用户名插入到角色中。与其他支持模板或脚本的 Elasticsearch 部分一样，您可以指定内联、存储或基于文件的模板，并定义自定义参数。您可以通过 _user 参数访问当前经过身份验证的用户的详细信息。

例如，以下角色查询使用模板来插入当前已验证用户的用户名：

POST /_security/role/example1
{
  "indices" : [
    {
      "names" : [ "my-index-000001" ],
      "privileges" : [ "read" ],
      "query" : {
        "template" : {
          "source" : {
            "term" : { "acl.username" : "{{_user.username}}" }
          }
        }
      }
    }
  ]
}

您可以通过 _user 变量访问以下信息：

您还可以访问自定义用户元数据。例如，如果您在用户元数据中维护了一个 group_id，您可以根据文档中的 group.id 字段应用文档级安全：

POST /_security/role/example2
{
  "indices" : [
    {
      "names" : [ "my-index-000001" ],
      "privileges" : [ "read" ],
      "query" : {
        "template" : {
          "source" : {
            "term" : { "group.id" : "{{_user.metadata.group_id}}" }
          }
        }
      }
    }
  ]
}

如果你的元数据字段包含对象或数组，你可以使用{{#toJson}}parameter{{/toJson}}函数来访问它。

POST /_security/role/example3
{
  "indices" : [
    {
      "names" : [ "my-index-000001" ],
      "privileges" : [ "read" ],
      "query" : {
        "template" : {
          "source" : "{ \"terms\": { \"group.statuses\": {{#toJson}}_user.metadata.statuses{{/toJson}} }}"
        }
      }
    }
  ]
}

为了确保用户只能阅读自己的文档，设置文档级安全是有意义的。在这种情况下，每个文档都必须与用户名或角色名相关联，以便角色查询可以使用这些信息进行文档级安全控制。这是一个可以使用设置安全用户处理器摄取处理器的情况。

The set security user processor 附加与当前经过身份验证的用户相关的详细信息（例如 username, roles, email, full_name 和 metadata ）到当前文档，通过预处理摄取。当 您使用摄取管道索引数据时，用户详细信息会自动附加到文档中。如果身份验证凭据是API密钥，则API密钥 id, name 和 metadata（如果存在且非空）也会附加到 文档中。

更多信息请参见 Ingest pipelines 和 Set security user

跨集群API密钥 可以用于验证对远程集群的请求。search 参数定义了跨集群搜索的权限。replication 参数定义了跨集群复制的权限。

replication 不支持任何字段或文档级别的安全性。search 支持字段和文档级别的安全性。

由于与具有文档和字段级安全性的多个角色中描述的类似原因， 如果search参数定义了文档或字段级安全性，则无法创建同时具有search和replication参数的单个跨集群API密钥。

如果你需要同时使用这两个参数，并且需要为search参数定义文档或字段级别的安全性， 请创建两个单独的跨集群API密钥，一个使用search参数， 另一个使用replication参数。你还需要设置两个不同的 远程连接到同一个集群，每个命名连接使用适当的跨集群API密钥。

您可以在使用创建或更新角色 API创建角色时应用run_as权限。被分配了包含run_as权限的角色的用户将继承其角色的所有权限，并且还可以代表指定的用户提交请求。

用户成功认证到 Elasticsearch 后，授权过程会确定传入请求背后的用户是否被允许运行该请求。如果已认证的用户在其权限列表中具有 run_as 权限，并指定了 run-as 头，Elasticsearch 将丢弃已认证的用户及其关联角色。然后，它会在领域链中的每个配置领域中查找，直到找到与 run_as 用户关联的用户名，并使用这些角色来执行任何请求。

考虑一个管理员角色和一个分析师角色。管理员角色拥有更高的权限，但也可能希望以其他用户身份提交请求来测试和验证他们的权限。

首先，我们将创建一个名为 my_admin_role 的管理角色。该角色在整个集群和部分索引上具有 manage 权限。此角色还包含 run_as 权限，该权限允许任何拥有此角色的用户代表指定的 analyst_user 提交请求。

POST /_security/role/my_admin_role?refresh=true
{
  "cluster": ["manage"],
  "indices": [
    {
      "names": [ "index1", "index2" ],
      "privileges": [ "manage" ]
    }
  ],
  "applications": [
    {
      "application": "myapp",
      "privileges": [ "admin", "read" ],
      "resources": [ "*" ]
    }
  ],
  "run_as": [ "analyst_user" ],
  "metadata" : {
    "version" : 1
  }
}

接下来，我们将创建一个名为 my_analyst_role 的分析师角色，该角色具有更多限制性的 monitor 集群权限和部分索引上的 manage 权限。

POST /_security/role/my_analyst_role?refresh=true
{
  "cluster": [ "monitor"],
  "indices": [
    {
      "names": [ "index1", "index2" ],
      "privileges": ["manage"]
    }
  ],
  "applications": [
    {
      "application": "myapp",
      "privileges": [ "read" ],
      "resources": [ "*" ]
    }
  ],
  "metadata" : {
    "version" : 1
  }
}

我们将创建一个管理员用户，并为其分配名为 my_admin_role 的角色， 该角色允许此用户以 analyst_user 的身份提交请求。

POST /_security/user/admin_user?refresh=true
{
  "password": "l0ng-r4nd0m-p@ssw0rd",
  "roles": [ "my_admin_role" ],
  "full_name": "Eirian Zola",
  "metadata": { "intelligence" : 7}
}

我们也可以创建一个分析师用户并为他们分配名为my_analyst_role的角色。

POST /_security/user/analyst_user?refresh=true
{
  "password": "l0nger-r4nd0mer-p@ssw0rd",
  "roles": [ "my_analyst_role" ],
  "full_name": "Monday Jaffe",
  "metadata": { "innovation" : 8}
}

然后，您可以以admin_user或analyst_user的身份向Elasticsearch进行身份验证。然而，admin_user可以选择代表analyst_user提交请求。以下请求使用Basic授权令牌向Elasticsearch进行身份验证，并以analyst_user的身份提交请求：

curl -s -X GET -H "Authorization: Basic YWRtaW5fdXNlcjpsMG5nLXI0bmQwbS1wQHNzdzByZA==" -H "es-security-runas-user: analyst_user" https://localhost:9200/_security/_authenticate

响应表明，analyst_user 提交了这个请求，使用了分配给该用户的 my_analyst_role。当 admin_user 提交请求时，Elasticsearch 验证了该用户，丢弃了他们的角色，然后使用了 run_as 用户的角色。

{"username":"analyst_user","roles":["my_analyst_role"],"full_name":"Monday Jaffe","email":null,
"metadata":{"innovation":8},"enabled":true,"authentication_realm":{"name":"native",
"type":"native"},"lookup_realm":{"name":"native","type":"native"},"authentication_type":"realm"}
%

响应中的 authentication_realm 和 lookup_realm 都指定了 native 领域，因为 admin_user 和 analyst_user 都来自该领域。如果这两个用户位于不同的领域，则 authentication_realm 和 lookup_realm 的值将不同（例如 pki 和 native）。

以下是可作为授权领域使用的LDAP领域的一个示例配置。此LDAP领域在用户搜索模式下配置，并指定了一个过滤器。

有关配置LDAP领域的更多信息，请参阅LDAP用户认证。

xpack:
  security:
    authc:
      realms:
        ldap:
          ldap1:
            order: 0
            authentication.enabled: true 
            user_search:
              base_dn: "dc=example,dc=org"
              filter: "(cn={0})"
            group_search:
              base_dn: "dc=example,dc=org"
            files:
              role_mapping: "ES_PATH_CONF/role_mapping.yml"
            unmapped_groups_as_roles: false

以下是一个配置示例，其中Kerberos领域对用户进行身份验证，然后将授权委托给LDAP领域。Kerberos领域对用户进行身份验证并提取用户主体名称（通常格式为user@REALM）。在此示例中，我们启用了remove_realm_name设置，以从用户主体名称中删除@REALM部分，从而获取用户名。此用户名用于通过配置的授权领域（在本例中为LDAP领域）进行用户查找。

有关Kerberos领域的更多信息，请参阅Kerberos认证。

xpack:
  security:
    authc:
      realms:
        kerberos:
          kerb1:
            order: 1
            keytab.path: "ES_PATH_CONF/es.keytab"
            remove_realm_name: true
            authorization_realms: ldap1

我们同样可以配置PKI领域以将授权委托给LDAP领域。用户由PKI领域进行身份验证，而授权则委托给LDAP领域。在此示例中，用户名是从客户端证书的DN中提取的通用名称（CN）。LDAP领域使用此用户名来查找用户并分配角色。

有关PKI领域的更多信息，请参阅PKI用户认证。

xpack:
  security:
    authc:
      realms:
        pki:
          pki1:
            order: 2
            authorization_realms: ldap1

与上述示例类似，我们可以配置领域以将授权委托给授权领域（这些领域具有通过用户名查找用户并分配角色的能力）。

要创建自定义角色提供程序：

将您的自定义角色提供程序打包为插件：

要创建一个授权引擎，您需要：

将您的授权引擎打包为插件：

提供了示例代码，展示了自定义授权引擎的结构和实现，位于GitHub上的 elasticsearch 仓库中。您可以使用此代码作为创建自己的授权引擎的起点。

为了为您的自定义角色提供程序或授权引擎注册安全扩展，您还需要实现一个包含该扩展的elasticsearch插件：

要使用安全扩展：