Impersonation

Conceptually, Impersonation is akin to saying, “I am System-User-A ("Non-Person Entity A") but I am acting as though I am Human-User-B.” System-User-A is the impersonator and Human-User-B is the impersonated.

The Impersonation Filter is intended to work with X.509 Public Key Infrastructure (PKI) certificates and gives specified server Non-Person Entity (NPE) distinguished names (DNs) the privilege to impersonate on behalf of human users. The DN provides the identifying information of an entity and is part of a certificate. When the Impersonation Filter is configured and made active on a service, incoming requests need some means of identifying who is the impersonator and who is the impersonated. This is made possible by the InHeaders filter which provides a set of incoming headers applied by a proxy, generally the Edge proxy. Upon enabling InHeaders in the Edge proxy, for example, all incoming requests are given two headers: EXTERNAL_SYS_DN and SSL_CLIENT_S_DN. These request headers declare the DN of the impersonator and will accompany the message as it is passed to its intended target service. Once a request reaches its intended target, the server DN is validated against the Impersonation list to make sure the server CN wanting to impersonate a user is valid and has proper permissions to do so.

See the InHeaders docs for more information on how Impersonation and InHeaders work together.

Example Use Cases

Limiting Access to Specific DNs

The Impersonation filter allows system administrators to specify a list of NPE DNs which are allowed to access a target service. If an NPE DN is not in this approved list, that request is rejected with a 403 response. Here is an example showing the key value pairs required to enable impersonation (_enable_impersonation), activate the filter (http_filters), create the server list (servers) and disable case sensitivity (caseSensitive). Adding these values to the #listener configuration of example-service.cue will enable impersonation on a target service called example-service.

  #listener & {
    listener_key:          "listener-example-service"
    _enable_impersonation: true
    http_filters: gm_impersonation: {
      servers:  "CN=edge-egress,OU=Engineering,O=Greymatter.io,L=Alexandria,ST=Virginia,C=US"
      caseSensitive: false
    }		
  },

This configuration ensures that the example-service refuses any communication that does not pass through edge or is not using a valid sidecar DN. To create a list of multiple DNs, use the Pipe Operator to separate the DN values.

Service Acting as a User

A service itself may also need to impersonate users in order to access user information (e.g. email addresses, phone numbers) or validate that a user exists in the system. To set this up, a sidecar to user-service could have its #listener configuration set as follows to enable impersonation from my-service:

  #listener & {
    listener_key:          "listener-user-service"
    _enable_impersonation: true
    http_filters: gm_impersonation: {
      servers:  "CN=my-service,OU=Engineering,O=Greymatter.io,L=Alexandria,ST=Virginia,C=US"
      caseSensitive: false
    }		
  },

This will give my-service the ability to send any USER_DN to the user-service in order to access information on any user.

Header Definitions

Filter Configuration Options