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.
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.
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.
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.
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
trueif there is secret data, or
falseif 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.
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.
After selecting a file, upload it by clicking "Submit."
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.
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
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.
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
secret_dict = json.loads(secret_string) for key in secret_dict: print("Key: %s;\nValue: %s" %(k, secret_dict[key]))