Akeyless supports Rotated Secrets for a growing number of services. Suppose you need to integrate with a service that is not yet natively implemented in Akeyless. In that case, you can create a custom Rotated Secret implementation that calls the service on demand to rotate secrets.

Akeyless communicates with custom Rotated Secret implementations over HTTP and delegates the rotate operation to the external services using a particular HTTP endpoint that follows a specific input/output format.

Once you have set up a custom Rotated Secret implementation, you can create a custom Rotated Secret that calls the implementation to rotate credentials.

Inputs

Custom Rotated Secret implementations are completely stateless. Akeyless provides encrypted storage for any user credentials, API keys, or other secret data required by a particular implementation and provides them to the custom Rotated Secret implementation with every request.

Set Up a Custom Rotated Secret Implementation

First, you must create a Web Target in Akeyless. This target holds the target endpoint of your application (e.g., https://my.web.server/rotate endpoint).

To create a Web Target using the Akeyless CLI, run the following command:

akeyless create-web-target -n <your web target name> \
-u https://my.web.server/rotate

Authentication

📘

Note

Custom Rotated Secret implementations should only handle requests from a known Akeyless Gateway instance. Every request made by Akeyless to a custom Rotated Secret implementation includes an AkeylessCreds header with a temporary JWT token issued and signed by Akeyless.

Use the following endpoint to verify all requests:

POST auth.akeyless.io/validate-producer-credentials
{
  "creds": "<redacted jwt token>",
  "expected_access_id": "p-1234",
  "expected_item_name": "/custom-rotated-foo",
}

Where:

Create a Custom Rotated Secret from the CLI

To create a custom Rotated Secret from the CLI, run the following command:

akeyless create-rotated-secret -n <Rotated Secret name> \
--gateway-url 'https://<Your-Akeyless-GW-URL:8000>' \
--target-name <Web Target item name> \
--authentication-credentials <use-user-creds> \
--rotator-type <custom> \
--custom-payload <Secret payload to be sent with rotation request> \
--auto-rotate <true|false> \
--rotation-interval <1-365>

Where:

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

• gateway-url: Akeyless Gateway URL.

• target-name: The name of the Web Target with which the custom Rotated Secret should be associated.

• authentication-credentials: Determines how to connect to the target.

  • use-user-creds - Use the credentials defined on the Rotated Secret item.

• rotator-type: The type of credentials to be rotated. For Web Target, choose:

  • custom - to rotate the password for the user specified in the Web Target.

• custom-payload: A secret payload to be sent with a rotation request.

• auto-rotate: Enable auto-rotation if you need to update the password regularly. If this value is set to true, specify the rotation-interval in days.

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