PAM › Admin Guide

Rotating Credentials

Automatically generate and apply new credentials to target systems, keeping the vault in sync

Rotating Credentials

How it works

When a rotation is triggered, manually or by a scheduled policy, GAccess generates a new credential according to the rules defined in the attached Rotation Policy (or built-in defaults if no policy is attached), then applies the change to the target system.

Rotation methods by credential type

Credential Type Protocol How the credential is changed
Local — Windows SMB on port 445 Connects using the current credential and updates it to the new value
Domain LDAPS port 636, fallback LDAP 389 Connects to the domain controller using the Gateway's reconcile account and sets the new password via LDAP modify
Local — Linux SSH on port 22 (configurable) Authenticates with the current credential and changes the password using the passwd command
Private Key — Linux SSH on port 22 (configurable) Authenticates with the current key, adds the new public key to authorized_keys, and removes the old one
Warning: Make sure to set GAcess password policies aligned with your target password policies. As a rule of thumb, maintain GAccess password policies that are stronger than or equal to system password policies, to avoid rotation failures.

Crash-safe rotation

Rotation is designed to survive Gateway crashes and network interruptions without losing the new credential value.

Before touching the target system, GAccess stores the newly generated credential as a candidate value in the vault. If the Gateway crashes or loses connectivity between generating the credential and confirming the change, the candidate value is preserved. On recovery, GAccess can promote it without needing to generate a new one, ensuring the vault and the target stay in sync even across unexpected failures.

New credential generation

Credentials are generated according to the Password Rules or Key Rules defined in the attached Rotation Policy. For manual rotations on credentials without an attached policy, the following defaults apply:

Password defaults

Rule Default
Minimum length 16 characters
Uppercase letters Required
Lowercase letters Required
Numbers Required
Special characters Required (!@#$%^&*)
Excluded characters "

SSH Key defaults

Rule Default
Algorithm Ed25519

After a successful rotation

When rotation completes successfully, GAccess updates the credential record:

  • Credential value is replaced with the new credential.
  • Previous value is the old value retained for reference.
  • Last rotated at is set to the time the Gateway confirmed the change.
  • Sync state is set to in_sync and last verified at is updated.

Failure handling and retry

When a rotation fails, the candidate value is discarded, rotation.status is set to error, and consecutiveFailures is incremented.

Manual (ad-hoc) rotation jobs are not retried. If a manual rotation fails, the result is recorded and the job ends.

Scheduled rotation jobs use exponential backoff on failure. GAccess re-queues the job with an increasing delay before the next attempt:

Failure number Delay before retry
1st 10 minutes
2nd 20 minutes
3rd 40 minutes
4th 80 minutes
5th and beyond 120 minutes (maximum)

Retries continue until consecutiveFailures reaches the policy's Max Retries threshold.

Account lockout protection

The same pause mechanism used for verification applies to rotation. When consecutiveFailures reaches the configured Max Retries threshold, GAccess sets rotation.pausedUntil and cancels any pending rotation jobs. The default pause duration is 24 hours and can be configured in the Rotation Policy.

Configuration Max retries before pause Pause duration
No Rotation Policy attached 2 24 hours
Rotation Policy attached Defined by the policy (default: 3, range: 1–10) Defined by the policy (default: 24 hours)

An administrator can clear the pause early using the Resume Rotation action on the credential detail view. This resets consecutiveFailures to zero and makes the credential available for rotation immediately.

Before resuming, investigate the root cause to avoid immediately re-triggering the pause.