Skip to main content

Secret Rotation

This guide will help you set up your first automated secret rotation using Vault++.

Prerequisites​

  1. Have a Vault++ account.
  2. Have integrated Vault++ with CICD.
  3. Have an AWS, Azure, or GCP account to rotate.

Introduction​

To safely rotate secrets without disrupting your services, Vault++ performs secret rotation in three steps:

  1. Step 1 - Create New Credentials: Vault++ generates new credentials for your application. During this stage, both the new and existing credentials remain active.
  2. Step 2 - Deploy with New Credentials: Your application is deployed using the new credentials.
  3. Step 3 - Commit and Deactivate Old Credentials: Once deployment is complete (ensuring the old credentials are no longer in use), Vault++ commits the new credentials and deactivates the old ones.

All three steps are executed within the same deployment pipeline. This means the secret rotation process completes within your deployment time, rather than taking weeks or months waiting for eventual secret consistency.

Dynamic Secrets​

Dynamic secrets provide better protection against secret leaks by creating and revoking credentials as they are used. However, when used at scale, this approach can introduce challenges that may disrupt service availability. A rate limit or a brief outage from the upstream provider could prevent your service from starting properly.

With Vault++'s fast rotation speed (minutes instead of weeks or months), secret rotations can be seamlessly integrated into your deployment pipeline. As a result, your application will use a new secret with every deployment, enabling it to scale smoothly without the risk of disruption—providing the same level of protection as dynamic secrets, without the drawbacks.

1. Update CICD to add rotations​

Open your workflow file containing workflow_dispatch with Vault++ integration, and add the following highlighted sections:

.github/workflows/example-app.yaml
name: Deploy App
on:
  push:
    branches:
      - main
  workflow_dispatch:
    inputs:
      action:
        required: true
        type: choice
        options:
          - sync
          - rotate
      environment:
        type: environment
        required: true
jobs:
  deploy:
    name: Build and Deploy App
    # Environment is only available on GitHub paid plans.
    environment: ${{ inputs.environment || 'staging' }}
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: vaultplusplus/setup@latest

      # Step 1 - Create New Credentials
      # Put this step prior to all "vpp export" command in the pipeline
      - if: inputs.action == 'rotate'
        run: vpp rotate begin ${{ inputs.environment || 'staging' }}
        env:
          VPP_SERVICE_ACCOUNT_KEY: ${{ secrets.VPP_SERVICE_ACCOUNT_KEY }}
          VPP_SERVICE_ACCOUNT_PASSWORD: ${{ secrets.VPP_SERVICE_ACCOUNT_PASSWORD }}

      # This export will use the new rotated secret
      - id: vpp
        run: vpp export --include CI_ -o github --env=${{ inputs.environment || 'staging' }} $GITHUB_OUTPUT
        env:
          VPP_SERVICE_ACCOUNT_KEY: ${{ secrets.VPP_SERVICE_ACCOUNT_KEY }}
          VPP_SERVICE_ACCOUNT_PASSWORD: ${{ secrets.VPP_SERVICE_ACCOUNT_PASSWORD }}
      
      ## some build steps...
      - run: make build

      # This export will use the new rotated secret
      - run: vpp export --exclude=CI_ --output=json --env=${{ inputs.environment || 'staging' }} secrets.json
        env:
          VPP_SERVICE_ACCOUNT_KEY: ${{ secrets.VPP_SERVICE_ACCOUNT_KEY }}
          VPP_SERVICE_ACCOUNT_PASSWORD: ${{ secrets.VPP_SERVICE_ACCOUNT_PASSWORD }}

      # Step 2 - Deploy with New Credentials
      - run: make deploy

      # Wait for the deployment to complete and ensure the old application version is no longer active.
      # Please refer to your platform-specific guide to ensure that old deployments are deactivated before proceeding.
      - if: inputs.action == 'rotate'
        run: make wait-until-live

      # Step 3 - Commit and Deactivate Old Credentials
      - if: inputs.action == 'rotate'
        run: vpp rotate commit
        env:
          VPP_SERVICE_ACCOUNT_KEY: ${{ secrets.VPP_SERVICE_ACCOUNT_KEY }}
          VPP_SERVICE_ACCOUNT_PASSWORD: ${{ secrets.VPP_SERVICE_ACCOUNT_PASSWORD }}

