Certificate-based Authentication

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 SaaS solution itself can act as a Certificate Authority for the internal environment.

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

Prerequisites

You need to have these three files saved on your machine:

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

Creating a Certificate-based Authentication Method

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.

The following additional parameters could be set and later checked against the certificate presented by the client in the authentication process:

Parameter

Description

--bound-common-names

A list of names. At least one must exist in the Common Name of the certificate. Supports globbing.

--bound-dns-sans

A list of DNS names. At least one must exist in the SANs of the certificate. Supports globbing.

--bound-email-sans

A list of Email Addresses. At least one must exist in the SANs of the certificate. Supports globbing.

--bound-uri-sans

A list of URIs. At least one must exist in the SANs of the certificate. Supports globbing.

--bound-organizational-units

A list of Organizational Units' names. At least one must exist in the OU field of the certificate.

--bound-extensions

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

A list of revoked certificate ids. Can be used to revoke specific certificates or intermediate certificates.

So, to create a certificate-based authentication method, run the following command in the CLI of your OS:

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

As a result, you should get the following output:

$ 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

Authenticating 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 in the CLI of your OS:

$ 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

As a result, you should get the authentication token:

$ 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

User Authentication Flow

  1. The User sends to the Akeyless authentication server a PKI certificate (in a --client-cert-file parameter) and a path to the corresponding private key (in a --client-key-file parameter). The PKI certificate contains the matching public key.

  2. The server needs to make sure that the User owns the private key that matches the public key from the PKI certificate. For that, the server sends to the User a challenge that is encrypted with this public key. The User needs to decrypt this challenge with the private key that is located at the path specified in the --client-key-file parameter.

  3. The User decrypts the challenge with the corresponding private key and sends it back to the server. This confirms the link between the User, the private key, and the PKI certificate.

  4. After that the server needs to check if the presented PKI certificate is valid along the trust chain. For this purpose, it has the root certificate stored in the Certificate-based Authentication Method object. Access ID provided by the User points the server to the right Authentication Method object.

  5. Then the server checks if all the fields specified as necessary in the Certificate-based Authentication Method object are present in the PKI certificate.

  6. Finally, the server generates an authentication token for this User.

  7. The User sends this token to the server for authorization.


Did this page help you?