Password Management

v1.0.0

The Password Management REST APIs provide a means to manage passwords and account state. Methods are provided for updating passwords, checking password quality requirements, generating one-time passwords, and retrieving account state information. All of these REST methods require bearer token authentication.

This API is currently experimental, and subsequent versions may not be backward compatible with this version. Users of this experimental version are encouraged to provide feedback for consideration in later versions of the API.

Methods

• get /scim/v2/ResourceTypes/{dataViewName}/passwordQualityRequirement Retrieves the password quality requirements for a new user. Requires 'Read' access to 'urn:unboundid:schemas:2.0:PasswordQualityRequirement' resource.

  Parameters

  Name	Type	Description	Required	Data Type
  dataViewName	path	The name of the Data View to use when retrieving the password quality requirements.	true	String

  Responses

  Code	Description	Response
  200	Success	PasswordQualityRequirementResponse

  Example Response

  Content-Type: application/json

  {\n  "currentPasswordRequired" : true,\n  "passwordRequirementResults" : [ {\n    "failureMessage" : "aeiou",\n    "requirementSatisfied" : true,\n    "display" : "aeiou",\n    "type" : "aeiou"\n  } ],\n  "mustChangePassword" : true,\n  "secondsUntilPasswordExpiration" : 123\n}

• get /scim/v2/{dataViewName}/{targetUserId}/account Gets account state information for a user. Requires 'Read' access to 'urn:unboundid:schemas:2.0:AccountState' resource.

  Parameters

  Name	Type	Description	Required	Data Type
  targetUserId	path	The ID of the user for whom account state information is retrieved.	true	String
  dataViewName	path	The name of the Data View to use when getting the user's account state information.	true	String

  Responses

  Code	Description	Response
  200	The user's account information.	AccountState

  Example Response

  Content-Type: application/json

  {\n  "graceLoginTimes" : [ "2015-06-02T14:19:02.721+0000" ],\n  "secondsUntilPasswordResetLockout" : 123,\n  "secondsUntilAuthenticationFailureUnlock" : 123,\n  "passwordChangedByRequiredTime" : "2015-06-02T14:19:02.721+0000",\n  "passwordExpirationWarnedTime" : "2015-06-02T14:19:02.721+0000",\n  "accountDisabled" : true,\n  "remainingAuthenticationFailureCount" : 123,\n  "remainingGraceLoginCount" : 123,\n  "passwordHistory" : [ "aeiou" ],\n  "secondsUntilRequiredChangeTime" : {\n    "passwordRetiredTime" : "2015-06-02T14:19:02.721+0000",\n    "passwordExpirationTime" : "2015-06-02T14:19:02.721+0000"\n  },\n  "accountExpirationTime" : "2015-06-02T14:19:02.721+0000",\n  "secondsUntilAccountExpiration" : 123,\n  "authenticationFailureTimes" : [ "2015-06-02T14:19:02.721+0000" ],\n  "passwordChangedTime" : "2015-06-02T14:19:02.721+0000",\n  "secondsUntilIdleLockout" : 123,\n  "mustChangePassword" : true,\n  "lastLoginTime" : "2015-06-02T14:19:02.721+0000",\n  "secondsUntilPasswordExpiration" : 123\n}

• put /scim/v2/{dataViewName}/{targetUserId}/account Sets account state information for a user. Requires 'Update' access to 'urn:unboundid:schemas:2.0:AccountState' resource.

  Parameters

  Name	Type	Description	Required	Data Type
  targetUserId	path	The ID of the user for whom account state information is set.	true	String
  dataViewName	path	The name of the Data View to use when setting the user's account state information.	true	String
  AccountState	body	The requested changes to the account state.	true	AccountState

  Responses

  Code	Description	Response
  200	The user's account information.	AccountState

  Example Response

  Content-Type: application/json

  {\n  "graceLoginTimes" : [ "2015-06-02T14:19:02.726+0000" ],\n  "secondsUntilPasswordResetLockout" : 123,\n  "secondsUntilAuthenticationFailureUnlock" : 123,\n  "passwordChangedByRequiredTime" : "2015-06-02T14:19:02.726+0000",\n  "passwordExpirationWarnedTime" : "2015-06-02T14:19:02.726+0000",\n  "accountDisabled" : true,\n  "remainingAuthenticationFailureCount" : 123,\n  "remainingGraceLoginCount" : 123,\n  "passwordHistory" : [ "aeiou" ],\n  "secondsUntilRequiredChangeTime" : {\n    "passwordRetiredTime" : "2015-06-02T14:19:02.726+0000",\n    "passwordExpirationTime" : "2015-06-02T14:19:02.726+0000"\n  },\n  "accountExpirationTime" : "2015-06-02T14:19:02.726+0000",\n  "secondsUntilAccountExpiration" : 123,\n  "authenticationFailureTimes" : [ "2015-06-02T14:19:02.726+0000" ],\n  "passwordChangedTime" : "2015-06-02T14:19:02.726+0000",\n  "secondsUntilIdleLockout" : 123,\n  "mustChangePassword" : true,\n  "lastLoginTime" : "2015-06-02T14:19:02.726+0000",\n  "secondsUntilPasswordExpiration" : 123\n}

• get /scim/v2/{dataViewName}/{targetUserId}/deliveryMechanisms Gets the list of configured delivery mechanisms for delivering one time passwords. Requires 'Read' access to 'urn:unboundid:schemas:2.0:DeliveryMechanisms' resource.

  Parameters

  Name	Type	Description	Required	Data Type
  targetUserId	path	The ID of the user for whom delivery mechanisms are retrieved.	true	String
  dataViewName	path	The name of the Data View to use when getting delivery mechanisms.	true	String

  Responses

  Code	Description	Response
  200	A list containing the delivery mechanisms.	array[DeliveryMechanism]

  Example Response

  Content-Type: application/json

  [ {\n  "supported" : true,\n  "name" : "aeiou",\n  "recipient" : "aeiou"\n} ]

• put /scim/v2/{dataViewName}/{targetUserId}/password Updates a user's password by specifying an old and new password. The old password may not be required. If a new password is not supplied, a new password may be generated and returned. Requires 'Update' access to 'urn:scim:schemas:core:1.0:password' resource.

  Parameters

  Name	Type	Description	Required	Data Type
  targetUserId	path	The ID of the user whose password will be updated.	true	String
  dataViewName	path	The name of the Data View to use when updating the user's password.	true	String
  passwordUpdateRequest	body	The request for the password update.	true	PasswordUpdateRequest

  Responses

  Code	Description	Response
  200	Success	PasswordUpdateResponse
  204	No content

  Example Response

  Content-Type: application/json

  {\n  "generatedPassword" : "aeiou"\n}

• get /scim/v2/{dataViewName}/{targetUserId}/passwordQualityRequirements Retrieves the password quality requirements for an existing user. Requires 'Read' access to the 'urn:unboundid:schemas:2.0:PasswordQualityRequirement' resource.

  Parameters

  Name	Type	Description	Required	Data Type
  targetUserId	path	The ID of the user for which the password quality requirements should be retrieved.	true	String
  dataViewName	path	The name of the Data View to use when retrieving the password quality requirements.	true	String

  Responses

  Code	Description	Response
  200	Success	PasswordQualityRequirementResponse

  Example Response

  Content-Type: application/json

  {\n  "currentPasswordRequired" : true,\n  "passwordRequirementResults" : [ {\n    "failureMessage" : "aeiou",\n    "requirementSatisfied" : true,\n    "display" : "aeiou",\n    "type" : "aeiou"\n  } ],\n  "mustChangePassword" : true,\n  "secondsUntilPasswordExpiration" : 123\n}

• post /scim/v2/{dataViewName}/{targetUserId}/passwordResetTokens Creates a password reset token. The password reset token can be used as the current password when updating a user's password, if a user forgets the previous password. Requires 'Create' access to 'urn:unboundid:schemas:2.0:PasswordResetToken' resource.

  Parameters

  Name	Type	Description	Required	Data Type
  targetUserId	path	The ID of the user for whom the password reset token is generated.	true	String
  dataViewName	path	The name of the Data View to use when generating the password reset token.	true	String
  passwordResetTokenRequest	body	The request for the password reset token.	true	PasswordResetTokenRequest

  Responses

  Code	Description	Response
  200	Success	TokenDeliveryResponse

  Example Response

  Content-Type: application/json

  {\n  "message" : "aeiou",\n  "deliveryMechanism" : {\n    "supported" : true,\n    "name" : "aeiou",\n    "recipient" : "aeiou"\n  }\n}

• post /scim/v2/{dataViewName}/{targetUserId}/singleUseTokens/{tokenId} Gets a single use token for a user. This token can be consumed later to validate that the user has received the token. Requires 'Create' access to 'urn:unboundid:schemas:2.0:SingleUseToken' resource.

  Parameters

  Name	Type	Description	Required	Data Type
  targetUserId	path	The ID of the user associated with the single use token.	true	String
  dataViewName	path	The name of the Data View to use when creating the single use token.	true	String
  tokenId	path	The ID of the token to create. The value used here must be used to consume the token.	true	String
  singleUseTokenRequest	body	The request for the single use token.	true	SingleUseTokenRequest

  Responses

  Code	Description	Response
  200	Success	TokenDeliveryResponse

  Example Response

  Content-Type: application/json

  {\n  "message" : "aeiou",\n  "deliveryMechanism" : {\n    "supported" : true,\n    "name" : "aeiou",\n    "recipient" : "aeiou"\n  }\n}

• delete /scim/v2/{dataViewName}/{targetUserId}/singleUseTokens/{tokenId}/{tokenValue} Consumes a single use token for a user. Requires 'Delete' access to 'urn:unboundid:schemas:2.0:SingleUseToken' resource.

  Parameters

  Name	Type	Description	Required	Data Type
  targetUserId	path	The ID of the user associated with the single use token.	true	String
  dataViewName	path	The name of the Data View to use when updating the user's password	true	String
  tokenId	path	The ID of the token to consume. This must be the same as the tokenId used to create the token.	true	String
  tokenValue	path	The value of the single use token that was delivered to the user.	true	String

  Responses

  Code	Description	Response
  204	No content
  404	Not found

Models

• PasswordQualityRequirementResponse

  The password quality requirements for a particular user.

  Attribute	Description	Data Type
  currentPasswordRequired	True if the user's password is required for password updates.	Boolean
  mustChangePassword	True if the user's password must be changed.	Boolean
  secondsUntilPasswordExpiration	The number of seconds before the password will expire.	Integer
  passwordRequirementResults	A list of password requirements that must be met.	array[PasswordRequirementResult]

• PasswordRequirementResult

  Password requirement results generated during a password update operation, or when requesting password quality requirements.

  Attribute	Description	Data Type
  display	The human-readable description of the password requirement.	String
  type	The type of password requirement.	String
  requirementSatisfied	True if this requirement was satisfied. False if not. (Only applicable for password update)	Boolean
  failureMessage	The message associated with this failure. (Only applicable for password update)	String

• PasswordUpdateRequest

  Request object for updating user passwords.

  Attribute	Description	Data Type
  currentPassword	The user's current password.	String
  newPassword	The requested new password for the user.	String

• PasswordUpdateResponse

  Information about the results of a password update operation.

  Attribute	Description	Data Type
  generatedPassword	The password generated during the password update operation.	String

• PasswordResetTokenRequest

  Attribute	Description	Data Type
  preferredDeliveryMechanisms	The delivery mechanisms to use for delivering the password reset token in order of preference.	array[DeliveryMechanism]
  fullText	The text that should appear in the message delivered to the user by a delivery mechanism that does not impose significant constraints on the message size.	TokenText
  compactText	The text that should appear in the message delivered to the user by a delivery mechanism that imposes significant constraints on the message size.	TokenText
  messageSubject	The text (if any) that should be used as the message subject if the delivery mechanism accepts a subject.	String

• DeliveryMechanism

  Attribute	Description	Data Type
  name	The delivery mechanism requested or used (depending on the context) for delivering one-time passwords	String
  recipient	The recipient address (email address, phone number) requested or used (depending on the context) for delivering one-time passwords.	String
  supported	True if the delivery mechanism is supported, or false if it is not (set when information is returned about delivery mechanisms).	Boolean

• TokenText

  Attribute	Description	Data Type
  before	The text that should appear before the token.	String
  after	The text that should appear after the token.	String

• TokenDeliveryResponse

  Attribute	Description	Data Type
  deliveryMechanism	The delivery mechanism used.	DeliveryMechanism
  message	Message containing information about the delivery of the one-time password.	String

• SingleUseTokenRequest

  Attribute	Description	Data Type
  preferredDeliveryMechanisms	The delivery mechanisms to use for delivering the password reset token in order of preference.	array[DeliveryMechanism]
  secondsUntilExpiration	The number of seconds that the token is valid. After the token expires, it cannot be successfully consumed.	Integer
  fullText	The text that should appear in the message delivered to the user by a delivery mechanism that does not impose significant constraints on the message size.	TokenText
  compactText	The text that should appear in the message delivered to the user by a delivery mechanism that imposes significant constraints on the message size.	TokenText
  messageSubject	The text (if any) that should be used as the message subject if the delivery mechanism accepts a subject.	String
  deliverIfPasswordExpired	true if the token should be delivered if the password is expired.	Boolean
  deliverIfAccountLocked	true if the token should be delivered if the account is locked.	Boolean
  deliverIfAccountDisabled	true if the token should be delivered if the account is disabled.	Boolean
  deliverIfAccountExpired	true if the token should be delivered if the account is expired.	Boolean

• AccountState

  Attribute	Description	Data Type
  accountDisabled	True if the account is disabled, or false if not. Set to null to clear.	Boolean
  accountExpirationTime	Time of account expiration. Set to null to clear.	Date
  secondsUntilAccountExpiration	Seconds until account is expired.	Integer
  passwordChangedTime	Password changed time. Set to null to clear.	Date
  passwordExpirationWarnedTime	Password expiration warned time. Set to null to clear.	Date
  secondsUntilPasswordExpiration	Seconds until password will expire.	Integer
  authenticationFailureTimes	The date and time of previous authentication failures.	array[Date]
  secondsUntilAuthenticationFailureUnlock	Seconds until authentication failure unlock.	Integer
  remainingAuthenticationFailureCount	Remaining authentication failure count.	Integer
  lastLoginTime	Last login time. Set to null to clear.	Date
  secondsUntilIdleLockout	Seconds until idle lockout.	Integer
  mustChangePassword	Must change password.	Boolean
  secondsUntilPasswordResetLockout	Seconds until password reset lockout.	Integer
  graceLoginTimes	Times of previous grace logins.	array[Date]
  remainingGraceLoginCount	Remaining grace login count.	Integer
  passwordChangedByRequiredTime	Password change by required time. Set to null to clear.	Date
  secondsUntilRequiredChangeTime	Seconds until require change time.	RetiredPassword
  passwordHistory	Password history. Set to null to clear.	array[String]

• RetiredPassword

  Attribute	Description	Data Type
  passwordRetiredTime	The time that the password was retired.	Date
  passwordExpirationTime	The expiration time of the password.	Date