Scripting Guide#

Introduction#

The Curity Identity Server is highly customizable via configuration settings, but many times it’s desirable to do more advanced operations in a programmatic way. This ranges from doing custom validation of input parameters, when a user authenticates or creates an account, to issuing tokens with a different structure than what’s provided by default. Even more advanced scenarios include issuing multiple tokens, or tokens from endpoints that normally don’t provide a token such as the introspection endpoint.

The Curity Identity Server supports programmatic customization of some of its behavior through the use of script procedures written in JavaScript, more specifically ECMAScript 5.1

Procedures Types#

Script procedures define JavaScript functions, whose parameters and return types depend on the type of behavior that is being customized. Therefore, script procedures are divided into different procedure types. When extending the Curity Identity Server behavior via a script procedure, the first step is usually to identify the adequate procedure type. This will define which information is available to the JavaScript function, via its parameters, and what should the function return.

The following table enumerates the existing script procedure types, with links to documentation specific to each type.

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 script procedure types.

Creating and Configuring Script Procedures#

There are two recommended ways to start creating and developing procedures:

• Using the Admin UI.
• Creating files directly in the etc/init installation folder

Using the Admin UI#

Script procedures can be created and managed in the following Admin UI location.

This page will show all existing script procedures, grouped and filterable by type. It also allows creating new script procedures by providing a name and a procedure type.

For some types, namely token procedures, a subtype may also be required.

The Admin UI will then present an editor panel, pre-populated with an example script procedure for the selected type, and subtype if applicable. This editor includes syntax highlighting and auto-completion suggestions.

Using the etc/init Installation Folder#

Script procedures can be added directly to the ${IDSVR_HOME}/etc/init/ installation folder, where each procedure type has its own dedicated sub-folder. For instance, global scripts should be located inside ${IDSVR_HOME}/etc/init/global-scripts. Script procedure types that also have subtypes, such as token procedures, will have nested folders for those more specific subtypes. For instance, token procedures for the OAuth 2.0 Refresh Token flow should be located in the ${IDSVR_HOME}/etc/init/token-procedures/oauth-token-refresh nested folder.

It is recommended to use one of the pre-defined script procedures as a starting point when creating new procedures.

• Pick an already existing procedure in ${IDSVR_HOME}/etc/init.
• Or add a new procedure via the Admin UI, which provides templates based on the type of procedure created, and use its contents as the file content.

The identifier of a script procedure added directly to a ${IDSVR_HOME}/etc/init subfolder will be its file name, without the .js extension.

After adding or changing a file in ${IDSVR_HOME}/etc/init/, use the ${IDSVR_HOME}/bin/idsvr --reload command to update the configuration of the server with the most recent file contents. This operation will compile the procedure, and if that fails the reload will fail with an error message.

Using XML Configuration Files#

It is also possible to define script procedures via XML configuration files. In those cases, the script content should be Base64 encoded before being added to the XML file.

As an example, the following XML snipped adds a global script defining a constant.

<config xmlns="http://tail-f.com/ns/config/1.0">
  <processing xmlns="https://curity.se/ns/conf/base">
  <procedures>
    <global-script>
      <id>common-script</id>
      <script>CnZhciBTT01FX0NPTlNUQU5UID0gInNvbWUgY29uc3RhbnQi</script>
    </global-script>
  </procedures>
  </processing>
</config>

Developing Script Procedures#

Common Procedure API contains the common API available to script procedures, composed by global objects and a context object passed as argument to functions. It also contains usage examples for this common API.

Token Procedure Examples contains script procedure examples for token issuance scenarios.

See Also#