AZN Script Interface

In the following examples we suppose that the authorization service has been registered with the name "AZN".

Example authorization workflow script

Given a document of user-attributes, then the following JavaScript function in a workflow details how to validate access to a resource. The HTML request body should be a JSON string containing the following fields:

• a request field of the form domain/resource

• a unique transaction id (for logging);

• a JSON-like structure containing the user-attributes.

The result is again a JSON string.

function evalDocument(workItem) {
    var service = tb.getService("AZN");
    var request = workItem.input;
    var payload = request.body;

    if (payload !== null) {
        var json = service.parseDocument(payload);

        if (json !== null) {
            var resource = json.resource;
            var document = json.document;
            var transactionId = json.transactionId;

            if (resource !== null && document !== null && transactionId !== null) {
                var response = service.evalDocument(resource, document, transactionId, true);

                workItem.output = tb.generateResponse(service.printDocument(response), null, null, 200);

                return;
            }
        }
    }

    workItem.output = tb.generateResponse('{"error": 2103}', null, null, 200);
}

Function parseDocument

The parseDocument function of the authorization service parses a JSON string into a document. This document is optimized for use by the authorization engine, but supports the standard JavaScript property access. If the string can not be parsed correctly, the result is null.

Examples

var doc = service.parseDocument('{"a": 3, "b": [1, 2]}');
var i = doc.b[1]; // should be 2
var error = service.parseDocument('{"a": 1, "b": [1, 2]'); // should be null because it is not a valid JSON syntax.

Function evalDocument

The evalDocument function of the authorization service validates if a user (with attributes described by the document parameter) has access to a given resource (of the form domain/resource-id). Scripts should not pass plain Javascript objects as documents to the authorization service.

Example

dev/user
dev/user/create
test/user/create

Here the domains are dev and test, and the resource ids are user and user/create.

Two additional parameters must be supplied to the function:

• transactionId (a unique string used for logging);

• a boolean parameter specifying whether the validation should be binary (true or false) or weighted.

In binary mode, the result is either 0 (failure) or 1 (success). In weighted mode, the score can be a number between 0 and 1.

The result is a JSON-like document containing at least a score and an error code:

• an error code;

• a score between 0 and 1;

• an optional list of hints containing JSON-like documents.

Example

{
    "error": 0,
    "score": 0,
    "hints": [ { "type": "step-up", "level": 5 } ]
}

The result indicates that no error occurred. The score is zero, indicating failure to authorize. The hints fields contains a step-up suggestion, indicating that the user should step up to a stronger authentication level. The contents of the hints is specified by the authorization rules.

Function printDocument

The printDocument function of authorization service converts a document into a JSON string. In case of errors, null is returned.

Example geo-location PIP workflow

The following workflow script illustrates a simple PIP service. Given a user id, the service calculates or retrieves the default (averaged) location of the user. This information is returned to the rule engine, where it can be used to calculated a weighed score, depending on how close to user is to the default location.

function execute(workItem) {
    var azn = tb.getService("AZN");
    var document = workItem.input.value;

    if (document.user-id !== null) {
        var location = ... // compute default location as latitude-longitude array
        var response = azn.$2("lat", location[0], "lon", location[1]);

        workItem.output = tb.simpleResponse(response);
    }
    else {
        workItem.output = new tbjava.SimpleValueResponse(1000, 0, null);
    }
}

The response should always be a document, or null in case of an error. In the latter case, a non-zero status and sub-status may also be specified. This results in the creation of an error document. (The rules can check if the response is an error.)

Function $2

The $2 function of authorization service is a convenience function to create JSON-like documents from scratch. It creates a new document and adds a variable number of consecutive key-value pairs to the document. In the example, the first key is "lat", and its value is the first element of the location array. The second key is "lon" (with value the second element of the array). If the number of parameters in the function call is odd, the last element (a key) is ignored.

Function $1

The $1 function of authorization service is a convenience function to create JSON-like lists from scratch. It creates a new list and the parameters of the function call.

Registering a rule suite

The following workflow script illustrates how to register rule suites on the fly, while the authorization service is running. The rule suite is represented by an XML body in the HTML request.

function registerRuleSuite(workItem) {
    var azn = tb.getService("AZN");
    var request = workItem.input;
    var xml = request.body;

    if (xml !== null) {
        var error = azn.registerRuleSuite(xml, false);

        workItem.output = tb.generateResponse("Error: " + error, null, null, 200);
    }
    else {
        workItem.output = tb.generateResponse("Absent xml", null, null, 200);
    }
}

Function registerRuleSuite

The registerRuleSuite function of authorization service is a convenience function to register a rule suite (XML string) on the fly. The second parameter specifies if the rule suite should be saved (this only works if the TB configuration of the authorization service specifies a directory of rule suites).

Errors

Unregistering a rule suite

The following workflow script illustrates how to unregister rule suites on the fly, while the authorization service is running.

function unregisterRuleSuite(workItem) {
    var azn = tb.getService("AZN");
    var request = workItem.input;
    var rulesuite = request.body;

    if (rulesuite !== null) {
        var error = azn.unregisterRuleSuite(rulesuite);

        workItem.output = tb.generateResponse("Error: " + error, null, null, 200);
    }
    else {
        workItem.output = tb.generateResponse("Absent rulesuite", null, null, 200);
    }
}

Function unregisterRuleSuite

The unregisterRuleSuite function of authorization service is a convenience function to unregister a rule suite (XML string) on the fly. The parameter specifies the name of the rule suite. If the rule suite is stored on file in the rule suites directory, the file will be removed.

Errors