Skip to content

Commit

Permalink
Customization / Timeouts (#2785)
Browse files Browse the repository at this point in the history 
initial checkin
  • Loading branch information
@nynymike
nynymike authored Oct 31, 2022
1 parent 2a67e1b commit 0bf1399
Show file tree
Hide file tree
Showing 3 changed files with 199 additions and 57 deletions.
149 changes: 94 additions & 55 deletions docs/admin/developer/interception-scripts.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,18 +6,30 @@ tags:

# Interception Scripts (or custom scripts)

Interception scripts (or custom scripts) allow you to define custom business logic for various features offered by the OpenID Provider (Jans-auth server). Some examples of features which can be customized are - implementing a 2FA authentication method, consent gathering, client registration, adding business specific claims to ID token or Access token etc.
Scripts can easily be upgraded and doesn't require forking the Jans Server code or re-building it.
Interception scripts (or custom scripts) allow you to define custom business
logic for various features offered by the OpenID Provider (Jans-auth server).
Some examples of features which can be customized are - implementing a 2FA
authentication method, consent gathering, client registration, adding business
specific claims to ID token or Access token etc.
Scripts can easily be upgraded and doesn't require forking the Jans Server code
or re-building it.

# Types of Interception scripts in Jans server
Listed below, are custom scripts classified into various types, each of which represents a feature of the Jans server that can be extended as per the business need. Each script type is described by a java interface whose methods should be overridden to implement your business case.

1. [Person Authentication](./scripts/person-authentication.md) : Allows the definition of multi-step authentication workflows, including adaptive authentication - where the number of steps varies depending on the context.
1. [Consent Gathering](./scripts/consent-gathering.md) : Allows exact customization of the authorization (or consent) process. By default, the OP will request authorization for each scope, and display the respective scope description.
1. [User Registration]()
Listed below, are custom scripts classified into various types, each of which
represents a feature of the Jans server that can be extended as per the business
need. Each script type is described by a java interface whose methods should be
overridden to implement your business case.

1. [Person Authentication](./scripts/person-authentication.md) : Allows the
definition of multi-step authentication workflows, including adaptive
authentication - where the number of steps varies depending on the context.
1. [Consent Gathering](./scripts/consent-gathering.md) : Allows exact
customization of the authorization (or consent) process. By default, the OP will
request authorization for each scope, and display the respective scope description.
1. Update User
1. [Client Registration](./scripts/client-registration.md)
1. Dynamic scopes : Enables admin to generate scopes on the fly, for example by calling external APIs
1. Dynamic scopes : Enables admin to generate scopes on the fly, for example by
calling external APIs
1. ID Generator
1. Cache Refresh
1. Session Management
Expand All @@ -30,18 +42,20 @@ Listed below, are custom scripts classified into various types, each of which re

# Implementation languages - Jython or pure Java

Interception scripts are written in **[Jython](http://www.jython.org/)** or in **pure Java**, enabling Java or Python libraries to be imported.
Interception scripts are written in **[Jython](http://www.jython.org/)** or in
**pure Java**, enabling Java or Python libraries to be imported.

***

## Implementation in Pure Java
## Implementation in Pure Java

A script in Java refers to a java source file (e.g. `Discovery.java`) which is compiled by AS and executed at runtime.
A script in Java refers to a java source file (e.g. `Discovery.java`) which is
compiled by AS and executed at runtime.

Some rules:

* The java class file containing the script should not have a package set.
* The name of the class must match to the name set in [CustomScriptType source code](https://github.com/JanssenProject/jans/blob/main/jans-core/script/src/main/java/io/jans/model/custom/script/CustomScriptType.java) (e.g. for discovery script it is "Discovery")
* The name of the class must match to the name set in [CustomScriptType source code](https://github.com/JanssenProject/jans/blob/main/jans-core/script/src/main/java/io/jans/model/custom/script/CustomScriptType.java) (e.g. for discovery script it is "Discovery")
* Scripts must implement predefined interface which can be found against the [CustomScriptType](https://github.com/JanssenProject/jans/tree/main/jans-core/script/src/main/java/io/jans/model/custom/script/type). For e.g. if you are writing a Person authentication script then your class should implement the [following interface](https://github.com/JanssenProject/jans/blob/main/jans-core/script/src/main/java/io/jans/model/custom/script/type/auth/PersonAuthenticationType.java)
* All libraries available at runtime to server are available also to pure java script
* To log to `jans-auth_script.log` use `scriptLogger`
Expand Down Expand Up @@ -109,11 +123,11 @@ public class Discovery implements DiscoveryType {
<Set name="extraClasspath">/opt/jans/jetty/jans-auth/custom/libs/library-name.jar</Set>
```
3. Restart jans-auth service
`systemctl restart jans-auth`
`systemctl restart jans-auth`

***

## Implementation in Jython
## Implementation in Jython
The example below is only meant to convey the concept, we will cover the details in later parts of the documentation.
Suppose, we are implementing an Openbanking Identity platform and we have to add business specific claims say `openbanking_intent_id` to the ID token. The custom script which will help us accomplish our goal is of the type `UpdateTokenType` where the `modifyIdToken` method has to be implemented. A sample custom script with this business logic will be as stated below :
```
Expand All @@ -122,7 +136,7 @@ class UpdateToken(UpdateTokenType):
self.currentTimeMillis = currentTimeMillis
def init(self, customScript, configurationAttributes):
< initialization code comes here >
< initialization code comes here >
return True
def destroy(self, configurationAttributes):
Expand All @@ -137,10 +151,10 @@ class UpdateToken(UpdateTokenType):
# Step1: <get openbanking_intent_id from session >
sessionId = context.getSession()
openbanking_intent_id = sessionId.getSessionAttributes().get("openbanking_intent_id ")
# Step2: <add custom claims to ID token here>
jsonWebResponse.getClaims().setClaim("openbanking_intent_id ", openbanking_intent_id )
```
### Using Java libraries in a Jython script:
<br> **Steps:**
Expand All @@ -150,23 +164,34 @@ class UpdateToken(UpdateTokenType):
<Set name="extraClasspath">/opt/jans/jetty/jans-auth/custom/libs/library-name.jar</Set>
```
3. Restart jans-auth service
`systemctl restart jans-auth`
`systemctl restart jans-auth`

### Using Python libraries in a script:

1. You can only use libraries (packages and modules) that are written in **Pure Python**. Importing a Python class which is a wrapper around a library written in C is not supported by the Jans server. As an example, the psycopg2 library used to connect to PostgreSQL from Python. Since it is a C wrapper around libpq, it won't work with Jython.
1. You can only use libraries (packages and modules) that are written in
**Pure Python**. Importing a Python class which is a wrapper around a library
written in C is not supported by the Jans server. As an example, the psycopg2
library used to connect to PostgreSQL from Python. Since it is a C wrapper
around libpq, it won't work with Jython.

1. Python 3 packages / modules are not supported.

<br> **Steps:**
1. Pure Python libraries should be added to `/opt/jans/python/libs`

2. Using pip to install additional Python packages:
2. Using pip to install additional Python packages:

* Find out about your Jython version first. cd into the /opt directory in your Jans Server container and run ls. A directory named jython-<version> should be listed too where <version> will correspond to the Jython version. Note the version.
* Open the file `/etc/jans/conf/jans.properties` and look for the line starting with `pythonModulesDir=`. Append the value `/opt/jython-<version>/Lib/site-packages` to any existing value. Each value is separater by a colon (:). It should look something like this ` pythonModulesDir=/opt/jans/python/libs:/opt/jython-2.7.2a/Lib/site-packages`
* Find out about your Jython version first. cd into the /opt directory in your
Jans Server container and run ls. A directory named jython-<version> should be
listed too where <version> will correspond to the Jython version. Note the
version.
* Open the file `/etc/jans/conf/jans.properties` and look for the line starting
with `pythonModulesDir=`. Append the value `/opt/jython-<version>/Lib/site-packages`
to any existing value. Each value is separater by a colon (:). It should look
something like this ` pythonModulesDir=/opt/jans/python/libs:/opt/jython-2.7.2a/Lib/site-packages`
Run the following command ` /opt/jython-<version>/bin/jython -m ensurepip `
Install your library with `/opt/jython-<version>/bin/pip install <library_name> ` where <library_name> is the name of the library to install.
Install your library with `/opt/jython-<version>/bin/pip install <library_name> `
where <library_name> is the name of the library to install.
* Restart the jans-auth service : `systemctl restart jans-auth`

### Debugging a Jython script
Expand All @@ -175,17 +200,27 @@ This [article](https://github.com/JanssenProject/jans/blob/main/docs/admin/devel

***

### Mandatory methods to be overridden
This is the [base class of all custom script types](https://github.com/JanssenProject/jans/blob/main/jans-core/script/src/main/java/io/jans/model/custom/script/type/BaseExternalType.java) and all custom scripts should implement the following methods.
* `init(self, customScript, configurationAttributes)` : This method is only called once during the script initialization (or jans-auth service restarts). It can be used for global script initialization, initiate objects etc
### Mandatory methods to be overridden
This is the [base class of all custom script types](https://github.com/JanssenProject/jans/blob/main/jans-core/script/src/main/java/io/jans/model/custom/script/type/BaseExternalType.java) and all custom
scripts should implement the following methods.
* `init(self, customScript, configurationAttributes)` : This method is only
called once during the script initialization (or jans-auth service restarts). It
can be used for global script initialization, initiate objects etc

* `destroy(self, configurationAttributes)`: This method is called when a custom script fails to initialize or upon jans-auth service restarts. It can be used to free resource and objects created in the init() method
* `destroy(self, configurationAttributes)`: This method is called when a custom
script fails to initialize or upon jans-auth service restarts. It can be used to
free resource and objects created in the init() method

* `getApiVersion(self, configurationAttributes, customScript)` : The getApiVersion method allows API changes in order to do transparent migration from an old script to a new API. Only include the customScript variable if the value for getApiVersion is greater than 10
* `getApiVersion(self, configurationAttributes, customScript)` : The
getApiVersion method allows API changes in order to do transparent migration
from an old script to a new API. Only include the customScript variable if the
value for getApiVersion is greater than 10

***

### Configurable properties of a custom script

```html
<table>
<tr><td> Name </td><td>unique identifier(name) for the custom script e.g. person_authentication_google</td></tr>
<tr><td> Description </td><td>Description text</td></tr>
Expand All @@ -200,27 +235,31 @@ This is the [base class of all custom script types](https://github.com/JanssenPr
</td></tr>
<tr><td> Custom properties</td><td>Key - value pairs for configurable parameters like Third Party API keys, location of configuration files etc </td></tr>
</table>
```

***
### Building business logic in a custom script
### Building business logic in a custom script

Jans-auth server uses Weld 3.0 (JSR-365 aka CDI 2.0) for managed beans. The most important aspects of business logic are implemented through a set of beans. This [article](https://jans.io/docs/admin/developer/managed-beans/) presents many ready-to-use beans which can be used to build a script.
Jans-auth server uses Weld 3.0 (JSR-365 aka CDI 2.0) for managed beans. The most
important aspects of business logic are implemented through a set of beans. This
[article](https://jans.io/docs/admin/developer/managed-beans/) presents many
ready-to-use beans which can be used to build a script.

***

### Operations on custom scripts using jans-cli

Jans-cli supports the following six operations on custom scripts:
Jans-cli supports the following six operations on custom scripts:

1. `get-config-scripts`, gets a list of custom scripts.
2. `post-config-scripts`, adds a new custom script.
3. `put-config-scripts`, updates a custom script.
4. `get-config-scripts-by-type`, requires an argument `--url-suffix TYPE: ______`.
You can specify the following types: PERSON_AUTHENTICATION, INTROSPECTION, RESOURCE_OWNER_PASSWORD_CREDENTIALS, APPLICATION_SESSION, CACHE_REFRESH, UPDATE_USER, USER_REGISTRATION, CLIENT_REGISTRATION, ID_GENERATOR, UMA_RPT_POLICY, UMA_RPT_CLAIMS, UMA_CLAIMS_GATHERING, CONSENT_GATHERING, DYNAMIC_SCOPE, SPONTANEOUS_SCOPE, END_SESSION, POST_AUTHN, SCIM, CIBA_END_USER_NOTIFICATION, PERSISTENCE_EXTENSION, IDP, or UPDATE_TOKEN.
You can specify the following types: PERSON_AUTHENTICATION, INTROSPECTION, RESOURCE_OWNER_PASSWORD_CREDENTIALS, APPLICATION_SESSION, CACHE_REFRESH, UPDATE_USER, USER_REGISTRATION, CLIENT_REGISTRATION, ID_GENERATOR, UMA_RPT_POLICY, UMA_RPT_CLAIMS, UMA_CLAIMS_GATHERING, CONSENT_GATHERING, DYNAMIC_SCOPE, SPONTANEOUS_SCOPE, END_SESSION, POST_AUTHN, SCIM, CIBA_END_USER_NOTIFICATION, PERSISTENCE_EXTENSION, IDP, or UPDATE_TOKEN.
5. `get-config-scripts-by-inum`, requires an argument `--url-suffix inum: _____`
6. `delete-config-scripts-by-inum`, requires an argument `--url-suffix inum: _____`

The post-config-scripts and put-config-scripts require various details about the scripts. The following command gives the basic schema of the custom scripts to pass to these operations.
The post-config-scripts and put-config-scripts require various details about the scripts. The following command gives the basic schema of the custom scripts to pass to these operations.
### Basic schema of a custom script
Command:

Expand Down Expand Up @@ -291,48 +330,48 @@ To add or modify a script first, we need to create the script's python file (e.g

### Add, Modify and Delete a script

The following command will add a new script with details given in /tmp/sample.json file. __The jans-cli will generate a unique inum of this new script if we skip inum in the json file.__
```
/opt/jans/jans-cli/config-cli.py --operation-id post-config-scripts --data /tmp/sampleadd.json
The following command will add a new script with details given in /tmp/sample.json file. __The jans-cli will generate a unique inum of this new script if we skip inum in the json file.__
```
/opt/jans/jans-cli/config-cli.py --operation-id post-config-scripts --data /tmp/sampleadd.json
```
The following command will modify/update the existing script with details given in /tmp/samplemodify.json file. __Remember to set inum field in samplemodify.json to the inum of the script to update.__
The following command will modify/update the existing script with details given in /tmp/samplemodify.json file. __Remember to set inum field in samplemodify.json to the inum of the script to update.__

```
/opt/jans/jans-cli/config-cli.py --operation-id put-config-scripts --data /tmp/samplemodify.json
```
/opt/jans/jans-cli/config-cli.py --operation-id put-config-scripts --data /tmp/samplemodify.json
```

To delete a custom script by its inum, use the following command:
To delete a custom script by its inum, use the following command:

```
/opt/jans/jans-cli/config-cli.py --operation-id delete-config-scripts-by-inum --url-suffix inum:SAMPLE-TEST-INUM
```
/opt/jans/jans-cli/config-cli.py --operation-id delete-config-scripts-by-inum --url-suffix inum:SAMPLE-TEST-INUM
```

### List existing custom scripts
These commands to print the details are important, as using them we can get the inum of these scripts which is required to perform update or delete operation.

1. The following command will display the details of all the existing custom scripts. This will be helpful to get the inum of scripts to perform the update and delete operation.
```
/opt/jans/jans-cli/config-cli.py --operation-id get-config-scripts
1. The following command will display the details of all the existing custom scripts. This will be helpful to get the inum of scripts to perform the update and delete operation.
```
/opt/jans/jans-cli/config-cli.py --operation-id get-config-scripts
```

2. Following command displays the details of selected custom script (by inum).
2. Following command displays the details of selected custom script (by inum).

```
```
/opt/jans/jans-cli/config-cli.py --operation-id get-config-scripts-by-inum --url-suffix inum:_____
```

3. Use the following command to display the details of existing custom scripts of a given type (for example: INTROSPECTION).
```
/opt/jans/jans-cli/config-cli.py --operation-id get-config-scripts-by-type --url-suffix type:INTROSPECTION
3. Use the following command to display the details of existing custom scripts of a given type (for example: INTROSPECTION).
```
/opt/jans/jans-cli/config-cli.py --operation-id get-config-scripts-by-type --url-suffix type:INTROSPECTION
```
:memo: **Note:** Incase the AS's Access token is bound to the client's MTLS certificate, you need to add the certificate and key files to the above commands.
E.g:
:memo: **Note:** Incase the AS's Access token is bound to the client's MTLS certificate, you need to add the certificate and key files to the above commands.
E.g:
```
/opt/jans/jans-cli/config-cli.py --operation-id post-config-scripts --data /tmp/sampleadd.json -cert-file sampleCert.pem -key-file sampleKey.key
```
/opt/jans/jans-cli/config-cli.py --operation-id post-config-scripts --data /tmp/sampleadd.json -cert-file sampleCert.pem -key-file sampleKey.key
```


## Client specific implementations

## Useful links
1. [Custom scripts and jans-cli](https://github.com/JanssenProject/jans-cli/blob/main/docs/cli/cli-custom-scripts.md#find-list-of-custom-scripts)
1. [Custom scripts and jans-cli](https://github.com/JanssenProject/jans-cli/blob/main/docs/cli/cli-custom-scripts.md#find-list-of-custom-scripts)
Loading

0 comments on commit 0bf1399

Please sign in to comment.