Creating SecureAuth Extension Scripts
Extending SecureAuth
To get an overview of SecureAuth Extensions, their usage and usecases, see the Extending SecureAuth Capabilities Solution Guide.
Extension Scripts in a Nutshell
SecureAuth 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 SecureAuth, 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 SecureAuth 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 SecureAuth 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 SecureAuth.
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 SecureAuth. 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 SecureAuth platform for Extensions used to enrich token claims.
For Extensions modifying the login flow for users, there is no sample output.
Unit Test Extensions
SecureAuth 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