User impersonation#

Starburst Enterprise platform (SEP) has to be authenticated when accessing an external service through the connector. Typically it requires passing authentication credentials, which contain information on behalf of what user SEP connects. Such credentials are stored in connector properties file.

Any SEP user accesses the external service as the user configured in the connector properties. This approach has the following downsides:

No authorization policies, built-in into this external service, are able to recognize the actual SEP user. As a result any user, who authenticates to SEP and access the data with SEP, has the same permissions and is tracked as the same service user.
It is difficult to perform an audit of access of the external service, since every SEP user is seen as the same local user in the external service.

One way of solving this is to impersonate the SEP user as the local user in the external service. With this approach SEP authenticates in the external service using credentials stored in the connector properties file. Once it connects, it informs the external service that any further action in a given session should be performed on behalf of current SEP user. That way a SEP user alice becomes a local user alice in the external service. This requires the user that connects to the external service, which is configured in connector properties file, to be trusted in this system and to be allowed to impersonate other users.

Note

The user impersonation feature is only supported in select connectors. Reference the connectors feature matrix for more information about which connectors support this feature.

When impersonating SEP users in the external service, SEP itself also requires authentication and proper access control configuration to ensure that users with valid credentials can be authenticated in the external service.

Note that the external service is required to support the impersonation mechanism, and actual details are different depending on the service.

The connectors that support user impersonation as the SEP user are shown in the Starburst connectors feature matrix.

The Hive connector also supports user impersonation when connecting to Hive Metastore or HDFS. However, the Hive connector doesn’t support SEP user to local user translation.

Additional considerations#

Consider the following before enabling impersonation:

Caching mechanisms are less effective when the cache has to be maintained for each individual user separately.
SEP features that run queries on behalf of users, such as the Cache service, require the SEP service user to have all the necessary permissions to run queries for those users.

While impersonation is a powerful feature, especially when handing workload migrations to SEP, long-term usage becomes less performant as impersonation limits the effectiveness of caching solutions in SEP and requires bespoke security configurations.

SEP user-to-local user translation#

The same actual user could be represented differently among services. For example, a SEP user alice_in_starburst can be represented in an external service as alice_in_external_service. There are two modes of user to local user translation:

Rule-based (default)
LDAP-based

The translation mode can be specified per-catalog with the auth-to-local.type catalog configuration property.

To enable user translation for a catalog, add a prefix before each catalog configuration property to specify which service the mapping is for. For example, to create an auth-to-local user mapping configuration for HDFS, use the hive.hdfs prefix followed by the appropriate property:

hive.hdfs.auth-to-local.type=LDAP
hive.hdfs.ldap.url=ldap://ldapserver:389
hive.hdfs.ldap.allow-insecure=true
hive.hdfs.auth-to-local.ldap.bind-dn=cn=admin,dc=trino,dc=testldap,dc=com
hive.hdfs.auth-to-local.ldap.bind-password=admin
hive.hdfs.auth-to-local.ldap.user-base-dn=dc=trino,dc=testldap,dc=com
hive.hdfs.auth-to-local.ldap.user-search-filter=(&(objectClass=inetOrgPerson)(sn=${USER}))
hive.hdfs.auth-to-local.ldap.attribute=givenName

The following services are supported for user translation catalog configuration with the corresponding prefix:

hive.hdfs for Hadoop Distributed File System (HDFS)
hive.metastore.thrift for Hive Metastore (HMS)
ranger for Ranger

Rule-based user-to-local user translation#

With rule-based user translation, you create a JSON file for a catalog containing user translation rules that map SEP users to their username in the catalog’s underlying data source.

Specify the path to the user translations file with the auth-to-local.config-file catalog configuration property:

auth-to-local.config-file=etc/auth-to-local-rules.json

The config file is specified in JSON format, and contains the rules defining how SEP users are represented in the external service.

Refreshing translation rules#

By default, when a change is made to the user translations file, the cluster must be restarted to load the changes. You can optionally configure the auth-to-local.refresh-period catalog configuration properties in the catalog properties file to refresh the translation rules without requiring a cluster restart:

