Skip to content
|
Plugin Hub
github-edit-pageEdit this page
report-issueReport an issue
header icon

Manual Mappings Between Certificate and Consumer Objects

By Kong Inc.
You are browsing unreleased documentation.

Sometimes, you might not want to use automatic consumer lookup, or you have certificates that contain a field value not directly associated with consumer objects. In those situations, you may manually assign one or more subject names to the consumer object for identifying the correct consumer.

Note: Subject names refer to the certificate’s Subject Alternative Names (SAN) or Common Name (CN). CN is only used if the SAN extension does not exist.

Create a mapping:

curl -X POST http://localhost:8001/consumers/{consumer}/mtls-auth \
    -d 'subject_name=test@example.com'

Where {consumer} is the id or username property of the consumer entity to associate the credentials to.

Once created, you’ll see a 201 success message:

HTTP/1.1 201 Created

{
    "consumer": { "id": "876bf719-8f18-4ce5-cc9f-5b5af6c36007" },
    "created_at": 1443371053000,
    "subject_name": "test@example.com"
}

To create a subject name mapping using declarative configuration, you must generate a UUID for each mtls_auth_credentials mapping. You can use any UUID generator to do this. Here are some common ones, depending on your OS:

After you have generated a UUID, add the following to your declarative configuration file:

consumers:
- custom_id: my-consumer
  username: {consumer}
  mtls_auth_credentials:
  - id: bda09448-3b10-4da7-a83b-2a8ba6021f0c
    subject_name: test@example.com

Parameters for manual mapping

Form Parameter Default Description
id
required for declarative config 		none UUID of the consumer-mapping. Required if adding mapping using declarative configuration, otherwise generated automatically by Kong’s Admin API.
subject_name
required 		none The Subject Alternative Name (SAN) or Common Name (CN) that should be mapped to consumer (in order of lookup).
ca_certificate
optional 		none If using the Kong Admin API: UUID of the Certificate Authority (CA).

If using declarative configuration: Full PEM-encoded CA certificate.

The provided CA UUID or full certificate has to be verifiable by the issuing certificate authority for the mapping to succeed. This is to help distinguish multiple certificates with the same subject name that are issued under different CAs.

If empty, the subject name matches certificates issued by any CA under the corresponding config.ca_certificates.

Matching behaviors

After a client certificate has been verified as valid, the consumer object is determined in the following order, unless skip_consumer_lookup is set to true:

  1. Manual mappings with subject_name matching the certificate’s SAN or CN (in that order) and ca_certificate = <issuing authority of the client certificate>
  2. Manual mappings with subject_name matching the certificate’s SAN or CN (in that order) and ca_certificate = NULL
  3. If config.consumer_by is not null, consumer with username and/or id matching the certificate’s SAN or CN (in that order)
  4. The config.anonymous consumer (if set)

Note: Matching stops as soon as the first successful match is found.

When a client has been authenticated, the plugin appends some headers to the request before proxying it to the upstream service, so that you can identify the consumer in your code:

  • X-Consumer-ID: The ID of the consumer in Kong.
  • X-Consumer-Custom-ID: The custom_id of the consumer (if set).
  • X-Consumer-Username: The username of the consumer (if set).
  • X-Credential-Identifier: The identifier of the credential (only if the consumer is not the anonymous consumer).
  • X-Anonymous-Consumer: Is set to true if authentication fails, and the anonymous consumer is set instead.

You can use this information on your side to implement additional logic. You can use the X-Consumer-ID value to query the Kong Admin API and retrieve more information about the consumer.

When skip_consumer_lookup is set to true, consumer lookup is skipped and instead of appending aforementioned headers, the plugin appends the following two headers

  • X-Client-Cert-Dn, distinguished name of the client certificate
  • X-Client-Cert-San, SAN of the client certificate

Once skip_consumer_lookup is applied, any client with a valid certificate can access the Service/API. To restrict usage to only some of the authenticated users, also add the ACL plugin (not covered here) and create allowed or denied groups of users using the same certificate property being set in authenticated_group_by.