The Akeyless Dev Hub

If you're looking for help with the only zero-trust, SaaS, unified platform for secrets management - you've come to the right place.

This is our documentation and updates center.

Documentation

Custom Dynamic Secrets

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 producer implementation that calls the service on-demand to generate or revoke temporary secrets.

Akeyless communicates with custom producer 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 producer implementation, you can create a custom dynamic secret that calls the implementation to generate dynamic credentials.

Inputs

Custom producer 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 producer with every request.

In addition, some custom producer 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 producers.

Set Up a Custom Producer Implementation

Implement the following endpoints in order 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 producer 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:

Field

Description

Example

payload

(Optional) Secret credentials stored by Akeyless. You define these credentials when you set up the custom dynamic secret in the Akeyless Gateway.

mongodb://user:[email protected]

{"user":"foo","pass":"bar"}

input

(Optional) User input provided with the current get-dynamic-secret-value operation. This is a JSON object, and its format depends on the information provided by the user.

  "domain":"foo.example.com",
  "use_staging":true
}```

`{"project_id":42}`

client_info

Information about the user requesting the credentials. It includes the user's Akeyless access ID, as well as any sub-claims.

  "access_id": "p-1234",
  "sub_claims": {
    "claim1": ["value1"]
  }
}```

POST /sync/create Output

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

where:

Field

Description

Example

id

A unique identifier for the temporary credentials, which is required during a `POST /sync/revoke' operation.

tmp.user1234

f2fa1940-8d7e-41d4-a688-8d915795e88b

response

A JSON object that includes any fields required by the particular use case.

  "cert":"<redacted>",
  "private_key":"<redacted>"
}```

`{"password":"strongpassword!"}`

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:

Field

Description

Example

payload

(Optional) Secret credentials stored by Akeyless. You define these credentials when you set up the custom dynamic secret in the Akeyless Gateway.

mongodb://user:[email protected]

{"user":"foo","pass":"bar"}

ids

A list of IDs to revoke. These IDs were previously received in response to POST /sync/create operations.

["foo", "bar"]

POST /sync/revoke Output

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

where:

Field

Description

Example

revoked

A list of revoked IDs.

["foo", "bar"]

message

An optional message in case any of the specified IDs were not properly revoked. This field should only be used for error handling.

"id foo was not removed: user does not exist"

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:

Field

Description

Example

payload

Secret credentials stored by Akeyless. You define these credentials when you set up the custom dynamic secret in the Akeyless Gateway.

mongodb://user:[email protected]

{"user":"foo","pass":"bar"}

POST /sync/rotate Output

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

where:

Field

Description

Example

payload

New secret credentials to replace the existing credentials stored by Akeyless.

mongodb://user:[email protected]

{"user":"mun","pass":"goh"}

📘

Payload rotation is performed on a best-effort basis. Very rarely, the rotation process fails, and even after a successful /sync/rotate request, the producer uses the old payload. To defend against this scenario, the custom producer 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 new payload.

Authentication

Custom producer implementations should only handle requests made by a known Akeyless Gateway instance. Every request made by Akeyless to a custom producer 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:

Field

Description

Example

creds

A temporary JWT token issued and signed by Akeyless that is included in the AkeylessCreds header of every POST /sync/create and POST /sync/revoke request.

expected_access_id

The initial access ID used for the Akeyless Gateway (not the user credentials).

"p-1234"

expected_item_name

(Optional) The item name of the custom dynamic secret. This can be helpful if a single Akeyless Gateway runs multiple custom dynamic secrets, and the custom producer implementation should only respond to one of them.

"/custom-producer-foo"

Dry Run Mode

When you define a custom dynamic secret in the Akeyless Gateway, the gateway makes a number of requests to the endpoints used in the configuration to ensure that the configuration is correct. These dry run requests include the configured secret payload, 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 producer 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 correctly handle dry run mode.

Create a Custom Dynamic Secret from the CLI

Once you have a custom producer implementation that follows these specifications, create a new custom dynamic secret from the Akeyless CLI. If you’d prefer, see how to do this from the Akeyless Gateway instead.

The CLI command to create a custom dynamic secret is:

akeyless gateway-create-producer-custom --name dummy-producer --create-sync-url https://example.com/sync/create --revoke-sync-url https://example.com/sync/revoke --timeout-sec 30

Create a Custom Dynamic Secret from the Akeyless Gateway

Once you have a custom producer implementation that follows these specifications, create a new custom dynamic secret in the Akeyless Gateway.

  1. In the Akeyless Gateway, select Dynamic Secrets > New > Custom Producer.

  2. Give the producer a name, and define where it should be saved.

  1. Define the following parameters:

    • Create Webhook URL: An FQDN to the POST /sync/create endpoint. This should be a complete URI that includes the schema and port.

    • Revoke Webhook URL: An FQDN to the POST /sync/revoke endpoint. This should be a complete URI that includes the schema and port.

    • Webhook Wait Timeout: The amount of time, in seconds, to wait for a response from the custom producer implementation. The invocation will fail if a response is not received in this time.

    • Payload: (Optional) Data required for the create and revoke operations, such as credentials. The payload is encrypted at rest, and decrypted and sent to the Webhook just before it is invoked.

    • User TTL: The token expiration.

  2. Select Save.

Usage Examples

You can find examples of custom procedure 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 producer implementations, such as Let’s Encrypt.

Updated 2 months ago

Custom Dynamic Secrets


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.