Akeyless supports dynamic secrets for a growing number of services. If you need to integrate with a service that is not yet natively implemented in Akeyless, you can create a custom dynamic secret implementation that calls the service on demand to generate or revoke temporary secrets.

Akeyless communicates with custom dynamic secret implementations over HTTP, and delegates create
and revoke operations to the external services using a particular set of HTTP endpoints that follow a specific input/output format.

Once you have set up a custom dynamic secret implementation, you can create a custom dynamic secret that calls the implementation to generate dynamic credentials.

Inputs

Custom dynamic 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 dynamic secret implementation with every request.

In addition, some custom dynamic secret implementations require user input every time a new secret value is requested. Akeyless accepts user input for every get-dynamic-secret-value operation for custom dynamic secret implementations.

Set Up a Custom Dynamic Secret Implementation

Implement the following endpoints to integrate with Akeyless:

• POST /sync/create: This endpoint is called each time a user requests a dynamic secret value.
• POST /sync/revoke: This endpoint is called each time temporary credentials need to be revoked.
• POST /sync/rotate: (Optional) This endpoint is called to rotate the custom dynamic secret payload.

POST /sync/create Input

This endpoint is called each time a user requests a dynamic secret value.

POST /sync/create
{
    "payload": "secret data stored by Akeyless",
    "input": { "user": "input" },
    "client_info": {
        "access_id": "p-1234",
        "sub_claims": {
            "claim1": ["value1"]
        }
    }
}

Where:

POST /sync/create Output

HTTP 200 OK
{
    "id": "<unique id>",
    "response": { <response as json object> }
}

Where:

POST /sync/revoke Input

This endpoint is called every time credentials need to be revoked. This can happen either when the TTL defined for the custom dynamic secret expires, or if an administrator explicitly requests that particular credentials are revoked.

Not every service supports revocation. If not, the operation should just return the specified IDs.

POST /sync/revoke
{
    "payload": "secret data stored by Akeyless",
    "ids": ["abc", "def"]
}

Where:

POST /sync/revoke Output

HTTP 200 OK
{
    "revoked": ["abc", "def"],
    "message": "id foo was not removed: user does not exist"
}

Where:

POST /sync/rotate Input

This endpoint is called to rotate the custom producer secret payload.

POST /sync/rotate
{
    "payload": "secret data stored by Akeyless"
}

Where:

POST /sync/rotate Output

HTTP 200 OK
{
    "payload": "new payload to replace the existing one"
}

Where:

👍

Note

Payload rotation is performed on a best-effort basis. The rotation process could fail, and even after a successful /sync/rotate request the dynamic secret could still use the old payload. For these cases, the custom dynamic secret implementation should support both the old payload and the new payload until there is at least one /sync/create or /sync/revoke request that uses the old payload.

Authentication

Custom dynamic secret implementations should only handle requests made by a known Akeyless Gateway instance. Every request made by Akeyless to a custom dynamic 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-producer-foo",
}

Where:

Dry-Run Mode

When you define a custom dynamic secret in the Akeyless Gateway, the gateway makes several requests to the endpoints used in the configuration to ensure that the configuration is correct. These dry-run requests include the configured secret payload and empty user input, and all use the p-custom user access ID. Dry-run requests are authenticated using an Akeyless Gateway access ID.

Ensure that your custom dynamic secret implementation can handle these requests without failing, even though there is no user or user input, and return a Success response that includes a predefined ID.

This ID is sent to the POST /sync/revoke endpoint, which should also be configured to handle dry-run mode correctly.

Create a Custom Dynamic Secret from the CLI

Once you have a custom dynamic implementation that follows these specifications, create a new custom dynamic secret from the Akeyless CLI.

To create a custom dynamic secret from the CLI, run the following command:

akeyless dynamic-secret create \
--name <Dynamic Secret Name> \
--gateway-url 'https://<Your-Akeyless-GW-URL:8000>' \
--create-sync-url 'https://example.com/sync/create:Port' \
--revoke-sync-url 'https://example.com/sync/revoke:Port' \
--revoke-sync-url 'https://example.com/sync/rotate:Port'

Where:

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

• gateway-url: Akeyless Gateway Configuration Manager URL (port 8000).

• create-sync-url: The URL of an endpoint that implements the /sync/create method.

• revoke-sync-url: The URL of an endpoint that implements the /sync/revoke method.

• rotate-sync-url: The URL of an endpoint that implements the /sync/rotate method.

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

👍

Note

To start working with dynamic secrets from the Akeyless Console, you need to configure the Gateway URL thus enabling communication between the Akeyless SaaS and the Akeyless Gateway.

To create and fetch dynamic secrets directly from the Akeyless Gateway, you can use the Gateway Configuration Manager.

Usage Examples

You can find examples of custom dynamic secret implementations in this GitHub Repository.

The repository includes sample authentication code, deployment examples (using a docker image, or AWS Lambda function, or similar) and actual dynamic secret implementations, such as Let’s Encrypt.