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.

👍

Note

The Akeyless Platform can act as a Certificate Authority for your internal environment.

You can use the PKI/TLS Certificate Issuer in the Console to issue PKI certificates for internal network resources.

Prerequisites

• A signed x509 PEM encoded certificate chain (signing_certificate.pem in our example)
• A valid PKI certificate signed by the Certificate Authority (pki_certificate.pem in our example)
• A matching private RSA key for this PKI certificate (customer_private_key.pem in our example)

Refer to our guide to set up a PKI/TLS Certificate Issuer and generate the necessary certificates.

Create a Certificate-based Authentication Method in the CLI

To create a certificate-based authentication method, the user must provide a signed x509 PEMencoded certificate chain, 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.

Let's create a new Certificate-based authentication method using the Akeyless CLI. (You can do this also from the Akeyless Console.)

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

akeyless auth-method create cert -n AuthMethodName -u UniqueIdentifierValue --certificate-file-name /Path/To/File/signing_certificate.pem

akeyless create-auth-method-cert -n AuthMethodName -u UniqueIdentifierValue --certificate-file-name /Path/To/File/signing_certificate.pem
Auth Method AuthMethodName successfully created
- Access ID: p-t6re34ynx8h4

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. to distinguish between different 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

For authentication, the user needs to provide:

• the Access ID received in the previous step
• a valid PKI certificate signed by the Certificate Authority
• a matching private RSA key for this certificate

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 /path/to/file/pki_certificate.pem --key-file-name /path/to/file/customer_private_key.pem

akeyless auth --access-id p-t6re34ynx8h4 --access-type cert --cert-file-name /path/to/file/pki_certificate.pem ---key-file-name /path/to/file/customer_private_key.pem
Authentication succeeded.
Token: t-be0a44dd031df3f3de9518f53dab8648

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.