Variable and secret management

The Variable and secrety management feature allows administrators to define and manage key-value pairs that can be referenced within hooks. This provides a secure and efficient way to store and retrieve sensitive values (such as API keys and client secrets) and general variables used across different configurations.

Capabilities

Secure storage for secrets: Sensitive values are encrypted and never displayed in plain text after creation.
Global and local variables: Global variables provide a centralized value that can be referenced across multiple hooks, while local variables are defined within individual hooks.
Application and identity store-specific overrides: Customize variable values for individual applications or identity stores, allowing flexibility in different environments.
UI-based management: A dedicated interface in the Admin Console enables administrators to create, manage, and delete variables and secrets easily.
Role-based access control: Limits access to secrets, ensuring only authorized administrators can modify and retrieve them.

Example use cases

Managing sensitive credentials securely: Secret management enables secure storage of sensitive values, such as API keys and client secrets, without embedding them in hook scripts. This ensures that confidential information remains encrypted and accessible only at code execution time.
Centralized control over configuration values: Global variables allow administrators to define configuration values—for example, risk score thresholds—that are used across multiple hooks. When adjustments are needed, updating the value in one place automatically applies the change wherever the global variable is referenced, eliminating the need for manual updates in multiple hooks.
Environment-specific configurations for application promotion: When moving an application from a test environment to production, hooks often require different credentials or settings (for example, test vs. production API endpoints). By defining required variables and secrets that need to be applied when a hook is applied to an application, administrators can ensure that the appropriate values are provided when deploying hooks in different environments, preventing misconfigurations and maintaining security.

Configuration

Creating global variables and secrets

Set global variables and secrets to allow you to manage sensitive data and reusable configuration values centrally.

Navigate to Instance configuration > Variables and secrets on the Admin console.
Select Create.
Select if variable or secret:
1. Variable: General configuration values.
2. Secret: Sensitive values that will be stored securely and never exposed.
Add a name and, optionally, a description. Policy and application tags can also be assigned to variables and secrets.
Add the variable or secret value.
Select Save.

Editing and deleting global variables and secrets

Use the kebab menu (⋮) next to an entry to edit or delete it.
Editing allows updating the value while maintaining references.
Deleting a global variable or secret is not allowed if it is referenced elsewhere, such as in a hook applied to an application or identity store.

Referencing global variables and secrets

To reference global variables and secrets, create a local variable, set the default value to Use value from, and select the appropriate global variable or secret.

Creating local variables and secrets

Local variables and secrets let you define environment-specific values that are only accessible within a specific hook.

Navigate to Lifecycle event hooks on the Admin console.
Select the Variables and secrets button on the upper right side of the IDE.
Select the Add button.
Add a name and, optionally, a description.
🚧
Local variable and secret names must follow certain rules: they are case-sensitive, meaning name, Name, and NAME are treated as distinct values. Spaces are not allowed, so use snake case, camel case, or Pascal case instead (for example, my_variable, myVariable, or MyVariable). Names cannot begin with a digit and should always start with a lowercase letter.
Select if variable or secret:
1. Variable: General configuration values.
2. Secret: Sensitive values that will be stored securely and not exposed.
Choose a default value. When an application is configured to use a local variable/secret, it expects a value for it. The default value setting helps define what should happen if the application hasn't been assigned a specific value.
1. No default value: The variable/secret is created without an initial value.
2. Static value/secret: You define a constant value when creating the variable/secret.
3. Use value from: Instead of defining a new value, the local variable/secret inherits its value from an existing global variable/secret. This is helpful when multiple hooks need to use the same variable/secret, but you want to control it centrally. If the global value is updated, all local variables/secrets referencing it will automatically use the same value.
Required toggle: The required toggle ensures that a value must be set for the variable/secret before it can be used.
Select Create.
To use the variable/secret within the hook, reference it from the parameters object in the function’s arguments.
1. Variables and secrets assigned to the hook are accessible through the parameters object.
2. Deconstruct the parameters object like other hook arguments:
```
module.exports = function ({ parameters }) {
    console.log(parameters.variableName); // Example usage
};
```
Select Save and deploy to deploy the hook.
To assign a hook and optionally override its variables or secrets, follow the steps based on whether you're working with an application or an identity store:
1. To assign a hook to an application, go to Applications on the Admin console, select an application from the list, and edit it. Within the General tab, scroll to Lifecycle event hooks and select Assign lifecycle event hook. Variables and secrets can be overridden here.
2. To assign a hook to an identity store, go to Identities > Identity stores on the Admin console, select an identity store from the list, and edit it. Within the Configuration tab, scroll to Lifecycle event hooks and select Assign lifecycle event hook. Variables and secrets can be overridden here.

Editing and deleting local variables and secrets

Use the icons next to the variable/secret in the list to edit or delete it.
Variable/secret names and the type cannot be modified after creation.
Deleting a local variable/secret keeps the assignment to any application or identity store intact, but removes overrides.

Overriding variables and secrets in applications and identity stores

In some cases, applications and identity stores may require values different from those initially defined for variables and secrets. When assigning a hook with a variable to an application or identity store, you can override its value with a custom one.

When assigning a variable or secret to an application or identity store, you can choose from the following options:

Value defined in hook: Use the value set in the hook.
No value: Leaves the variable or the secret empty.
Static value/secret: Sets a fixed value.
Use value from: Pulls the value from the global variables and secrets.

🚧
If a variable or secret is marked as required and "no default value" is selected when it's created, you must provide a value when assigning the hook to an application or identity store.

📘
Values set at the application and identity store level can be further overridden in A/B testing. If an A/B test is configured, the value used for a variable or secret may change based on the test conditions. This allows you to experiment with different values for different customer groups or use cases without modifying the application or identity store settings directly.

Restrictions and limitations

Secret values are immutable: Once set, they cannot be retrieved in plain text.
Secret/variable type is immutable: Once created, the type cannot be edited.
Maximum length: Both variables and secrets have an 8192-character limit.