2. Create required credentials​

Secret rotations involve two types of credentials: a rotator and a target credential. A rotator credential is used by Vault++ to rotate the target credential. When granted sufficient permissions, Vault++ will also rotate the rotator credential.

To create the required credentials to rotate secrets, follow these steps:

1.1. Create the target credential​

Skip this step if you already have a target credential to rotate.

  1. Navigate to the AWS Console and open the IAM page.

  2. Click Users under the Access Management section.

  3. Click the Create user button.

  4. Follow the steps and assign the necessary permissions required by your application.

1.2. Create the rotator policy​

  1. In the AWS IAM Page, click Policies under the Access Management section.

  2. Click the Create policy button.

  3. Click the JSON tab to switch to the JSON editor.

  4. Add the following policy, replacing the highlighted line with the target credential ARN:

    {
        "Version": "2012-10-17",
        "Statement": [
            {
                "Sid": "AllowManageOwnAccessKeys",
                "Effect": "Allow",
                "Action": [
                    "iam:CreateAccessKey",
                    "iam:DeleteAccessKey",
                    "iam:ListAccessKeys",
                    "iam:UpdateAccessKey",
                    "iam:GetAccessKeyLastUsed"
                ],
                "Resource": "arn:aws:iam::*:user/${aws:username}"
            },
            {
                "Sid": "AllowManageTargetAccessKeys",
                "Effect": "Allow",
                "Action": [
                    "iam:CreateAccessKey",
                    "iam:DeleteAccessKey",
                    "iam:ListAccessKeys",
                    "iam:UpdateAccessKey",
                    "iam:GetAccessKeyLastUsed"
                ],
                "Resource": "arn:aws:iam::*:user/REPLACE-THIS-WITH-TARGET-ARN"
            }
        ]
    }

  5. Click Next, enter a policy name (e.g. APIDeployRotator).

  6. Click Create policy to create the policy.

1.3. Create the rotator credential​

  1. In the AWS IAM Page, click Users under the Access Management section.
  2. Click the Create user button.
  3. Enter a user name and click Next.
    tip

    We recommend providing a name that links to the target credential (e.g., api-deploy-rotator) for easier administration.

  4. Select Attach policies directly and choose the policy created in the step 1.2.
  5. Follow the remaining steps to complete the user creation process.

3. Add credential to Vault++​

Follow these steps to add the credential created in the previous step to Vault++:

  1. In a new tab, navigate to Vault++ and open your application.

  2. Select a live environment, e.g., staging.

  3. Click the Add () button and select New rotating secret.

  4. Select AWS.

  5. Enter environment keys for AWS Access Key ID and AWS Secret Access Key, e.g., AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY.

  6. Press Enter.

  7. Switch to the AWS Console tab, find the target credential and click on it.

  8. Copy the ARN into the Target User ARN field in Vault++.

  9. Back to the AWS Console tab, find the rotator credential and click on it.

  10. Click the Security credentials tab.

  11. Click the Create access key button.

  12. Select Other in the use case selection.

  13. Follow the steps until you receive an access key and its secret key.

  14. Copy the access key into the AWS Access Key ID field in Vault++.

  15. Copy the secret key into the AWS Secret Access Key field in Vault++.

  16. Click the Save () button.

Upon saving your rotation, Vault++ will trigger a rotation pipeline in your CICD. Once the pipeline completes, your application will start using the new credentials, and the old credentials will be deactivated.

You can manually trigger a rotation from your CICD pipeline or by clicking the Rotate secret option located to the right of the gear icon next to the secret value.

Rotate local environment​

To rotate secrets in the local environment, you do not need to use CICD. You can run the following command on your local machine to automatically rotate and commit secrets to Vault++:

vpp rotate local