Managing Secrets¶

Aunsight secrets provide a way to allow Aunsight members to make use of sensitive credentials, certificates, and keys without exposing the content of the secrets to those users personally. Because of their importance, secrets should be able to be used without revealing their contents to those who need to run a process. In much the same way as tokens allow workflows and processes to be run without actually providing a member's credentials directly, Aunsight's Secret Service allows users to create secrets that can mask the content of the secrets from most users and only allow access to those secrets from within a process.

Teams will want to entrust someone with the role of administering and maintaining secrets. Because most certificates expire and security credentials should be changed often, a teams secret manager will need to know how to create, update, and delete secrets from the Web interface. This article teaches how to manage secrets using the Secret Service workspace. After reading this article, users should be able to browse for secrets, create a secret, view metadata about a secret, and upload a file containing the information that the secret protects.

The Secret Service Workspace¶

The Aunsight web interface provides the Secret Service workspace to users who have the AU-SECRET:view-secret permission available to them through a role or group they have in a given context.

To access this workspace, log in to the web interface and select the context you wish to work in through the context selector. From that context's dashboard, click the "Secret Service" icon () in the palette on the right.

Secret Service Workspace

The Secret Service workspace is a standard list-based view of secrets available in the present context. You can search () and sort () the list to find a secret by clicking the appropriate icon at the top of the list. You can also create a new secret by clicking the plus icon ().

Create a Secret¶

To create a secret, click the plus icon () to open a dialog for creating a new secret.

new secret creation dialog

To create a secret, the only required field is the name for the new secret record. In most cases, however, you may wish to specify other options:

Description: The description field is a text field that will be used to generate the secret's description text. Though the field accepts only plain text, it will render markdown formatted content as rich text.
Tags: Aunsight secrets can be free-form tagged as with other types of objects by adding keywords as a comma separated list of tags (32 character limit per tag).

In addition to these settings, users can also immediately add a file by clicking the "Upload File" checkbox. This will display a file selector button. Use the input to specify the file and it will be uploaded as the content of the secret. You can also skip this step and upload your secret data later.

View Secret Metadata¶

Clicking on the name of a secret brings it into the main window where users can review details and perform actions on the metadata record for that secret.

secret record view

The web application interface displays information and tools in two tabs: details and upload.

Users with the appropriate permissions will also see action buttons to delete () the secret and its metadata or download () the secret's data.

Details tab¶

By default, Aunsight displays the "Details" tab where basic information about a secret is displayed. Information in this section includes:

ID: The secret's GUID. This is needed to use secrets from the SDKs or Toolbelt.
Name: The secret's name.
Description: The secret's description.
Tags: Custom tags for the secret (32 character limit per tag).
Project: GUID of the owning project context.
Empty: Indicates whether the secret contains data; It will be true if there is secret data, or false if the secret is empty.

In addition to these fields, the details will also show the name and timestamp of the last significant changes to the secret (creation, update, modification, and last time accessed).

Users can edit the Name, Descriptio, and Tags fields by clicking the edit icon () in the upper right corner of this section. All other fields are not user editable.

Upload tab¶

The upload tab allows users with the appropriate permissions to upload a file with secret data. Secret data could take the form a simple text file, an SSH private key, an SSL certificate, or any kind of data structured as a JSON object.

To upload a secret, click the "upload" tab and then "Choose File" to select a file on the local filesystem to upload. secrets upload tab

After selecting a file, upload it by clicking "Submit."

Using Secrets¶

Managing secrets happens primarily from within the Web interface, but secrets are not usually used here. Users who have the AU-SECRET:fetch-secret permission will be able to download the secret data from the web interface, but this is only useful if you want to see what is in the secret. To employ secrets to authenticate, sign, or encrypt data requires access through a programmatic interface like the Toolbelt or one of the Aunsight SDKs.

From Toolbelt¶

Secrets can be accessed from Shell script processes via the Toolbelt. Toolbelt exposes commands for dealing with secrets via the au2 secret command group.

To download a secret for use in a shell script, first set the context and then download the secret to a file by its GUID:

# Set shell variables for Aunsight Context
ORG='50d93f12-0288-4473-8d35-3e8e9bbc1693' # Organization GUID
PROJECT='3355a611-500f-4f56-a031-9ba9682198cf' # Project GUID
SECRET='e9b41718-6e03-40de-bf4b-eb7f31ea009d' # Secret GUID

# Set context
au2 context set $ORG $PROJECT

# Download secret and redirect the standard output stream to a file
au2 secret download $SECRET >> secret_file.txt

Note

If you are working at the Organization context level, you can ommit the $PROJECT variable and simply set the context using au2 context set $ORG

In many cases, secrets are stored as JSON data. To read key/value pairs, use jq to access JSON attributes by name from the shell:

# Download a secret and pipe to 'jq' to filter for the username and password attributes.
au2 secret download $SECRET | jq '.username,.password'

For more information on using jq to parse JSON in shell scripts, see the jq manual online.

From Python¶

Developers working with the Aunsight Python SDK, lib-aunsight-py can access secrets by creating a context object and getting the a secret object from that context by GUID.

from lib_aunsight import context
from lib_aunsight.lib.models import Secret
import json

# Some global variables for interacting with Aunsight
HOST = 'http://localhost:7900/' # Host address for Aunsight API
TOKEN_ID = '' # Session Token for creating a context
SECRET = '' # Secret GUID for fetching a secret within a context

# Create a context
c = context.AunsightContext(token=TOKEN, api_rest_host=HOST)

# Fetch a secret from that context
secret = c.secret(id=SECRET)

# "Download" the secret as a Python `request` library object.
secret_string = secret.download().content.decode('utf-8')

# Share your secrets carefully...
print("Pssst! The secret is %s" % secret_string)

In many cases, the secret will be stored as a JSON object which will first need to be parsed into a native Python dict object by Python's standard json library. In place of the last print statement above, do something similar to the following:

secret_dict = json.loads(secret_string)

for key in secret_dict:
    print("Key: %s;\nValue: %s" %(k, secret_dict[key]))