Verify Password

Overview

Verify Password lets GAccess confirm that a stored credential — a password or SSH key — still matches the actual configuration on the target system. It does this without making any changes, so it is safe to run at any time. Use this feature to detect credential drift caused by out-of-band changes, enforce compliance requirements, or diagnose access failures before they impact users.

How it works

When a verification is triggered, GAccess creates a verify job and routes it to a Gateway that can reach the target system. The Gateway retrieves the credential — which is transmitted in encrypted form — and attempts to authenticate against the target using the appropriate protocol (SSH, SMB, or LDAPS). It does not open a shell or perform any action after authenticating; authentication success or failure is the only outcome it measures.

The result is written back to the credential as a sync state: in_sync if authentication succeeded, out_of_sync if the credential was explicitly rejected, or unknown if the infrastructure itself could not be reached. The credential record is updated with a timestamp and, on failure, the reason code.

Verification can be triggered manually at any time by an administrator, or run automatically on a schedule defined by a Verification Policy attached to the credential.

Prerequisites

Before running a verification, confirm the following are in place:

Permissions

• You must have the manage permission on the credential you want to verify.

Credential requirements

• The credential type must not be Application. Application credentials do not support verification.
• For Local and Private Key credential types, exactly one server must be associated with the credential. Credentials with zero or more than one associated server cannot be verified.
• The credential must not be in a paused state (sync.pausedUntil must not be set to a future time). If paused, manual verification returns HTTP 429 until the pause expires or is cleared.

Gateway requirements

• At least one Gateway must be available and reachable by GAccess.
• For Domain credentials: at least one Gateway with the Account Discovery module enabled must be online.
• For Local and Private Key credentials: at least one Gateway whose configured CIDR routes cover the target server's IP address must be online.

Scheduled verification

• To enable automatic scheduled verification, a Verification Policy must be attached to the credential. Without a policy, only manual verification is available.

Admin Guide

Supported credential types and verification methods

Configuring a Verification Policy

A Verification Policy controls how often scheduled verification runs and when GAccess stops retrying after repeated failures. Attach a policy to a credential to enable scheduled verification.

The fields that affect verification behaviour are:

Gateway requirements per credential type

Gateway selection is automatic. GAccess picks the most appropriate Gateway based on the credential type:

• Domain credentials — Any Gateway with the Account Discovery module enabled. GAccess does not require the Gateway to have a specific route to the domain controller; the Gateway itself resolves the DC.
• Local and Private Key credentials — The Gateway whose CIDR route table best covers the target server's IP address (longest-prefix match). If no Gateway has a matching route, the job cannot be dispatched and the verify attempt returns an error.

If no suitable Gateway is available at the time a verify job is created, the job is rejected immediately with HTTP 400.

Understanding sync states

The sync.state field on a credential reflects the most recent known result of verification.

Account lockout protection

GAccess includes a lockout protection mechanism to prevent repeated verification attempts from locking out an account on the target system.

How it works:

Every failed verification — whether caused by an authentication rejection or a network error — increments the sync.consecutiveFailures counter on the credential. When the counter reaches the configured threshold, GAccess automatically pauses verification for that credential for 24 hours.

When a credential is paused:

• sync.pausedUntil is set to 24 hours from the moment the threshold was reached.
• All pending verify jobs for the credential are cancelled immediately.
• Any new manual verify attempt returns HTTP 429, including the pausedUntil timestamp in the response.
• The scheduler skips the credential until pausedUntil expires.

Thresholds:

• Credentials without an attached Verification Policy: 2 consecutive failures trigger a 24-hour pause.
• Credentials with an attached Verification Policy: the policy's Max Consecutive Failures value (default 3, range 1–10) is used.

Resuming early:

An administrator with manage permission on the credential can clear the pause before the 24 hours elapse by calling:

POST /credentials/:id/resume-verification

This clears sync.pausedUntil and resets sync.consecutiveFailures to 0. Scheduled verification resumes on the next scheduler cycle; manual verification becomes available immediately.

Scheduled verification behaviour

When a Verification Policy is attached to a credential, the GAccess scheduler creates verify jobs automatically.

Normal flow:

1. The scheduler runs periodically and checks whether verification.nextVerificationAt <= now.
2. If the condition is met and no rotation or verify job is already pending or running, a new verify job is created with triggerType: "scheduled".
3. verification.nextVerificationAt is advanced by the policy interval.
4. The Gateway polls for and claims the job, executes the verification, and reports the result.

Retry and backoff on failure:

When a scheduled verify job fails, GAccess does not immediately retry. Instead, it re-queues the job with an exponential backoff delay:

The formula is min(2^attempt × 5, 120) minutes. Backoff-scheduled jobs are only claimed by the Gateway after their scheduled time; the Gateway's poll endpoint skips jobs where createdAt > now.

Pause after repeated failures:

Retries continue until consecutiveFailures reaches the policy's Max Consecutive Failures threshold. At that point, the credential is paused for 24 hours as described in the Account lockout protection section above.

User Guide

Running a one-time verify

Use this when you want to immediately check whether a credential is still valid — for example, after a suspected out-of-band change or before granting access to a sensitive system.

1. Navigate to Privileged Access → Credentials and open the credential you want to check.
2. Confirm you have the manage permission on the credential (the Verify action will be visible if you do).
3. Click Verify Password (or Verify Key for SSH key credentials).
4. GAccess creates a verify job and the credential's sync state changes to verifying.
5. Wait for the job to complete. Depending on network conditions and the target system, this typically takes a few seconds. Refresh the credential view to see the updated sync state.
6. Review the result. See Interpreting the result below.

Interpreting the result

After a verify job completes, the credential displays one of the following sync states:

The credential detail view also shows:

• Last verified at: when the most recent successful or failed verification completed.
• Reason: a normalised code explaining why verification failed (only present when state is out_of_sync or unknown).
• Reason detail: the raw error message from the Gateway, useful for diagnosing infrastructure issues.

What to do when a credential is out of sync

An out_of_sync state means the stored credential value does not match the target system. This usually happens because the password was changed outside of GAccess — for example, by a system administrator directly on the server.

Recommended steps:

1. Determine the current valid password or key for the account on the target system.
2. If GAccess manages rotation for this credential, trigger a Rotate operation to generate and set a new password automatically.
3. If the credential is managed manually, edit the credential in GAccess and update the stored value to match the current value on the target.
4. After updating, run another manual verification to confirm the credential is now in_sync.

What to do when verification is paused

A paused credential has reached its consecutive failure threshold and will not be verified again — either manually or by the scheduler — until the pause expires or is cleared.

What you will see:

• The sync state shows the last known state (out_of_sync or unknown) along with a pausedUntil timestamp.
• Attempting to run a manual verify returns an error indicating the credential is paused and showing when the pause expires.

Options:

1. Wait for the pause to expire. The pause lasts 24 hours from the moment the threshold was reached. Scheduled verification resumes automatically.

2. Resume early. If you have manage permission on the credential, you can clear the pause immediately. Go to the credential detail view and click Resume Verification, or use the API:

   POST /credentials/:id/resume-verification

   This resets consecutiveFailures to 0 and clears pausedUntil. Verification becomes available again immediately.

Troubleshooting

Reference

Sync state reference

Error reason reference

Retry backoff schedule

Applies to scheduled verify jobs only. Manual (ad-hoc) jobs are not retried.

Formula: min(2^attempt × 5, 120) minutes. Retries stop when consecutiveFailures reaches the Max Consecutive Failures threshold defined on the attached Verification Policy. At that point the credential is paused for 24 hours.