auth-to-local.refresh-period=10m

User translation rules#

These rules control the SEP user name translation to the external service local user name. The local user is calculated by the first matching rule read from top to bottom. If no rule matches, an error is raised. Each rule is composed of the following fields:

match (optional): determines if local user should be calculated from SEP user name (USER) or principal (PRINCIPAL). Defaults to USER.
pattern (required): regex to match against the value pointed with match.
substitution (optional): local user replacement for SEP user.
case (optional): determines if result local user should be lowercased (LOWER), upper cassed (UPPER) or case should remain (KEEP). Defaults to KEEP.

For example, if you want to impersonate SEP user alice to access the external system as user alice_in_the_external_system and bob as charlie, you can use the following rules:

{
  "rules": [
    {
      "match": "USER",
      "pattern": "alice",
      "substitution": "alice_in_the_external_system"
    },
    {
      "match": "USER",
      "pattern": "bob",
      "substitution": "charlie"
    }
  ]
}

If you want to impersonate SEP users with principals alice/hr@company.com and charlie/eng@company.com to access the external system as users HR_ALICE and ENG_CHARLIE accordingly, but SEP principals bob/marketing@company.com and danny/marketing@company.com to use marketing_acount, you can use the following rules:

{
  "rules": [
    {
      "match": "PRINCIPAL",
      "pattern": "[^/]+/marketing@company.com",
      "substitution": "marketing_acount"
    },
    {
      "match": "PRINCIPAL",
      "pattern": "([^/]+)/(.+)@company.com",
      "case": "UPPER",
      "substitution": "$2_1"
    }
  ]
}

LDAP-based user-to-local user translation#

With LDAP-based user translation, the catalog can connect to an LDAP server for information on how the SEP user maps to the external service. If configured for a catalog, SEP connects to the LDAP server and searches for a match against the current user. A successful match is cached in SEP for an amount of time defined in the auth-to-local.cache-ttl catalog configuration property.

To enable LDAP-based user translation for a catalog, configure the following catalog configuration properties:

Property name	Description
`ldap.url`	URL of the LDAP server. The URL scheme must be `ldap://` or `ldaps://`. Connecting to an LDAP server without TLS enabled requires `ldap.allow-insecure` to be set to `true`.
`ldap.allow-insecure`	Allow connection to an LDAP server that is not secured with TLS.
`ldap.ssl.keystore.path`	Path to the PEM or JKS key store.
`ldap.ssl.keystore.password`	Password for the key store.
`ldap.ssl.truststore.path`	Path to the PEM or JKS trust store.
`ldap.ssl.truststore.password`	Password for the trust store.
`ldap.ignore-referrals`	If set to `true`, ignores referrals from the LDAP server to instead only search for a user match within one LDAP server.
`ldap.timeout.connect`	Timeout for establishing a connection.
`ldap.timeout.read`	Timeout for reading data from the LDAP service.
`auth-to-local.ldap.bind-dn`	Distinguished name for the user bind. For example: `CN=User Name,OU=CITY_OU,OU=STATE_OU,DC=domain,DC=domain_root`.
`auth-to-local.ldap.bind-password`	Password used for the user bind. For example: `password1234`.
`auth-to-local.ldap.user-base-dn`	Base distinguished name of the user. For example: `dc=example,dc=com`.
`auth-to-local.ldap.user-search-filter`	Custom user search query on the LDAP service. For example: `(&(objectClass=inetOrgPerson)(uid=${USER}))`.
`auth-to-local.ldap.attribute`	Attribute to be used for user mapping.
`auth-to-local.cache-ttl`	Determines how long user mapping information is cached.

Username case sensitivity#

User impersonation is case-sensitive by default. As a result, when the SEP user name and identity provider token subjects are in different letter cases, user impersonation may fail or trigger an unwanted mapping rule.

Set the http-server.impersonation.case-sensitive property in config.properties to false, to disable username case sensitivity:

http-server.impersonation.case-sensitive=false