Custom Rotated Secret

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 (for example, https://my.web.server/rotate).

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 with the CLI

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

akeyless rotated-secret create custom \
--name <Rotated Secret name>
--gateway-url 'https://<Your-Akeyless-GW-URL>:8000' \
--target-name <Web Target item name> \
--authentication-credentials <use-user-creds> \
--password-length 16
--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 (port 8000).

• 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, should be custom.

• custom-payload: A JSON string sent with every rotation request to your rotator endpoint. Include any static context your implementation needs, such as a username, system identifier, or application-specific metadata. Adapt field names to match your rotator endpoint's expected schema. For example:

  • Password-only rotation (rotates the password for a known, fixed username): {"username": "svc-reporting", "system": "my-app"}
  • Username and password rotation (passes the current password so the rotator can authenticate, then rotates both credentials): {"username": "svc-reporting", "current_password": "<current-value>", "system": "my-app"}

• custom-password-policy[=false]: A boolean flag to set the policy for the rotated password, the endpoint must provide a new password according to the following settings:

  • password-length: Password length.
  • PasswordLowercaseChar: A boolean flag specifies whether the generated temporary password must contain at least one lowercase character from the ISO basic Latin alphabet (a to z).
  • PasswordUppercaseChar: A boolean flag specifies whether the generated temporary password must contain at least one uppercase character from the ISO basic Latin alphabet (A to Z).
  • PasswordRequireNumbers: A boolean flag specifies whether the generated temporary password must contain at least one numeric character (0 to 9)
  • PasswordRequireSymbols: A boolean flag specifies whether the generated temporary password must contain at least one of non-alphanumeric characters. For example, "! @ # $".

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

Use a Custom Rotated Secret with Secure Remote Access (SRA)

Use this pattern when you want users to connect through Akeyless Secure Remote Access while the credential is still rotated by your custom rotator endpoint.

Prerequisites

• SRA is deployed and reachable in your environment. See Remote Access Setup Overview.
• Users can access the SRA portal or client flow. See Secure Remote Access Portal.
• Your custom rotated secret is already working with a reachable Web Target and successful rotation flow.

Recommended Flow

1. Create and validate the custom rotated secret first (without SRA settings).
2. Enable SRA-related settings on the rotated secret item.
3. Validate user connectivity through SRA and confirm rotation behavior after sessions, if configured.

Common SRA Flags for rotated-secret create custom

The following flags are commonly used when enabling SRA for a custom rotated secret:

• --secure-access-enable: Enables Secure Remote Access for the item.
• --rotate-after-disconnect: Rotates the secret after an SRA session ends.
• --secure-access-bastion-issuer: Sets the SSH certificate issuer path for bastion use cases.
• --secure-access-web: Enables web SRA access for supported scenarios.
• --secure-access-web-browsing: Enables isolated browser access by way of Akeyless Web Access Bastion.
• --secure-access-web-proxy: Enables web proxy access by way of Akeyless Web Access Bastion.
• --secure-access-host: Specifies target hosts for SRA connections.

For exact syntax and parameter behavior, use CLI Reference - Rotated Secrets (custom).

Example: Enable SRA on a Custom Rotated Secret

akeyless rotated-secret create custom \
--name reporting-app-svc \
--gateway-url 'https://gw.internal.example.com:8000' \
--target-name my-rotator-target \
--authentication-credentials use-user-creds \
--password-length 16 \
--rotator-type custom \
--custom-payload '{"username":"svc-reporting","system":"reporting-app"}' \
--auto-rotate true \
--rotation-interval 30 \
--secure-access-enable true \
--rotate-after-disconnect true \
--secure-access-host app01.internal.example.com

ℹ️

Note: The --sra-association flag in target association workflows is documented as relevant to LDAP rotated secret associations. For custom rotated secrets, use the custom command SRA flags and validate behavior in your environment.

Working Example: Rotate an On‑Premises Application Password by way of Web Target (Customer R/S)

This section provides an end-to-end, working example of creating a customer Rotated Secret (R/S) using a Web Target and a customer-managed rotator endpoint.

Scenario: You have an on‑premises application that uses a local service account svc-reporting. You want Akeyless to rotate that password on a schedule. Because the application is not natively integrated, you expose an internal HTTPS endpoint that can update the password in the application.

Architecture & Flow (High Level)

1. Akeyless Gateway triggers rotation (scheduled or manual).
2. Gateway calls the Web Target endpoint (your rotator service).
3. Rotator service:
   • Validates AkeylessCreds JWT (recommended).
   • Authenticates to the on‑premises app/admin API using the current credential.
   • Sets a new password.
4. Rotator service returns the new password to Akeyless.
5. Akeyless stores a new secret version; applications retrieve the latest value.

Prerequisite

A rotator service must be created that the Akeyless Gateway can call by HTTPS endpoint. The creation and maintenance of the rotator service is dependent on the application and your responsibility.

Step 1: Create the Web Target (Example)

akeyless create-web-target -n my-rotator-target -u https://rotator.internal.example.com/rotate

Step 2: Implement the Rotator Endpoint (Guidance)

Your rotator endpoint must:

• Accept HTTPS requests from the gateway
• Validate the AkeylessCreds JWT (recommended)
• Perform the actual rotation in the target system
• Return a success response with the new rotated value

Request Validation (Recommended)

Every request includes:

• Header: AkeylessCreds: <jwt>

Validate the JWT using:

POST auth.akeyless.io/validate-producer-credentials
{
  "creds": "<redacted jwt token>",
  "expected_access_id": "<gateway-access-id>",
  "expected_item_name": "/<path-to-rotated-secret>"
}

Step 3: Create the Custom Rotated Secret (Example)

This example creates a rotated secret named reporting-app-svc and enables auto-rotation every 30 days.

akeyless rotated-secret create custom \
--name reporting-app-svc \
--gateway-url 'https://gw.internal.example.com:8000' \
--target-name my-rotator-target \
--authentication-credentials use-user-creds \
--password-length 16 \
--rotator-type custom \
--custom-payload '{
  "username": "svc-reporting",
  "current_password": "<current-value>",
  "system": "reporting-app"
}' \
--auto-rotate true \
--rotation-interval 30

Step 4: Test and Verify

1. Confirm the rotated secret item exists in Akeyless.
2. Trigger a rotation according to your operational procedure.
3. Verify:
   • A new version is created in Akeyless.
   • The on‑premises application accepts the new password.
4. Ensure the rotator endpoint logs show:
   • JWT validation succeeded
   • Password change succeeded
   • Response returned to gateway (do not log plaintext secrets)