Rate this page

Account

The Ping Identity Data Governance Broker’s account sub-resource allows a privileged client to read and modify aspects of a user’s account state. Account state properties are governed by the Ping Identity Directory Server acting as the Data Governance Broker’s user store; they generally concern a user’s ability to authenticate and complete a login. Please consult the Ping Identity Security Guide for more information about account state.

The following table describes the possible fields of an account resource.

Field Type Provided? Description
schemas array always The SCIM schema of the account resource. Always has the value urn:pingidentity:schemas:2.0:AccountState.
meta complex always Will always contain a resourceType sub-attribute with the value Account State. Will always contain a location attribute with the account resource’s canonical URI.
accountDisabled boolean True if the account is disabled, or false if not. Set to null to clear.
accountExpirationTime dateTime Time of account expiration. Set to null to clear.
secondsUntilAccountExpiration number The number of seconds until the account is marked as expired. Read-only.
passwordChangedTime dateTime Password changed time. Set to null to clear.
passwordExpirationWarnedTime dateTime Password expiration warned time. Set to null to clear.
secondsUntilPasswordExpiration number The number of seconds until the password will expire. Read-only.
secondsUntilPasswordExpirationWarning number The number of seconds until a password expiration warning is returned with authentication responses. Read-only.
authenticationFailureTimes dateTime The timestamps of previous authentication failures. Set to [] (empty array) to clear.
secondsUntilAuthenticationFailureUnlock dateTime The number of seconds until the account is unlocked following an automatic lockout due to authentication failures. Read-only.
remainingAuthenticationFailureCount number Remaining authentication failure count. Read-only.
lastLoginTime dateTime The timestamp of the account’s last login. Set to null to clear.
secondsUntilIdleLockout number The number of seconds until the account is locked due to inactivity. Read-only.
mustChangePassword boolean Must change password. Set to null to clear.
secondsUntilPasswordResetLockout number The number of seconds until password reset lockout. Read-only.
graceLoginTimes array Times of previous grace logins. Set to [] (empty array) to clear.
remainingGraceLoginCount number Remaining grace login count. Read-only.
passwordChangedByRequiredTime dateTime Password change by required time. Set to null to clear.
secondsUntilRequiredChangeTime number The number of seconds until a password change is required. Read-only.
retiredPassword complex Retired password information; see the table below. A retired password is a password that remains usable for some period of time after a new password has been set. Set to null to clear.
accountActivationTime dateTime Time of account activation. Set to null to clear.
accountUsabilityNotices array A list of one or more account usability notices. See below for details. Read-only.
accountUsabilityWarnings array A list of one or more account usability warnings. See below for details. Read-only.
accountUsabilityErrors array A list of one or more account usability errors. See below for details. Read-only.

Retired passwords

The following table describes the fields of a retired password object.

Field Type Provided? Description
passwordRetiredTime dateTime always The time that the password was retired.
passwordExpirationTime dateTime always The expiration time of the password.

Account usability issues

Account usability issues provide useful summary information about an account state. The following table describes the fields of account usability notice, warning, and error objects.

Field Type Provided? Description
name string always The account usability issue type.
message string always A human-readable description of the account usability issue.

Account usability notices may have the following name values:

Name Description
outstanding-retired-password The user user has a valid outstanding retired password.
outstanding-one-time-password The user user has a valid outstanding one-time password that was issued by the user store.
outstanding-password-reset-token The user user has a valid outstanding password reset token that was issued by the user store.

Account usability notices may have the following name values:

Name Description
account-expiring The user’s account is about to expire.
password-expiring The user’s password is about to expire.
outstanding-bind-failures The user has had one or more failed authentication attempts since the last successful bind; the account may be locked if there are too many more failures.
account-idle The user has not authenticated in some time, and the account may be locked in the near future if it remains idle.
require-password-change-by-time The user user will be required to change his or her password by a specific time, because the password policy requires all users to change their passwords by that time.

Account usability errors may have the following name values:

Name Description
account-disabled The user’s account is disabled.
account-not-yet-active The user’s account is not yet valid.
account-expired The user’s account is expired.
account-permanently-locked-due-to-bind-failures The user’s account is permanently locked (until the password is reset by an administrator) as a result of too many failed authentication attempts.
account-temporarily-locked-due-to-bind-failures The user’s account is temporarily locked (until the lockout period elapses or the password is reset by an administrator) as a result of too many failed authentication attempts.
account-idle-locked The user’s account is locked (until the password is reset by an administrator) as a result of remaining idle for too long (i.e., it has been too long since the user last authenticated).
account-reset-locked The user’s account is locked (until the password is reset by an administrator) as a result of failing to change the password in a timely manner after it was reset by an administrator.
password-expired The user’s password is expired.
password-not-changed-by-required-time The user’s account is locked (until the password is reset by an administrator) as a result of failing to change the password by a required time.
password-expired-with-grace-logins The user’s password has expired, but the user has one or more grace logins remaining. The user may still authenticate with a grace login, but will not be permitted to submit any other requests until changing the password.
must-change-password The user must change their password after an administrative reset (or for a newly-created account) before they will be submit any requests. The user’s account may be locked if they do not change their password in a timely manner.

Retrieve a user’s current account state

GET /scim/v2/Users/{id}/account

GET /scim/v2/Me/account

This retrieves a user’s current account state.

Example request:

GET /scim/v2/Users/2b61e834-2c60-4d11-969d-acf29c6e7997/account HTTP/1.1
Accept: application/scim+json
Accept-Encoding: gzip, deflate
Authorization: Bearer eyJhbGci...
Content-Type: application/scim+json
Host: example.com:443

Example response:

HTTP/1.1 200 OK
Content-Length: 379
Content-Type: application/scim+json
Date: Tue, 26 Jul 2016 13:50:59 GMT

{
    "accountDisabled": true, 
    "accountUsabilityErrors": [
        {
            "message": "The account has been disabled by an administrator", 
            "name": "account-disabled"
        }
    ], 
    "meta": {
        "location": "https://example.com:443/scim/v2/Users/2b61e834-2c60-4d11-969d-acf29c6e7997/account", 
        "resourceType": "Account State"
    }, 
    "mustChangePassword": false, 
    "passwordChangedTime": "2016-07-25T22:31:21Z", 
    "remainingGraceLoginCount": 0
}

Update a user’s account state

PUT /scim/v2/Users/{id}/account

PUT /scim/v2/Me/account

A user’s account state may be updated using the PUT method. The client need not specify every account property; omitted properties will be ignored.

Example request:

PUT /scim/v2/Users/2b61e834-2c60-4d11-969d-acf29c6e7997/account HTTP/1.1
Accept: application/scim+json
Authorization: Bearer eyJhbGci...
Content-Type: application/scim+json
Host: example.com:443

{
    "accountDisabled": false
}

Example response:

HTTP/1.1 200 OK
Content-Length: 162
Content-Type: application/scim+json
Date: Tue, 26 Jul 2016 13:51:45 GMT

{
    "accountDisabled": false, 
    "meta": {
        "location": "https://example.com:443/scim/v2/Users/2b61e834-2c60-4d11-969d-acf29c6e7997/account", 
        "resourceType": "Account State"
    }
}