Certificates

TLS 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.pemin 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 from the CLI

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

Parameters

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

As a result, you should get the Access ID.

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 p-t6re34ynx8h4 --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 Akeyless Console

  1. Log in to the Akeyless Console and go to Auth Methods > New > 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.

    • 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.

  4. Click Save.

👍

What's next?

Make sure to associate your new Authentication Method with an Access Role to grant the relevant permissions within Akeyless


Did this page help you?