Rules and Scripts

Rules

The main purpose of rule packages and rules is to do access checks for services. Rules can also be used for mangling user data, like scripts, which can be easier to understand.

Rule packages

To manage rule packages, navigate to Rules -> List rules. Add a rule package by selecting Add rule package, and then enter the required rule package properties:

• Package name: Enter a name for the package.
• Knowledge base: Enter the knowledge base.
• Version: Enter a version number.

These values are from the framework of the rules engine Drools and are drived from Maven packages. The package name refers to the groupId, knowledge base to the artifactId in Maven syntax. When rule packages are compiled, they are bundled in local class and stored in a local in memory repository. This repository is used by the Drools framework to run the rules.

A rule package can contain one or more rules. They are all compiled in this packages and executed when the package is run. For more details, please refer to the Drools documentation.

Rules

To manage rules, navigate to Rules -> List rules. Add a rule by selecting Add rule, view details of available rules by selecting one in the table. In the rule editor, edit the following fields.

• Name: Set/change the name of the rule. There are no explicit restricitions, but best to use only alphanumeric and -_
• Rule package: Assign the rule to one of the available rule packages (see above)
• Rule type: For the type, use one of the following values: At the moment only tested value is DRL
• Rule: Here you can edit the rule itself.

Rule examples

An example for a rule, which checks for the presence of an e-mail address:

package edu.kit.scc.webreg.drools

import edu.kit.scc.webreg.entity.SamlUserEntity;
import edu.kit.scc.webreg.drools.UnauthorizedUser;

global org.slf4j.Logger logger;

rule "IDP is one of two specific entity id"

    when
        $user : SamlUserEntity( idp.entityId != "<entity-id-1>" &&
                   idp.entityId != "<entity-id-2>" )
    then
    	logger.info( "IDP for user {} is wrong", $user.getIdp().getEntityId() );
    	insert( new UnauthorizedUser($user, "kit-only") );

end

rule "Email is set"

    when
        $user : SamlUserEntity( email == null )
    then
    	logger.info( "E-Mail for user {} is not set", $user.getEppn() );
    	insert( new UnauthorizedUser($user, "e-mail-missing") );

end

Tools

In the List rules section, you can use a regular expressions to search and replace on all rules. An usage example for this function is the upgrade from an older version to 2.6.1. The UserEntity object was renamed to SamlUserEntity in this release. With search and replace, you can edit all occurrences in all rules at once. Please beware that rules are not automatically versioned, so it is best to backup the reg-app database before doing this.

Scripts

Using scripts, you can configure certain aspects of the reg-app. At the moment script are used for the configuration of two factor authentication and for configuration of attribute releases for relying parties.

To manage your scripts, navigate to Rules -> Scripts, click Add script, enter a name and save it. Available scripts appear in the table, click on a script name to view its detailed properties. Use Edit at the bottom of the code area to change the scripts name, its runtime properties and the script itself.

• Script engine: Enter the scripting runtime engine which is necessary to run the script. At the moment, the only tested value is nashorn.
• Script type: Enter the type of the script. Supported value is javascript. It's the only implemented language at the moment.

Do not forget to click Save to persist the changes.

HIER WÄRE ES VIELLEICHT NÜTZLICH WENN MAN BEI EINEM NEUEN SCRIPT EIN STÜCKCHEN AUSKOMMENTIERTEN CODE VOREINGESTELLT HÄTTE