Scripting Guide

The Identity Server supports customization of some of its functions through the use of JavaScript scripts. 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 are available to different kinds of procedures. See Common Procedure Objects for a list of objects 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 302 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 303 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 log level methods trace, debug, info, warn and error are available. The line number is also presented in the output.

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