From X-Pack to OpenSearch: Part 5 – Migrating User Impersonation (run_as)

This article describes how to migrate user impersonation (run_as) security settings from X-Pack Security to OpenSearch Security.

X-Pack run_as

In our last blog post, we discussed how to migrate Document and Fieldlevel security settings from X-Pack Security to OpenSearch Security. In this article we focus on User impersonation which is an optional part of the role definition.

The feature is sometimes referred to as run_as in X-Pack. In this article we will use the more suitable term user impersonation.

Assume we have a role with run_as defined:

{
  "cluster":[
    "all"
  ],
  "indices":[
    {
      "names":[
        "index*",
        "some"
      ],
      "privileges":[
        "all"
      ],
      "run_as": [ "spock", "worf" ],
    }
  ]
}

The run_as part of the role definition allows a user with this role (the authenticated user to act on behalf of the users defined as values (in this example spock and worf. Wildcards are not supported.

Assume the user kirk is assigned the role stated above then he can also execute API call as spock (or worf). In this case, the API behaves exactly like the user was really worf. This means of course that the impersonated API call will fail if spock does not have the required permissions.

The main reason to use user impersonation is, apart from testing and troubleshooting, to allow trusted applications to act as different users without authenticating every one of them. Under the assumption that a trusted application handles authentication and authorization itself, it may also be a fact that such an application does not have the user credentials to authenticate the user to elasticsearch.

To submit an API request as an impersonated user a HTTP header named es-security-runas-user needs to be attached to every request.

Here is a curl example:

curl -k -H "es-security-runas-user: spock" -u kirk:kirkpassword https://localhost:9200/_search

OpenSearch User Impersonation

In OpenSearch Security user impersonation also exists and works similarly but will be configured differently to X-Pack.

In OpenSearch, user impersonation will be configured in opensearch.yml and not in the roles.

The main advantage in doing this statically in opensearch.yml is that it is more secure because only system administrators can change it. User impersonation is a critical feature which could cause great harm when wrongly configured.

The disadvantage is that it is inflexible and requires a rolling cluster restart if changes must be made. On the other hand, OpenSearch allows wildcards and even regular expressions.

Here is an equivalent example to the definition we have in X-Pack:

plugins.security.authcz.rest_impersonation_user:
  kirk:
    - spock
    - worf

To submit an API request as an impersonated user a HTTP header named opendistro_security_impersonate_as needs to be attached to every request.

Here is a curl example:

curl -k -H "opendistro_security_impersonate_as: spock" -u kirk:kirkpassword https://localhost:9200/_search

Because wildcards are supported in OpenSearch User impersonation configuration, we can also configure something like:

plugins.security.authcz.rest_impersonation_user:
  admin:
    - *

This would allow the admin user to impersonate as any other user.

Migrate User Impersonation Configuration

First, we need to retrieve the roles from Elasticsearch and inspect which of them have the run_as attribute assigned. Please refer to our blog post Part 3 – Migrating Custom Roles for a detailed description on how to do this.

After you have figured out which roles allow impersonation you need to find out which users have those roles assigned.

Then create a configuration according to

plugins.security.authcz.rest_impersonation_user:
  <AUTHENTICATED_USER_1>:
    - <IMPERSONATED_USER_1>
    - <IMPERSONATED_USER_2>
  <AUTHENTICATED_USER_2>:
    - <IMPERSONATED_USER_1>
    - <IMPERSONATED_USER_3>
  <AUTHENTICATED_USER_3>:
    - <IMPERSONATED_USER_Y>
    - <IMPERSONATED_USER_X>

and add it to the opensearch.yml on every node.

Perform a rolling restart and you are done.

Limitations

In X-Pack and as well in OpenSearch Security not all authentication methods support user impersonation. The to be impersonated user needs to be looked up (without credentials) by the authenticated user. This is only possible for the following authentication methods:

X-Pack Security Realm	OpenSearch Security Authentication backend
`native`	`Internal User Database`
`ldap`	`ldap`
`active_directory`	`ldap`

Next Steps

In our next article, we will cover the migration of more complex roles containing tenants and role mappings.

Please reach out with any questions or comments via twitter!