Nervepoint Access Manager RPC API
Nervepoint Team
| Revision History | |
|---|---|
| Revision 0.1 | 06/09/2011 |
|
Prototype API first revision. |
|
| Revision 0.2 | 13/09/2011 |
|
Added new "inputHints" to /challenge response output. This describes any general rules and constraints that are placed on any input returned for a particular challenge. In the case of a Password Reset, these are used to return the currently configured password policy. Also made the use of the "type" attribute clearer. |
|
| Revision 0.3 | 2/03/2012 |
|
Flow now requires that each challenge has its response submitted before another challenge is provided. Added the ability to move back to a previous challenge. Added locale to all requests. |
|
Chapter 1. Introduction
This document describes how to perform remote password resets and account unlocks for users that are managed by Nervepoint Access Manager.
It assumes you are familiar with the HTTP (and HTTPS) protocol, have knowledge of the JSON data-interchange format, and have some method of communicating via HTTP with the server. Many programming languages have built in support for the HTTP protocol, and failing that will have some external library available.
To be able to make use of the discovery mechanism, you will also require basic knowledge of Active Directory / LDAP.
General
The API has the following features :-
-
Requests are made using a URL under the /rpc namespace.
-
Requests may provide parameters using either GET or POST methods.
-
Response content is return in the JSON format.
-
Response errors make use of HTTP status codes.
-
Currently supports Password Reset and Account Unlock features.
-
Multi-stage challenge-response model is used that follows the identity verification schemes used internally by Nervepoint allowing a fairly flexible API that can be used with current and planned identity verification modules.
-
Cookies are not used. Instead, when state is required, responses will contain a unique id that may be used for subsequent calls.
Chapter 2. Discovery of the server
Overview
To be able to communicate with the Nervepoint remote API, the only piece of information you require is the base URL of the service. For example, if the service was running on https://nervepoint.acme.com, the RPC base URL would be https://nervepoint.acme.com/rpc.
Whilst clients should provide fallback mechanisms to allow this to be manually configured, it is recommended the automatic discovery mechanism be used when possible.
Locate the Active Directory Server
The first stage is to locate the Active Directory Server for the network. How to actually do this is beyond the scope of this document, but the Windows API can supply this information. Other techniques include querying the local DNS server.
Query Active Directory
When Nervepoint is installed, from version 0.4 it will automatically insert an entity into Active Directory that provides the RPC base URL. For example, using the acme.com domain example, this may be located using the distinguished name :-
CN=NervepointRPC,CN=Program
Data,DC=acme,DC=com
The entity will always be available under the common names CN=Nervepoint,CN=Program Data and the domain components will be whatever domain you are dealing with.
Once you have this entity, you may query the url attribute to retrieve the location of the Nervepoint RPC API.
Chapter 3. Remote Procedures
This section documents the actual calls you may make using the API. Each call is initiated by making an HTTP request. The URL for the request is made up of the configured base URL, plus the name of the remote function as well as any parameters required.
For example, to start a challenge-response session for a password reset, the full URL would be https://nervepoint.acme.com/rpc/challengeStart?scope=passwordReset
If the call was successful, the HTTP response code will be 200, the return content-type will be application/json, and the content will be a JSON response. The password reset call above would result in the following response :-
{
"sessionId":"vasb6o20hgf8tcll81rj0ak0j5"
}
Note, I have formatted this response for readability, the actual responses return on one line.
Challenge-Response
This refers to a set of calls that provide a challenge-response model that may be used to perform the Password Reset and Account Unlocks procedures. Because future versions of Nervepoint will be provide more Identity Verification Modules, with configurable Identity Verification Schemes (i.e. 'User Name', 'Self Service Questions' etc), this mechanism is used to provide a flexible RPC equivalent of the standard "Wizard" web-based user interface.
Clients should always make best attempts to "end" the Challenge-Response sessions, either successfully, or by using the cancel option (see below). However, should sessions go un-ended, the server itself will periodically force these sessions to timeout.
The server may also place additional restrictions as to how many times such resets may be attempted.
Starting a Challenge-Response session
The first stage is to start the challenge-response session. This is where you declare what Scope you require (i.e. Password Reset or Account Unlock).
URI
/rpc/challengeStart
Example URL :-
https://nervepoint.acme.com/rpc/challengeStart?scope=passwordReset
Request Parameters
Example response :-
{
"sessionId":"vasb6o20hgf8tcll81rj0ak0j5",
"incompleteChallenges":3,
"totalChallenges":3
}
Table 3.1. Parameters
| Parameter | Description |
| scope | Provides the scope to use. Will be either passwordReset or accountUnlock. |
| locale | Optional. This may be used to indicate the locale that should be used for any text labels returned. Should be the ISO country / locale codes as supported by Java. See here for a full description. Will default to the server's locale. |
HTTP Return Codes
Table 3.2. response HTTP Return Codes
| Key | Description |
| 200 (OK) | The request was accepted, the returned contained will contain the JSON data for the challenge-response session |
| 400 (BAD_REQUEST) | The scope parameter was not supplied. |
Response Content
Table 3.3. challengeStart JSON Response Dictionary
| Key | Description |
| sessionId | This contains the unique ID that should be used for sub-sequent challenge and endChallenge calls. |
| totalChallenges | The total number of challenges that are required to be completed. In total, you will call challenge this number of times, and response at least this number of times. This is not guaranteed to be fixed, a response to a challenge may alter the number of challenges required. |
| incompleteChallenges | The number of challenges that have not had responses submitted. |
Requesting a challenge
After the session has been started you should request a challenge from the server. Each challenge consists of a number of Prompts, each of which describes a single field that must be presented for this stage of the challenge. Additional hints are provided by the Type, which may be used to determine if the field is a password-like one, and so user entry should be masked (e.g. Using a '*' character).
The user must then be presented with all of these challenges, providing a way for them to provide answers to each of the prompts.
URI
/rpc/challenge
Example URL :-
https://nervepoint.acme.com/rpc/challenge?id=vasb6o20hgf8tcll81rj0ak0j5
Request Parameters
Table 3.4. Parameters
| Parameter | Description |
| id | The challenge-response session identifier, as returned by challengeStart. |
| locale | Optional. This may be used to indicate the locale that should be used for any text labels returned. Should be the ISO country / locale codes as supported by Java. See here for a full description. Will default to the server's locale. |
HTTP Return Codes
Table 3.5. response HTTP Return Codes
| Key | Description |
| 200 (OK) | The request was accepted, the returned contained will contain the JSON data for the challenge |
| 400 (BAD_REQUEST) | The id parameter was not supplied. |
| 404 (NOT_FOUND) | Will be returned if challenge-response session identifier supplied is not correct or all challenges have already been retrieved. |
Response Content
Example response 1
This example shows the response returned for the challenge used to collect display the Self Service Questions that are required for a password reset. Notice the type field of identityVerification , used to indicate the challenge is required to verify the identity of the user that wishes to perform the reset.
{
"prompts" : [
{ "label":"Where was your first school?",
"type":"PASSWORD",
"defaultValue":""
},
{
"label":"What was your first telephone number?",
"type":"PASSWORD",
"defaultValue":""
},
{
"label":"What was your first pets name?",
"type":"PASSWORD",
"defaultValue":""},
{
"label":"What is your favourite TV show?",
"type":"PASSWORD",
"defaultValue":""
},
{
"label":"Where were you born?",
"type":"PASSWORD",
"defaultValue":""
}
],
"type":"identityVerification",
"label":"Please enter your username:",
"inputHints": []
}
Example Response 2
This example shows the response returned for the challenge used to ask for the user's new password. Notice the type field of passwordReset, used to indicate the challenge is asking for a new password. In this particular example, inputHints are also returned, describing the general rules of any input the user will provide - in this case, password policy details.
{
"prompts":[
{"label":"New Password",
"type":"PASSWORD",
"defaultValue":null},
{"label":"Confirm Password",
"type":"PASSWORD",
"defaultValue":null}],
"type" :"passwordReset",
"label":"Your New Password",
"inputHints": [
{"id":"maximumSize",
"label":"Is no more than 127 characters long",
"value":127},
{"id":"minimumSize",
"label":"Is at least 127 characters long",
"value":7},
{"id":"minimumDigits",
"label":"Has at least 1 numeric characters",
"value":1},
{"id":"minimumLowerCase",
"label":"Contains at least 1 lowercase character(s)",
"value":1},
{"id":"minimumUpperCase",
"label":"Contains at least 1 uppercase character(s)",
"value":1},
{"id":"minimumSymbols",
"label":"Uses at least 1 non-alphanumeric characters",
"value":null},
{"id":"noUsername",
"label":"May not contain your username",
"value":false }
]
}
Table 3.6. challenge JSON Response Dictionary
| Key | Description |
| type | This field is a hint describing the stage this challenge is at. The client may use this to provide additional information to the user. Currently may be one of identityVerification or passwordReset. |
| label | A short description of this challenge, in the language of the selected locale when supported (otherwise English). |
| prompts | A JSON Array containing all the prompts this challenge contains. See the Prompt section below. |
| inputHints | A JSON Array containing a list of general hints as to what sort of input the user must provide for this challenge. See blow. |
Prompt Response
The prompt response is a JSON dictionary, an array of which is returned in the prompts value as described above. Each challenge consists of a number of prompts.
Table 3.7. prompt JSON Response Key
| Key | Description |
| type | This field provides a hint to the client as to what sort of text input field to use. Currently may be one of TEXT (an ordinary text field) or PASSWORD (for fields that should be masked out if possible). |
| label | A short description of this prompt, in the language of the selected locale when supported (otherwise English). |
| defaultValue | The value to initialise any user input field with. May be null. |
Input Hint Response
The input hint response is a JSON dictionary, an array of which is returned in the inputHints value as described above. Each challenge consists of a number of input hints, describing the general rules for any input the user must provide. For example, in the case of a Password Reset, on the final challenge where the new password is asked for, these hints will contain the currently configured password policy.
Table 3.8. inputHints JSON Response Key
| Key | Description |
| id | A fixed identifier for the hint. The exact value of which will be depend on the challenge in question. For example, on the New Password challenge, a hint called minimumDigits is returned. |
| label | A short description of this hint. For example, in the case of the minimumDigits hint, this will be an english descripton such as "The minimum number of numeric digits required". |
| value | Any value associated with the hint. For example, in the case of the minimumDigits hint, this will contain the actual number of numeric characters required. |
Sending the response
Once the client has collected the responses for a challenge, it MUST send the response to the server before attempting to read the next challenge.
It is suggested that POST be used for this request instead of GET, although either will work.
URI
/rpc/response
Example URL:-
https://nervepoint.acme.com/rpc/response?id=25197i6j00s7938e6jutvkud9j&response=London&response=01987345678&response=Tiddles&response=&response=
Request Parameters
Table 3.9. Parameters
| Parameter | Description |
| id | The challenge-response session identifier, as returned by challengeStart. |
| response (repeats for each prompt in challenge) | The value of the response. This parameter should be repeated, once for each of the prompts contained in the challenge. If the user left this prompt blank, the response should still be included (with a empty value). Send the responses in the order the prompts were received. |
| locale | Optional. This may be used to indicate the locale that should be used for any text labels returned. Should be the ISO country / locale codes as supported by Java. See here for a full description. Will default to the server's locale. |
HTTP Return Codes
Table 3.10. response HTTP Return Codes
| Key | Description |
| 200 (OK) | The request was accepted, the response fields validated, and the client may continue to the next stage (send another response, or end the session). |
| 400 (BAD_REQUEST) | The request is invalid in some way (parameters are incorrect, or response handling failed in some other way). |
| 409 (CONFLICT) | The request itself was valid, but not accepted because the values of the response parameter are incorrect. The status message will give more detail as to why this was not accepted. |
| 404 (NOT_FOUND) | Will be returned if challenge identifier supplied is not correct. |
Moving the Challenge-Response backwards
It should be possible for the user to move the challenge response backwards so that a previous challenge can be resubmitted. Moving back will invalidate the current response and the previous challenge will be returned (along with the users responses).
See /rpc/challenge for details of the output of this request.
URI
/rpc/goBack
Example URL :-
https://nervepoint.acme.com/rpc/goBack?id=vasb6o20hgf8tcll81rj0ak0j5
Request Parameters
Table 3.11. Parameters
| Parameter | Description |
| id | The challenge-response session identifier, as returned by challengeStart. |
| locale | Optional. This may be used to indicate the locale that should be used for any text labels returned. Should be the ISO country / locale codes as supported by Java. See here for a full description. Will default to the server's locale. |
Ending the Challenge-Response session
The final stage is to end the challenge-response session. At this point, an attempt will be made to reset the password or unlock the account. Before the session may be ended, all responses must have been completed successfully (i.e. Returned a 200 status).
This call should also be used if at any stage the client wishes to cancel the session.
URI
/rpc/challengeEnd
Example URL :-
https://nervepoint.acme.com/rpc/challengeEnd?id=vasb6o20hgf8tcll81rj0ak0j5
Request Parameters
Table 3.12. Parameters
| Parameter | Description |
| id | The challenge-response session identifier, as returned by challengeStart. |
| cancel | Optional. This may be used to indicate the session should just be cancelled with no further processing. The parameter may have any value. |
HTTP Return Codes
Table 3.13. response HTTP Return Codes
| Key | Description |
| 200 (OK) | The request was accepted, and the password has successfully been reset or the account successfully unlocked OR the session has been successfully cancelled. |
| 400 (BAD_REQUEST) | The request is invalid in some way (parameters are incorrect, or failed in some other way). |
| 409 (CONFLICT) | The request itself was accepted, but the password reset or account unlock failed for some other reason. The status message will give more detail as to why this happened. |
| 404 (NOT_FOUND) | Will be returned if challenge-response session identifier supplied is not correct. |
