Creating Cloudentity Extension Scripts
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.
Go to Extensions > Scripts from the workspace main page.
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.
Tip
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.
Enter the script name in the form and click Create. Your script is created and opened in the embedded editor.
Write or modify your script in the editor.
For instructions and samples for writing scripts for a particular Extension Point, see:
Save your script.
Recommendations for Writing Extensions
Adhere to the following best practices when writings scripts:
Write safe code using try/catch statements.
Add meaningful error messages.
Run your script in test mode at least once.
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
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.
Check the data in the INPUT section.
It is meant to mimic a real request processed by Cloudentity. Modify the parameters if necessary for the purpose of your test.
Select RUN.
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