Impersonation

The Impersonation Filter (also known as the Access Control List (ACL) Filter) gives specified server distinguished names (DNs) the privilege to impersonate on behalf of users. The incoming headers EXTERNAL_SYS_DN and SSL_CLIENT_S_DN are validated against this list to make sure both servers wanting to impersonate a user are valid and have proper permissions to do so.

Example Use Cases

Limiting Access to Specific DNs

The Impersonation/ACL filter allows system administrators to specify a list of DNs which are allowed to access a service. If a DN is not in this approved list, that request is rejected with a 403 response. In typical installations of Grey Matter, sidecars are set up to only accept communication from the edge and a global DN for inter-mesh communication:

{
    "listener_key" : "listener-example-service",
    "active_http_filters" : [
        "gm.impersonation",
    ],
    "gm_impersonation" : {
        "servers": "cn=edge-egress|cn=sidecar"
    },
    ...
}

This ensures that services refuse any communication that does not pass through edge and is not using a valid sidecar DN.

Note: the gm-inheaders filter needs to be set on edge nodes to ensure that users are not able to set arbitrary USER_DN or EXTERNAL_SYS_DN headers.

Service Acting as a User

A Service may 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 User Service sidecar could have the following impersonation filter configuration:

{
    "listener_key"  : "listener-user-service",
    "active_http_filters" : [
        "gm.impersonation",
    ],
    "gm_impersonation" : {
        "servers" : "cn=my-service|cn=edge"
    }
    ...
}

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

Note: we also have to specify cn=edge in the server white list since requests coming through edge will have SSL_CLIENT_S_DN set to the edge certificate.

Flow Chart

Header Definitions

USER_DN - The effective (possibly impersonated) Distinguished Name of requesting application

SSL_CLIENT_S_DN - The Distinguished Name taken from the system certificate

EXTERNAL_SYS_DN - The Distinguished Name taken from the external system certificate (originally inside s_client_s_dn)

Filter Configuration Options

Name	Type	Default	Description
servers	String	""	Pipe (|) delimited string of server DNs that will be validated against the incoming request.
caseInsensitive	Boolean	false	If set to true, does not validate case for each server DN specified.

Example

http_filters:
- name: gm.impersonation
  config:
    servers: "C=US,ST=Virginia,L=Alexandria,O=Decipher Technology Studios,OU=Engineering,CN=localhost"
    caseInsensitive: true