Custom Authenticator example scripts

This section contains example scripts for a Custom Authenticator. They show the minimal response to complete the step in the process. The Extension Engine contains documentation for writing scripts with more details about the syntax of the scripts.

Registration script

This is an example for registration which accepts all incoming requests. It returns the requestPayload from the request as registrationData in the response. registrationData is saved in the Token Server for future requests to this Custom Authenticator. The (empty) responsePayload is returned via the Token Server to Onegini SDK.

The format of the requestPayload parameter is defined by the mobile application. It is sent as String parameter to the execute function. The script developer is responsible for parsing this String and implement the logic to either register the user or reject the registration.

function execute(requestPayload, userIdentifier) {
  LOG.debug("Registration of Example Custom Authenticator for user: {}", userIdentifier);

  return {
    status: 2000,
    registrationData: requestPayload,
    responsePayload: ""
  };
}

Authentication script

This is an example for authentication. It compares the requestPayload from the current request with the registrationData that was saved during registration. When it succeeds, it returns a status code 2000 (Success), otherwise 4000 (Failure, user can try again). The (empty) responsePayload is returned via the Token Server to Onegini SDK.

The format of the requestPayload is defined by the mobile application. Both requestPayload and registrationData are sent as String parameter to the execute function. The script developer is responsible for parsing this String and implement the logic to either authenticate the user or reject the authentication.

function execute(requestPayload, userIdentifier, registrationData) {
  LOG.debug("Authentication of Example Custom Authenticator for user: {}", userIdentifier);

  var validUserKey = requestPayload.equals(registrationData);
  var statusCode = validUserKey ? 2000 : 4000;

  return {
    status: statusCode,
    responsePayload: ""
  };
}

Status codes

The execute function of the script is responsible for returning a status that can be interpreted by the Token Server. The Token Server will perform different actions (such as issuing or revoking tokens, etc.) based on the returned status, and will return only selected status codes to the SDK. Extreme care must be taken that they are correct.

There are different ranges of status codes, each with a particular meaning.

• 2xxx: Success
• 3xxx: Configuration error
• 4xxx: Recoverable client error
• 5xxx: Non-recoverable client error

The script should return a status code of 2000, 4xxx, or 5000. A 3xxx status is returned by the Extension Engine when the script could not be executed.

The following table contains an overview of the status codes and their meaning.

Status	Description	Response to SDK
2000	Success	forward
3000	Requested script not available	HTTP 500
3001	Script execution failure	HTTP 500
3002	Script execute function not available	HTTP 500
3003	Script class not available	HTTP 500
3004	Script result object invalid	HTTP 500
4000	Failure, user can try again	forward
4001	User already registered	HTTP 409
4002	User not registered	HTTP 404
5000	Failure, cleanup actions should be triggered	forward