Scripting Guide

The Identity Server supports customization of some of its functions through the use of JavaScript scripts (ECMAScript 5.1). In this section, we describe how to implement these scripts with examples of common scenarios.

See also

For a general overview of the Scripting functionality and configuration of scripts see: the Administration guide on Scripts.

Each type of script is defined by its place in the configuration and the expected interface it needs to implement.

Several utility objects and functions are available to different kinds of procedures. See Common Procedure API for a list of objects and functions that may be used from different procedures.

Each type may contain subtypes, which is marked by a specific configuration parameter of that type in the configuration. See the configuration reference for procedure for more information about each configuration type.

Developing Procedures

It is recommended to use one of the pre-defined procedures as a starting point when customizing the procedures. There are many workflows that can be used.

  1. Pick a procedure in $IDSVR_HOME/etc/init to use as starting point or add a new procedure in the UI which provides templates based on the type of procedure created.
    Copy the procedure into a new file in the same directory or create a new procedure in the UI by going to System → Procedures and adding a new procedure of a certain type. When using etc/init the name of the file will become the configuration ID of the procedure for later reference.
  2. Update the procedure
    Using your preferred editor or the admin UI, update the procedure with the functionality desired.
  3. Reload the configuration or, if using the GUI, commit the changes
To deploy the procedure, use the idsvr --reload command which will update the configuration of the server. This operation will compile the procedure, and if that fails the reload will fail with an error message.

Note

Only errors resolvable during compilation are reported on reload, some errors could still occur when running the procedure, such as missing references etc. Always test your procedures with the flows it is intended to support.

Logging

The procedures can use the slf4j logger which is provided as a global object named logger.

Listing 268 Logging to the server log in a procedure
1
2
3
4
5
logger.debug("Printing claims");

for(key in context.optionalClaims.claims) {
    logger.debug("Claim: {}={}", key, context.optionalClaims.claims[key]);
}

This will log to the server.log (or stdout if not running as a service) with the script name as part of the class name.

Listing 269 Procedure log output
2016-08-27 08:14:28 DEBUG  {qtp1444635117-75} se.curity.identityserver.scripting.token_procedure.my-token-procedure:58 Printing claims
...

The Logger methods trace, debug, info, warn and error are available. The line number is also presented in the output.

Note

Besides the logger, there are other objects and helper functions available to all scripts. Please see Common Procedure API and Global Scripts for more details.

In addition to the logger object, the perhaps more familiar console.log may also be used, which is equivalent of using logger.debug.

Exceptions

To abort the procedure and report an error, an exceptionFactory object is available from all procedures.

The following example will result in an error response with the appropriate HTTP status code being reported back to the HTTP client.

Listing 270 Aborting execution using exceptions
1
throw exceptionFactory.unauthorizedException("The user is not authorized to perform this action")

Tip

If you want your message to be visible in the server’s response you would need to enable expose-detailed-error-messages