Akeyless supports rotated 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 rotated secret implementation that calls the service on-demand to rotate secrets.

Akeyless communicates with custom rotated secret implementations over HTTP, and delegates rotate operation to the external services using a particular set of HTTP endpoint that follow a specific input/output format.

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

Set Up a Custom Rotated Secret Implementation

First, you need to create a Web Targets in Akeyless. This target holds the target endpoint of your application. e.g. https://my.web.server/rotate endpoint.

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

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

📘
Note:
Custom rotated secret implementations should only handle requests made by 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.

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-rotated-foo",
}

where:

Field	Description	Example
creds	A temporary JWT token issued and signed by Akeyless that is included in the `AkeylessCreds` header of every 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 rotated secret. This can be helpful if a single Akeyless Gateway runs multiple custom rotated secrets, and the custom rotated secret implementation should only respond to one of them.	`"/custom-rotated-foo"`

Create a Custom Rotated Secret

Run the following CLI command:

akeyless create-rotated-secret -n <Rotated Secret name> -r <Web Target item name> --rotator-type custom --custom-payload <Secret payload to be sent with rotation request>

Options

The full list of options for this command is:

-n, --name                                 *Secret name
  -r, --target-name                          *The target name to associate
  -u, --gateway-url[=http://localhost:8000]   API Gateway URL (Configuration Management port)
  -m, --metadata                              Metadata about the secret
  -t, --tag                                   List of the tags attached to this secret. To specify multiple tags use argument multiple times: -t Tag1 -t Tag2
  -k, --key                                   The name of a key that used to encrypt the secret value (if empty, the account default protectionKey key will be used)
      --auto-rotate                           Whether to automatically rotate every --rotation-interval days, or disable existing automatic rotation
      --rotation-interval                     The number of days to wait between every automatic rotation (1-365),custom rotator interval will be set in minutes
      --rotation-hour                         The Hour of the rotation in UTC
      --rotator-type                         *The rotator type password/target/api-key/custom
      --rotator-creds-type[=use-self-creds]   The credentials to connect with use-self-creds/use-target-creds
      --rotator-custom-cmd                    Custom rotation command (relevant only for ssh target)
      --ssh-username                          ssh username - deprecated, replace by rotated-username
      --ssh-password                          ssh password to rotate - deprecated, replace by rotated-password
      --api-id                                API ID to rotate (relevant only for rotator-type=api-key)
      --api-key                               API key to rotate (relevant only for rotator-type=api-key)
      --rotated-username                      username to be rotated, if selected "use-self-creds" at rotator-creds-type, this username will try to rotate its own password, if "use-target-creds" is selected, target credentials will be use to rotate the rotated-password (relevant only for rotator-type=password)
      --rotated-password                      rotated-username password (relevant only for rotator-type=password)
      --custom-payload                        Secret payload to be sent with rotation request (relevant only for rotator-type=custom)
      --profile                               Use a specific profile from your $HOME/.akeyless/profiles/ folder
      --username                              Optional username for various authentication flows
      --password                              Optional password for various authentication flows
      --uid-token                             The universal identity token, Required only for universal_identity authentication
  -h, --help                                  display help information
      --json[=false]                          Set output format to JSON
      --no-creds-cleanup[=false]              Do not clean local temporary expired creds

Inputs

Set Up a Custom Rotated Secret Implementation

📘Note:

Authentication

Create a Custom Rotated Secret

📘
Note: