Using the Password Reset Feature
Service API Specification
Overview
The Password Reset Module provides a REST API for user password reset on the specified port. User operations are performed by requests to the https://<server_ip>:<port>/api/users endpoint with the body in JSON format and the token in the header.
Performing the Password Reset Operation
In order to generate a password for a user the request should have the following body:
{
"type": "request",
"request": {
"action": "generate_password",
"user": "<user_id>"
}
}
The following formats are acceptable for the Password Reset Module where recognized by DNS:
- login: Jon.One
- full login: mydomain\Jon.One
- full username: Jon.One@mydomain.com
- ADsPath: LDAP://CN=Jon.One,CN=Users,DC=mydomain,DC=com
The Password Reset Module can function across multiple domain trees in the same forest. This requires the service to run under an account with domain administrator privileges in the domain tree being accessed. If the account only has rights in a single tree, then the password reset module will not be able to span across the domain forest.
If the request is valid and the password reset finishes successfully, the service sends a response with the following body as shown below, where generated_password is a password generated according to the service settings, and username is the name of the user as Distinguished Name (DN) in Active Directory:
{
"res": "ok",
"type": "response",
"response": {
"password": "<generated_password>",
"username": "<username>"
}
}
For example:
{
"res": "ok",
"type": "response",
"response": {
"password": "E2x7s+",
"username": "CN=Jon.One"
}
}
If the request fails, the response is the following:
{
"res": "failed"
}
Response Codes
The following codes can be encountered following a Fetch URL scenario block; the value is stored in the variable $(fetchURLResultCode):
- 0: Service returned 200 OK as a response. Check the response body for success or failure. A successful response will have “ok” in the result, and “failed” if unsuccessful. In order to prevent malicious users from determining the reason for the failure, check the server event viewer for password reset events. This could include the following errors encountered:
- External validation script returned with failure
- Invalid user
- User not a member of the allowed groups
- User belongs to one of the disallowed groups
- The password configured is not complex enough to meet domain requirements
- -3: Unable to connect to HTTP host; check the URL and port with the configuration on the Password Reset server
- -4: Incorrect JSON syntax in request body; check the format for errors
- 404: The service was not found (i.e., the HTTP host resolved correctly but still was not found); check the token and hash values if the time-based option is used.
< Previous | Next >