Certificates

Certificate-based authentication is usually a machine-to-machine authentication flow. An organization may already have a private Certificate Authority in place to sign and distribute digital (PKI) certificates to machines, which they use to authenticate to different internal services. The Akeyless SaaS solution can be built into this flow seamlessly.

Prerequisites

• CA certificate for signature verification
• X.509 certificate signed by a CA and corresponding Private Key in PEM format

Create a Certificate-based Authentication Method in the CLI

To create a certificate-based authentication method, the user must provide a signed x509 PEM encoded certificate, and a unique identifier that could be a value of common_name or organizational_unit parameters from the certificate.

A unique identifier acts as a sub-claim helping to uniquely identify the authenticating Identity.

To create a certificate-based authentication method, run the following command:

akeyless auth-method create cert \
--name <Auth Method name> \
--unique-identifier 'common_name' \
--certificate-file-name 'ca_certificate.pem'

Where:

• name: A unique name for the authentication method. The name can include the path to the virtual folder where you want to create the new authentication method, using slash / separators. If the folder does not exist, it will be created together with the authentication method.

• unique-identifier A unique identifier parameter plays the same role as a sub-claim in OIDC, OAuth2, LDAP, and SAML authentication method types. It contains details that allow the system to uniquely identify the user (e.g., distinguishing between users from within the same organization).

• certificate-file-name: A path to the CA certificate.

You can find the complete list of additional parameters for this command in the CLI Reference - Authentication section.

Authenticate with the Certificate-based Authentication Method

To authenticate using the new certificate-based authentication method, run the following command:

akeyless auth \
--access-id <Access ID> \
--access-type cert \
--cert-file-name cert.pem \
--key-file-name key.pem

Where:

• access-id: The Access ID of the Certificate Authentication Method

• cert-file-name: Path to the signed x509 PEM Encoded Certificate in a PEM format

• key-file-name: Matching Private Key for the certificate in a PEM format

As a result, you should get the authentication token

Create a Certificate-based Authentication Method in the Console

1. Log in to the Akeyless Console and go to Users & Auth Methods > New > Application (Certificate).

2. Define a Name for the authentication method, and specify the Location as a path to the virtual folder where you want to create the new authentication method, using slash / separators. If the folder does not exist, it will be created together with the authentication method.

3. Define the remaining parameters as follows:

• Expiration Date: Select the access expiration date. This parameter is optional. Leave it empty for access to continue without an expiration date.

• Allowed Client IPs: Enter a comma-separated list of CIDR blocks from which the client can issue calls to the proxy. By "client," we mean CURL, SDK, etc. This parameter is optional. Leave it empty for unrestricted access.

• Allowed Trusted Gateway IPs: Enter a comma-separated list of CIDR blocks. When specified, the Gateway with the IP from this range will be trusted to forward original client IPs (so that they will be visible in the logs). If empty, the Gateway's IP will be used in the logs.

• Audit Log Sub Claims: Enter a comma-separated list of sub-claims keys to be included in the audit logs.

• CA Certificate: Download the CA certificate in Base64 format.

• Bound Common Names: Enter a list of names. At least one must exist in the Common Name of the certificate. Supports globbing.

• Bound DNS SANs: Enter a list of DNS names. At least one must exist in the SANs of the certificate. Supports globbing.

• Bound Email SANs: Enter a list of Email Addresses. At least one must exist in the SANs of the certificate. Supports globbing.

• Bound URI SANs: Enter a list of URIs. At least one must exist in the SANs of the certificate. Supports globbing.

• Bound Organizational Units: Enter a list of Organizational Units' names. At least one must exist in the OU field of the certificate.

• Bound Extensions: Enter a list of extensions formatted as oid:value. Expects the extension value to be some type of ASN1 encoded string. All values must exist in the certificate. Supports globbing on value.

• Revoked Cert Ids: Enter a list of revoked certificate ids. Can be used to revoke specific certificates or intermediate certificates.

• Allowed CORS Domains: Comma-separated list of allowed CORS domains to be validated as part of the authentication flow.

• Unique Identifier: A unique identifier to distinguish different users such as common_name or organizational_unit.

4. Click Finish.