How-tos

3 mins read

Creating Cloudentity Extension Scripts

How-to article for creating and testing Cloudentity Extensions. Learn how to create an Extension using JavaScript. Then, you can test the Extension in two ways: using the test mode or using a Sandbox Identity Provider and Demo Application.

Extending Cloudentity

To get an overview of Cloudentity Extensions, their usage and usecases, see the Extending Cloudentity Capabilities Solution Guide.

Extension Scripts in a Nutshell

Cloudentity offers two options for extending the user authentication process when using an Identity Provider: Post Authentication script and Post Authentication custom application.

The Post Authentication script allows for custom JavaScript code execution within the context of Cloudentity, enabling the modification of certain authentication context attributes, enhancement of the user context, or triggering custom API calls.

The Post Authentication custom application option allows to connect a third-party application to Cloudentity in order to redirect users to perform custom actions as part of the authentication process.

Create Extension Script

The video below shows how to create Extensions in Cloudentity based on the out-of-the-box templates.

Removing/Renaming Extensions

To remove or rename an extension, use the contextual hover-on menu available for each extension in the EXTENSIONS list.

Renaming an Extension does not cause the Extension to be unassigned from the Extension Point.

Deleting an Extension causes unassigning the Extension from the Extension Point.

  1. Go to Extensions » Scripts from the workspace main page.

  2. Create an extension using one of the available menu options

    • + - creates an empty script.

    • Sample api request - creates a script with code executing a request to a given URI.

    • Sample with secret - creates a script that uses a secret value outside of the script itself.

      Secrets

      It is recommended to use secrets for data that needs to be confidential like API keys, client credentials, and more.

    • Sample authn context modification - creates a script which enhances the authentication context after it’s prepared within Cloudentity.

    • Sample IDP selection - creates a script that enables the developers to control the identity providers visible to the users in login flows.

  3. Enter the script name in the form and click Create. Your script is created and opened in the embedded editor.

  4. Write or modify your script in the editor.

    For instructions and samples for writing scripts for a particular Extension Point, see:

  5. Save your script.

Recommendations for Writing Extensions

Adhere to the following best practices when writings scripts:

When running the script in test mode, check for errors in the console. You can see a sample error report in the video below, where we’re making a call to a non-existing document.

Test Extension Using Test Mode

  1. Run the script in test mode to check if it works as expected.

    In the video below, we are checking a simple script returning a secret value.

  2. Check the data in the INPUT section.

    It is meant to mimic a real request processed by Cloudentity. Modify the paremeters if necessary for the purpose of your test.

  3. Select RUN.

    Result

    Your script runs against the input data. The result is printed in the OUTPUT section. Runtime information is printed in the CONSOLE section.

    In a real world scenario, attribute values from OUTPUT:

    • Override the original authentication context for the Extensions that modify the authentication context (provided they exist in the authentication context - new attributes are NOT created).

    • Override claims within the security token and/or create new claims within the security token issued by the Cloudentity platform for Extensions used to enrich token claims.

    For Extensions modifying the login flow for users, there is no sample output.

Unit Test Extensions

Cloudentity provides a Sample Script Extensions Test GitHub that can be forked within the Extensions. You can add unit/integration tests for more complex scripts. For more information, see the READ.ME

Updated: Nov 2, 2023