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 can manually assign one or more subject names to the Consumer entity 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.
You can create a Consumer mapping with either of the following:
The following table describes how Consumer mapping parameters work for the Header Cert Auth plugin:
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 Gateway’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 Admin API: UUID of the Certificate Authority (CA).
If using declarative configuration: Full PEM-encoded CA certificate.
The provided CA UUID or full CA 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 .
|
After a client certificate has been verified as valid, the Consumer object is determined in the following order, unless config.skip_consumer_lookup
is set to true
:
- Manual mappings with
subject_name
matching the certificate’s SAN or CN (in that order) and ca_certificate = {issuing authority of the client certificate}
- Manual mappings with
subject_name
matching the certificate’s SAN or CN (in that order) and ca_certificate = NULL
- If
config.consumer_by
is not null, Consumer with username
and/or id
matching the certificate’s SAN or CN (in that order)
- 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 Gateway.
-
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 Admin API and retrieve
more information about the Consumer.
When config.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
: The distinguished name of the client certificate
-
X-Client-Cert-San
: The SAN of the client certificate
Once config.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 and create
allowed or denied groups of users using the same
certificate property being set in config.authenticated_group_by
.