Grey Matter Documentation

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.

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.

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

servers(String, default: "") - Pipe (|) delimited string of server DNs that will be validated against the incoming request.
caseInsensitive*(Boolean, default: 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

How does it work?

The ACL Impersonation Filter gives whitelist server distinguished names (DNs) the privilege to impersonate on behalf of users.
The 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.

Filter Configuration Options

Name	Type	Default	Description
`servers`	`string`	`""`	Pipe (`\|`) delimited string of server DNs that will be validated against the incoming request.

Example

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