Store Encrypted Secrets in a Splunk App

Does your Splunk app integrate with a third-party service or API? If so, that service might require your app’s users to authenticate using a secret. You can securely store and retrieve secrets in an app using the capabilities of the Splunk platform.

What Is a Secret?

Secrets consist of sensitive data, including passwords, credentials, and API keys, that an app requires to run. Secrets allow your app’s users to authenticate with an external service and to access that service’s resources and APIs in your app.

In the Splunk platform, secrets contain the following fields:

• Name: The third-party API username associated with the secret
  
• Password: The secret to encrypt and store
  
• Realm: The realm associated with the secret. You can have multiple secrets for the same user if the realm is different. This field is optional.
   

How Secret Storage Works

When you store a secret in a Splunk app, the Splunk platform encrypts the secret and stores this information in the passwords.conf file. Authorized users can then retrieve and use the secret for authentication.

To store a secret in an app, you first need to collect the associated name, password, and realm using a setup page. Then, call the storage/passwords endpoint to encrypt the secret and save this information in the passwords.conf file.

To retrieve a secret from the passwords.conf file, submit a GET request to the storage/passwords endpoint. This API call returns the clear text, encrypted, and masked forms of the password associated with a user's credentials.

This diagram shows the workflow for how to store and retrieve secrets in an app using the storage/passwords endpoint:

^{Note: Users require specific capabilities to store and retrieve secrets in an app. See Configure access control for secret storage.}

Three Ways to Manage Secret Storage in a Splunk App

You can call the storage/passwords REST API endpoint to manage secret storage using the following methods:

1. The Splunk Enterprise REST API
   
2. The Splunk SDK for JavaScript
   
3. The Splunk SDK for Python
    

In this blog post, we’ll walk through an example that uses the Splunk SDK for JavaScript to store a secret and the Splunk Enterprise REST API to retrieve the secret.

Store a Secret Using the Splunk SDK for JavaScript

To store a secret in a Splunk app, you need to collect the associated name, password, and realm from the user. You can use a setup page to capture this information the first time that a user runs the app.

This screenshot shows a setup page, from the Developer Tutorial app, that prompts the user to create a password to complete app setup.

Under the hood, the setup page code uses the Splunk SDK for JavaScript to post the user’s password to the storage/passwords REST API endpoint, as shown in the following code snippet.

This code contains the following methods:

• Config.create_splunk_js_sdk_service(): Creates a Service object in the Splunk SDK for JavaScript. This method allows you to connect and log in to a running instance of Splunk Enterprise.
  
  
• storage.Passwords.create(): Uses the storagePasswords class from the SDK to call the storage/passwords endpoint and store the user's password as an encrypted secret in the app's passwords.conf file. In this example, the name and realm fields are hardcoded.
   

When you store a secret in an app, the Splunk platform encrypts the secret and saves this information in the $SPLUNK_HOME/etc/apps/appname/local/passwords.conf file. The following screenshot shows the encrypted secret that we stored in the Developer Tutorial app.

Retrieve a Secret Using the Splunk REST API

To retrieve a secret in clear text, submit a GET request to the storage/passwords REST API endpoint. 

In this example, we’ll retrieve the secret that we stored in the Developer Tutorial app through calling the storage/passwords endpoint using the Splunk REST API directly, as shown in the following image.

The API call response contains the clear text, encrypted, and masked forms of the secret we stored in the app, as shown in the following image.

More Resources

Check out the following resources to learn more about secret storage:

• For comprehensive documentation on secret storage, see Manage secret storage in apps for Splunk Cloud Platform or Splunk Enterprise on the Splunk Developer Portal.
  
• For comprehensive documentation on setup pages, see Enable first-run configuration with setup pages in Splunk Cloud Platform or Splunk Enterprise on the Splunk Developer Portal.
  
• For a blog post about setup pages, see Enable First-Run App Configuration With Setup Pages.
  
• For a step-by-step tutorial that uses a setup page to store a secret in a Splunk app, see Module 2: Add a setup page to your app in Splunk Cloud Platform or Splunk Enterprise on the Splunk Developer Portal.
  
• For an example app that uses a setup page to store a secret in a Splunk app, see the Weather App in the splunk-app-examples repository on GitHub.