PAM › Admin Guide

Verifying Credentials

Confirm that a stored credential still matches the target system without making any changes

Verifying Credentials

How it works

When a verification is triggered, manually or by a scheduled policy, GAccess creates a verify job and routes it to an appropriate Gateway based on the target IP address. The Gateway retrieves the encrypted credential, decrypts it locally, and attempts to authenticate against the target using the appropriate protocol. It does not open a shell or perform any action beyond authenticating; success or failure is the only outcome measured.

The result is reported back to GAccess and written to the credential as a sync state.

Verification methods by credential type

Credential Type	Protocol	How authentication is tested
Local — Windows	SMB on port 445	Opens a session using the stored credential
Domain	LDAPS port 636, fallback LDAP 389	Attempts an NTLM auto-bind to the domain controller
Local — Linux	SSH on port 22 (configurable)	Opens an SSH session using password authentication
Private Key — Linux	SSH on port 22 (configurable)	Opens an SSH session using key-based authentication

Sync states

After a verification job completes, the credential's sync state reflects the outcome:

State	Meaning
`in_sync`	Authentication succeeded. The stored credential matches the target system.
`out_of_sync`	Authentication was explicitly rejected. The credential does not match the target.
`unknown`	The target could not be reached. A network or infrastructure error prevented verification.
`verifying`	A verify job is currently running.

Both out_of_sync and unknown increment the credential's consecutiveFailures counter. The distinction matters for diagnosis: out_of_sync means the credential value is wrong; unknown means the infrastructure could not be reached and the stored value is still indeterminate.

The credential detail view also shows:

Last verified at — when the most recent verification completed.
Reason — a normalised code explaining why verification failed.
Reason detail — the raw error message from the Gateway, useful for diagnosing infrastructure issues.

Account lockout protection

GAccess includes a built-in mechanism to prevent repeated verification attempts from locking out accounts on the target system.

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

All pending verify jobs are cancelled immediately.
New manual verify requests are blocked until the pause expires or is cleared by an administrator.
The scheduler skips the credential until the pause elapses.

Thresholds:

Configuration	Max consecutive failures	Pause duration
No Verification Policy attached	2	24 hours
Verification Policy attached	Defined by the policy (default: 3, range: 1–10)	Defined by the policy (default: 24 hours)

Warning: Both authentication failures and infrastructure failures (timeouts, connection errors) count toward the threshold. A misconfigured Gateway that cannot reach the target will pause a credential just as quickly as a wrong password would.

Resuming a paused credential

An administrator with manage permission can clear the pause before it expires using the Resume Verification action on the credential detail view. This resets consecutiveFailures to zero and makes the credential available for verification immediately.

Before resuming, investigate the root cause. If the credential is out_of_sync, resuming without resolving the mismatch will cause an immediate failure that quickly re-triggers the pause.

Retry logic

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

Scheduled verify 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 Consecutive Failures threshold, at which point the credential is paused as described above.

Note: The nextVerificationAt timestamp advances by the policy interval when the scheduled job is first created, regardless of retries. A failing credential does not delay the next regular scheduled cycle.

Error reason reference

Reason code	Meaning	Recommended action
`auth_failed`	Credential explicitly rejected by the target. Password is wrong or SSH key is not authorised.	Update the stored value or rotate the credential.
`auth_key_format`	SSH private key is malformed or the passphrase is incorrect.	Re-upload a valid key and verify the passphrase.
`connection_timeout`	Connection attempt timed out before a response was received.	Check that the target is reachable from the Gateway on the expected port.
`connection_failed`	Host unreachable, port closed, or connection refused.	Verify the target is online and the relevant service (SSH, SMB, LDAPS) is running.
`dc_resolution_failed`	No domain controller could be resolved for the credential's domain.	Check the `DOMAIN_CONTROLLERS` Gateway configuration or DNS SRV records.
`unknown_error`	Unexpected error during verification.	Check the reason detail on the credential and review Gateway logs.