Rotate secrets

This section describes how Conjur uses rotation to manage secrets locally on a Conjur Server, or in a development environment.


Secrets, like passwords, are always susceptible to attack, and the longer a secret remains unchanged, the more vulnerable it becomes. The way to mitigate any risk of compromise is to use a complex secret and to change it often. The Conjur rotation feature meets this requirement by automatically generating and rotating the secrets used to access an underlying system.

Regenerated secret values are contained in variables stored in Conjur. The rotation mechanism also updates the corresponding secrets in the target system -- a database password, for example, or an AWS API key, this way protecting the target system.

All secrets are declared as variables in policy. Annotations on the variable configure the specific rotator to use and the time-to-live (TTL) duration of a value. At each time-to-live interval, the old value expires and Conjur assigns a new automatically generated value.

How rotation works

Many secrets require rotation, including passwords, keys, and certificates. Rotation includes updating the secret value on the target system, and for that, Conjur needs access to the targets. Each target type has its own rotator. Rotator configuration occurs in policy, as annotations on the variable.

A rotator replaces the value of an expired variable with a new, automatically generated value.


To perform secret rotation on a target system, Conjur needs to have access to a credential with sufficient privilege to perform a password reset or update on the target system. The details of how this works varies from target to target, but there are two common patterns:

  • An administrative credential for the target system is loaded into a Conjur variable. This admin credential is used by the rotator to change the password of any user or account in the target system, and store the new password in the rotated variable.

    For example, a cloud 'root' account can be used to manage the authentication credentials of any other cloud account.

  • The password in the rotated variable is powerful enough itself to perform a password reset or update in the target system. For example, database user accounts can generally change their own password (but not the password of other database users).

The second pattern is preferable, because it does not require Conjur to store a 'super user' password for the target system. Of course, if Conjur does store a super user password, this password may itself be rotated.


Rotation is enabled by adding these annotations to a variable:




How long a variable uses the same value before rotation (time-to-live), ISO8601 duration.


The name of the rotator to be used for a rotation.

For duration, Conjur relies on the standard duration format defined by ISO8601. It establishes the amount of intervening time in a time interval. For example, P1D represents a duration period (P) of one (1) day (D).

Generally, the ISO8601 format can designate durations in terms of years, months, weeks, days, time, hour, minute, and second. Refer to the Wikipedia page on ISO8601 durations for a complete explanation.

Some rotators may require additional annotations.

Conjur includes a number of pre-built rotators for integrated rotation functionality. For information about currently available rotators in Conjur and their requirements, see Rotators below.

Initial rotation

After annotating a variable for rotation, the variable must be set with an initial value to trigger the start of rotation. This initial setting of a rotating variable causes that variable to rotate immediately (within 1 second) to a new value. You can consider this the handoff to the rotator. After this, the variable is rotated automatically based on its rotation/ttl annotation. You can set the initial value for a rotation variable with the Conjur API.


             def rotate
    conjur_url = Conjur.configuration.appliance_url
    account = Conjur.configuration.account
    var_name = params['id']
    token = Base64.strict_encode64(api.token.to_json)
      :Authorization => "Token token=\"#{token}\""


The following rotators are supported.