Skip to main content

Secrets

Secrets are a way of allowing users of Teneo to store, manage, and use any secret/sensitive information, such as API keys, tokens, passwords, etc., in a secure and controlled way in the Platform.

The sections on this page provide information about the various aspects of Secrets:

Concept​

Secrets are a way of allowing users of Teneo to store, manage, and use any secret/sensitive information, such as API keys, tokens, passwords, etc., in a secure and controlled way in the Platform. These secret values can be used during Groovy script execution at runtime, while still protected and secure.

This feature allows developers to set different permissions for team members based on their roles/responsibilities, ensuring that some members of a team have access to see, update, and also use keys or tokens, whereas other users will not have these permissions.

No user can see the values of the secrets. All users can see the name of the secrets.

The Secrets functionality involves a type of setting on Account level and on the other hand, for Solutions, a new type of Global Script.

The Secrets functionality involves a setting on the Account level and a unique Global Script type.

Security​

Security is the main focus of this feature.

The implemented approach ensures that secrets remain secret by:

  • using encryption (before communication, at rest, and at runtime);
  • never returning (Studio API) or showing (Studio UI) a secret after it has been set;
  • only allowing users with appropriate permissions to:
    • modify secrets at development time, and
    • write scripts that can handle secrets at runtime.

Account​

Secrets are defined on the Account level. Here, users can define a secret with a name, a value, and an optional description. The defined secrets are accessible from within all solutions in this account.

account-page-secret

Only users with the right permissions (defined when configuring the environment) can define/update/delete the secrets. For users without the necessary permissions, these options will appear disabled.

Once a secret is created, it is stored encrypted. The value of a secret is never exposed through the Account interface to any user, no matter permissions.

Solution​

On the Solution level, Secrets have their own type of Global Script.

add-secret-script

Being a type of Engine scripts, Secret scripts have read and write access to solution data. However, they are not connected to nor have access to any sessions. As they are intended to define utility classes to be used by scripts running later, the Secret script type is executed right before the Solution loaded scripts by the Engine.

This script type works just as the Solution loaded scripts, but also has access to and can make use of any Secrets and their values defined in the Account Settings.

Secrets defined in Account settings are accessible from within this script type via the super class Secrets, and by using this method:

Secrets.getSecret('name_of_secret')
note

This method is only allowed from within this script type; trying to access Secrets from any other Global scripts or elsewhere in the solution will throw a warning.

note

Make sure the Secret used in a Secret script is defined in the Account. If a Secret is used in a Secret script but not defined in the Account, Tryout will throw a warning.

The getSecret method provided by the Engine does not permanently store secrets in memory, but rather temporarily loads them on request and decrypts them, so that it can return the secret as plain text.

This means that any Secrets scripts have access to, can read, and can use the secrets, but do not store them locally, nor log them. As it is an Engine script with no connection to sessions, it is not part of the processing path.

The Secret scripts follow the same rules for branching as other Global scripts, and can, just like the others, be multiple and be ordered.

note

Only users with sufficient permissions are able to create, delete, or in other way modify Secret scripts. Any user will still be able to view them. Any user with permission to edit solutions will be able to set the Secrets scripts to Stable and modify the script ordering.

How to​

Add a Secret​

To create a new Secret, follow these steps:

  1. Before opening a solution, click on Account in the Studio sidebar.
  2. Click on Add to open the dropdown menu and select Secret.
  3. Give the Secret a name and add its value.
  4. Click on Save.

Edit a Secret​

To edit an existing Secret, follow these steps:

  1. Before opening a solution, click on Account in the Studio sidebar.
  2. Select the relevant Secret in the Settings section.
  3. In the Secret section, click on Edit.
  4. After editing, make sure to click on Save.

Delete a Secret​

To delete an existing Secret, follow these steps:

  1. Before opening a solution, click on Account in the Studio sidebar.
  2. Select the relevant Secret in the Settings section.
  3. In the Secret section, click on Delete.
  4. A popup window will open. Type the name of the Secret to confirm that you want to delete it and click on Delete.

Use a Secret in a Global Script​

note

Secrets can only be used in the Secret Global script type; attempting to access them from other Script types will throw a warning. For more information on how to use Global scripts, please visit the 'How to' section of Global Scripts.

To use a Secret in a Secret Global script, use this method:

Secrets.getSecret('name_of_secret')

UI​

For a detailed explanation of the UI in the Account section, visit Account.

For a detailed explanation of the UI in the Global Scripts section, visit Global Scripts.

Best Practices​

The Secrets and the Secret scripts are encrypted and protected, but it is still vital that the developers of the Secret scripts take responsibility to ensure the Secrets remain protected when writing code. Take into account the following:

  • Never print Secrets, because they would appear in engine message logs(not to be confused with session logs).
  • Never provide any methods that return any Secrets or strings containing Secrets and do not store Secrets on static class fields, because these methods and class fields can be accessed from normal scripts and thus be used to expose Secrets.
  • Utility classes defined in Secret scripts should be annotated with @groovy.transform.CompileStatic to prevent exposure of Secrets by using Groovy method interception on the provided utility classes.

Practical Examples​

Imagine you have a secret called my_api_key. A Secret script could define a class like this:

@groovy.transform.CompileStatic 
class MyAPIHandler extends Secrets { 
  static Object getResult(String query) { 
    def result = HttpClient.buildRequest() 
      .get("http://myapi/query?q=$query") 
      .addHeader('API_KEY', getSecret('my_api_key')) 
      send(); 
    return result; 
  } 
}

This class can then be used within the solution in other script scenarios. For example, you could have an integration "APIQuery" with a method called "NameQuery", which would contain the following:

  • input parameter: name
  • output parameter: result
  • integration script: return MyAPIHandler.getResult("name=$name")