Credentials Vault

The management of credentials in the Kentik portal is discussed in the following topics:

• About Credentials Vault
• Credentials Vault Page
• Credential Settings Dialogs
• Manage Credentials
• API Test Credentials Tutorial

A high-level look at Kentik’s Credentials Vault is provided in the following topics:

• Credentials Vault Overview
• About Credentials
• Credential Portal Usage

The Credentials Vault enables you to save credentials centrally and securely so that they can be used on different configuration pages throughout the Kentik portal. In the event that one of your credentials needs to be updated, updating it once in the Credentials Vault will update it everywhere it is used.

When we talk about credentials in the Kentik portal it involves four main terms:

• Key: The name by which the system calls up a key/value pair’s value. Each key within a single credential must be unique so that it can be distinguished from all other keys in the credential.
• Value: The character string (e.g. email address, password) that is provided to the system when its key is called (see Credential Values).
• Key/value pair: A 1:1 mapping of one key and one value where the value is accessed by “calling” the key.
• Credential: One or more key/value pairs saved under a single name with a description, type, and label(s).

When credentials are stored in the Credentials Vault, they’re double-encrypted using AES256. Each organization will have their own unique encryption key, which we use in conjunction with IV (Initialization Vector) to encrypt all key/value sets before storing them in the Credentials Vault. An additional global encryption key is stored in our own secure key management system. Once a credential has been saved, while the values of a credential can be reset when needed, they can never be viewed or unmasked (values are write-only).

Credentials are currently used in the portal for Kentik-registered devices and HTTP synthetic tests in the Test Control Center.

For Devices, credentials are used on the following tabs of a device settings dialog:

• SNMP: Under Collection method, check the For NMS via Universal Agent checkbox (see Device SNMP Settings).
• Streaming Telemetry: Under Collection method, check Dial-In from Universal Agent (see Device ST Settings).

When you check one of the above checkboxes, a pane will open that includes a Credential drop-down, which includes all credentials to which you have access (that are of the same type as the selected collection method). You can select one of these existing credentials or choose New Credential to create (and automatically add) a new credential for that device (see Add SNMP Device Credential or Add ST Device Credential).

Credentials are currently supported in Synthetics for the following HTTP tests, where they are selected using a Credentials Vault button that is present on the below-indicated tabs of the Test Settings Page (see Set HTTP Test Credentials):

• Transaction: On the Target and Agents tab.
• Page Load: On the HTTP tab, in the Configure Request section when the Headers tab is selected.
• HTTP(S) or API: On the HTTP tab, in the Configure Request section (for use with the Headers and/or Body tabs).
  Note: For a step-by-step walk-through of creating a credential and using it with an HTTP(S) or API test, see API Test Credentials Tutorial.

Note: To determine which synthetic tests use specific credentials, use the Credentials filter in the Tests List Filters on the Test Control Center page.

The Credentials Vault page is covered in the following topics:

• About the Credentials Vault
• Credentials Vault Page UI
• Credential List Filters
• Credential List

The Credentials Vault page is home to the Credential List, which displays all of the credentials to which you have access in the Kentik portal. To access the page, choose Credentials Vault from the Organization Settings menu on the portal's main navbar.

Note: While Member-level users can access the Credentials Vault page and use credentials (if they have the adequate RBAC permissions), they cannot add new credentials. Only Administrator-level users can add or modify credentials (see About Users).

The Credentials Vault page includes the following UI elements:

• Add Credential: A button (visible only to Administrator-level users) that opens the Add Credential dialog where you can create a new credential (see Credential Settings Dialogs).
• Show/Hide Filters: A button (filter icon) that toggles the Filters pane between expanded and collapsed.
• Group by: A drop-down from which you can choose how to group the credentials on the list. You can group by:
  - None: Credentials are not grouped.
  - Type: Credentials are grouped by type (e.g. Basic Authentication, SNMP etc.).
  - Usage: Credentials are grouped by whether or not they’re currently used in the Kentik portal.
• Search: A field that shows lozenges for the filters currently set in the Filters pane and also enables you to enter text. The Credential list will be filtered to show only rows in which there's a match between the entered text and the Type or Name columns. Click the X at the right of the field to clear entered text, and the X in a lozenge to clear the corresponding filter.
• Filters: A pane with controls that narrow the credentials shown in the Credential List (see Credential List Filters).
• Credential list: A table listing the credentials in your organization to which you have access (see Credential List).

The Filters pane at the left of the Credential List narrows the list to credentials that match the specified criteria. When a filter is added with this pane, a lozenge for the filter appears in the Search field (see Credentials Vault Page UI).

The Filters pane includes the following controls:

• Clear all (appears only when you’ve specified one or more filters): Clears all current filters.
• Type: Checkboxes that filter the list of credentials by Credential Type.
• Labels: A field that displays a lozenge for each selected label and filters the Credentials list to credentials with those Labels. To select a label, click in the field and choose the label from the filterable drop-down list. To remove a label, click the X at the right of that label's lozenge.
  Note: Only labels currently applied to one or more credentials are displayed in the list.
• Created by: Checkboxes that filter the list of credentials by the user who created it.

The Credential list is a table that lists all credentials saved in your organization. To change the sort order of the list, click a heading to select a column, and click the resulting blue up or down arrow to choose the sort direction (ascending or descending).

The Credential list includes the following columns:

• Name: The name given to the credential. If provided, the description appears below the credential’s name, with any applied labels appearing below the description.
• Type: The type of credential (see Credential Type).
• Keys: The key name(s) provided for this credential. The key names are displayed alphabetically and do not reflect the order in which they were created, nor (in the case of Credential Type system templates) how they are displayed with the credential settings dialogs.
• Used By: The ways in which this credential is being used in the portal (e.g. in a Synthetics test). When in use, click the link to navigate to where in the portal it is used (e.g. Devices page or the Test Control Center), where the list is filtered to see only the elements that use the credential. If the credential is not currently used in the portal, this column reads “Not In Use”.
• Created By: The name of the user who created the credential.
• Last Updated: The date and time when the credential was last edited.
• Edit (Administrator-level users only): A button (pencil icon) that opens the Edit Credential dialog (see Credential Settings Dialogs).
• Remove (Administrator-level users only): A button (trash icon) that opens a confirming dialog that allows you to remove the credential from your organization.

Adding or editing a credential involves specifying information in the fields of a credential settings dialog (Add Credential or Edit Credential), which is covered in the following topics:

• Credential Settings UI
• Credential Settings Definitions
• Credential Labels
• Credential Type
• Credential Values

Note: The credential settings dialogs are visible only to Administrator-level users.

Both credential settings dialogs include the following fields and controls:

• Cancel: A control — either the X at the upper right or the Cancel button at the lower right — that exits the dialog while leaving all settings as they were when it was opened.
• Add Credential (Add Credential dialog only): Saves the dialog’s current settings and exits the dialog.
• Save (Edit Credential dialog only): Saves the dialog’s current settings and exits the dialog.

The credential settings dialogs (Add Credential and Edit Credential) include the elements shown in the following table.

Applying labels to your credentials provides a way to easily find and filter them within both the Credential list and the Credentials Vault Popup (when creating a Synthetics test). The Labels field in the credential settings dialogs displays a lozenge for each selected label. To select a label to apply to the credential, click in the field and choose the label from the filterable drop-down list. To remove a label, click the X at the right of that label’s lozenge.

Note: In the future, labels will be linked with RBAC roles, enabling them to grant permissions that allow access to and/or modification of data throughout the portal.

When a credential is created or edited it is assigned one of eight different credential types. Each of these credential types uses one or the other of the following key types:

• System template: Keys are defined in pre-set system templates, in which the number of keys and their assigned names are fixed and cannot be changed (they appear grayed out in the Credential Settings Dialogs).
• Unstructured: The number of key/value pairs and the name(s) of the keys can be customized.

The following table details the keys and values available for each of the available credential types.

Notes:
- A user-defined key name can contain only alphanumeric characters, underscores, and dashes.
- If you change a credential’s type, recheck the value of each of its keys.

Keys for Unstructured Credentials

When naming keys and values for unstructured credentials, editable key fields accept only alphanumeric characters, dashes, or hyphens so that the credentials can be used in HTTP Transaction tests within a Javascript/Puppeteer script. Each key name must be unique, and we recommend that the names are self-explanatory and descriptive. Once a credential is saved, the value of any Key field will no longer be editable, though you can edit the credential itself by adding more key/value pairs.

Note: The key/value pairs of a saved credential are listed — in the Edit Credential dialog or in a Credentials Vault Popup in a Synthetics test — in alphabetical order by key name, not in the order they were added.

A credential value is a character string (e.g. email address or password) that is provided to the system when its paired key is requested on the portal.

When you first enter text into a Value field of a credential settings dialog, you can click the eye icon to see the text you’ve entered. Once the credential is saved, however, the contents of the Value field can no longer be viewed (each value is write-only). Each Value field with a saved value will show asterisks to represent an entered value. When a credential’s value is copied from the Credentials Vault Popup, a programmatic representation (or variable) is used to maintain the value’s security (see Value Variables).

While you cannot unmask the contents of a saved Value field, you can reset it (Update a Credential Value) or delete the credential (Remove a Credential). When you update (or reset) a value, the same visibility conditions apply - you can view it while editing the field, but once it’s saved, its value is masked and cannot be viewed.

The only exceptions to the value masking described above are for the values of the authentication_protocol and privacy_protocol keys for the credential type SNMP v3 Authentication. The options selected in these two fields are visible even after the credential is saved.

Note: Currently, any administrator-level user can create, edit, or delete a credential, whether that user created the credential or not.

When creating a Synthetics test involving a credential, the credential's settings can be specified with strings that you've copied from the Credentials Vault Popup. When pasted into a Key field, the text will display as a programmatic representation (variable) of the actual value. The structure of the variable string will be $vault(‘credential_name.key_name'), where:

• $vault is a vault function that calls the set specified in the following parentheses.
• () (the contents of the parentheses) show what is being called from the Credentials Vault.
• credential_name is the credential’s name.
• The period (.) separates the credential’s name from the key’s name.
• key_name is the credential’s key name.

The management of credentials is covered in the following sections:

• Add a Credential
• Edit a Credential
• Use a Credential
• Remove a Credential

There are currently three different places in the portal where you can create a new credential: the Credentials Vault Page, the SNMP tab of a device settings dialog, and the Streaming Telemetry tab of that dialog.

Notes:
- The Credential Name field accepts only alpha-numeric characters, dashes, and underscores.
- Credentials created in the settings dialog for a device can only be edited or removed on the Credentials Vault page.
- To add labels or descriptions to credentials created in the settings dialog for a device, edit the credential from the Credentials Vault page (see Edit a Credential).
- A newly created credential will immediately be listed in the Credential List.

To add a new credential from the Credentials Vault (CV) page:

1. Open the page by choosing Credentials Vault from the Organization Settings menu on the portal's main navbar.
2. Click the Add Credential button to open the Add Credential dialog.
3. Specify the values of the fields in the dialog (see Credential Settings Definitions).
4. Click Add Credential to save your changes. Your credential should now appear in the Credential list.

Notes:
- When adding a key/value pair the eye icon in the Value field will reveal the entered value string.
- Once the credential is saved, the contents of its Value fields will be masked and cannot be revealed.

To add a new credential for SNMP when adding or editing a device (see Device SNMP Settings):

1. On the Settings » Devices page, open the dialog by clicking the Add Device button or the Edit button (pencil icon) at the right of a row in the Device list.
2. Click the SNMP tab of the dialog.
3. Check the For NMS via Universal Agent checkbox. The For NMS via Universal Agent pane will appear.
4. From the Credential drop-down, choose New Credential, which opens the Add SNMP Credential Dialog.
5. Use the Type radio buttons to choose an SNMP version (v1, v2, or v3).
6. Enter a value in the following fields:
   - Credential Name
   - Community (for v1 and v2)
   - User Name, Authentication type and value, and Privacy type and value (for v3).
7. Click Add Credential to close the Add SNMP Credential dialog and save the credential, which will be selected in the Credential field.
8. If you also need to add a credential for Streaming Telemetry, see Add ST Device Credential. Otherwise, if you're done with all other settings for the device, click either the Add Device button (when adding a device) or the Save button (when editing a device).

To add a new credential for Streaming Telemetry (ST) when adding or editing a device (see Device ST Settings):

1. On the Settings » Devices page, open the dialog by clicking the Add Device button or the Edit button (pencil icon) at the right of a row in the Device list.
2. Click the Streaming Telemetry tab of the dialog.
3. Check the Dial-In from Universal Agent checkbox. The Dial-In from Universal Agent pane will appear.
4. From the Credential drop-down, choose New Credential to open the Add Streaming Telemetry Credential dialog.
5. Enter a value in the following fields:
   - Credential Name
   - User Name
   - Password
6. Click Add Credential to close the Add Streaming Telemetry Credential dialog and save the credential, which will be selected in the Credential field..
7. If you also need to add a credential for SNMP, see Add SNMP Device Credential. Otherwise, if you're done with all other settings for the device, click either the Add Device button (when adding a device) or the Save button (when editing a device).

To edit the settings for an existing credential:

1. Open the Credentials Vault page from the Organization Settings menu on the portal's main navbar.
2. In the Credential List, find the row corresponding to the credential you’d like to edit, and click the Edit button. The Edit Credential dialog will open.
3. Edit the existing credential setting(s) you'd like to change (see Credential Settings Definitions).
   Note: If you change a credential’s type, recheck the value of each of its keys.
4. To add a new key/value pair to the credential, click the Add button (see Add a Key/Value Pair).
5. Click Save to save your changes.

Note: Once a credential is saved, its key/value pairs can't be removed, and all Key fields are read-only; they can't be changed. The value of keys, however, can still be edited (see Update a Credential Value).

If a credential's key type is Unstructured (see Keys by Credential Type), you can add a key/value pair by clicking the Add button. A new set of key/value fields will be added to the Key list:

• The new Key field will only be editable until you click Save.
• The Remove button (trash icon) to the right of the Value field will be present only until you click Save. After saving, you cannot remove a key/value pair from a credential.

Notes:
- After saving, when you open the Edit Credential dialog, the list of key/value pairs is ordered alphabetically by Key name.
- If a credential's key type is System Template, you can't add or modify key/value pairs.

While you can't delete a saved key/value pair, you can update a key's value:

1. Open the Credentials Vault page from the Organization Settings menu on the portal's main navbar.
2. In the Credential List, find the row corresponding to the credential you’d like to edit, and click the Edit button. The Edit Credential dialog will open.
3. Enter a new string in the Value field you’d like to modify.
   Note: The field only permits alpha-numeric characters, dashes, and underscores.
4. To verify the new string, click the eye icon to reveal the contents of the Value field.
5. Click Save. The value is updated everywhere in the portal where that credential is used.

In the Kentik portal, you can currently use credentials in two distinct contexts, the steps for which are covered in the topics below:

• Devices: Credentials may be used to authorize SNMP polling of a device and/or the publication of Streaming Telemetry data from a device (see Credentials for Devices):
  - To set a credential for device SNMP polling, see Add SNMP Device Credential.
  - To set a credential for Streaming Telemetry from a device, see Add ST Device Credential.
• Synthetics Tests: Credentials may be used to authenticate for tests whose type is in the HTTP category (see Credentials for HTTP Tests). To set a credential for an HTTP test, see Set HTTP Test Credentials.
  Note: The minimum synthetics agent version for credentials support is 0.6.10.

In Synthetics, credentials may be used to provide authentication information in tests whose type is in the HTTP category:

1. On the Synthetics » Test Control Center page, click the Add Test button at top right.
2. In the Application section of the page, click one of the following HTTP test types to open a Test Settings Page for the new test:
   - HTTT(S) or API
   - Page Load
   - Transaction
3. On the settings page, click the Credentials Vault button to pop up the Credentials Vault Popup. The conditions under which the button is present depend on the type of the test:
   - HTTP(S)/API and Page Load tests: The Credentials Vault button is on the HTTP tab, but is shown only when the tab of the Configure Request table is either Headers or Body.
   - Transaction tests: The button is on the Target and Agents tab.
4. Filter the list of credentials by credential name or by any assigned labels. The credential(s) that match the provided criteria will be listed under Credentials in the Credentials Vault popup.
   Note: Filtering by credential name is case sensitive.
5. Click the arrow to the right of a credential’s name to expand it. The credential's key names will be listed under Values.
6. Click the Copy button beside a key name (e.g. auth_email_header) to copy the key's value.
7. Paste it into the Key field of the Headers tab of the Configure Request table on the Test Settings Page. The value will be displayed in this field as a programmatic variable (see Value Variables).
8. Repeat steps 6 to 7 for any other values that you need to add to the test (e.g. auth_email_value, auth_api_token_header, and auth_api_token_value; see Creating a Test in the API Test Credentials Tutorial).
9. Click the X to close the Credentials Vault popup.
10. Complete any remaining settings on the other Test Settings Tabs.
11. Ensure the test is error-free and preview if needed (see Test Preview Overview).
12. Click Create Test.

To edit the credentials of an existing HTTP test, open its Edit Test dialog (see Edit a Test), complete steps 3 to 11, and click Save.

To remove a credential from your organization’s list of credentials:

1. Open the Credentials Vault page from the Organization Settings menu on the portal's main navbar.
2. In the Credential List, find the row corresponding to the credential you’d like to remove, then click the Remove button at the right of the row.
3. Click Remove in the resulting confirmation dialog.

This section will walk you through the use of credentials in Synthetics, which involves creating an example credential (with four key-value pairs) and then using the credential's values in an HTTP(S) or API test that tests against our Label APIs.

The steps we’ll take for this example include:

• Finding Header Elements
• Creating a Credential
• Creating a Test

We need the following four things to create the credential that we'll use to authenticate against the API:

• A header name for the user's email address
• A header value for the email address
• A header name for the user's API token
• A header value for the API token

To find these elements, we’ll perform the following steps:

1. In the Kentik portal, navigate from the main navbar menu to the API Tester and click Label Management API in the API list.
2. On the Label Management API page, click the Swagger tab.
3. In the LabelService pane, click on the row for the GET method. The row will expand.
4. In the Parameters section, click the Try it Out button. A blue Execute button appears.
5. Click Execute, which opens the Responses section.
   
6. In the Curl section of Responses, note the following header names and values:
   - Email header name: X-CH-Auth-Email
   - Email header value: r.song@tardis.time (placeholder for actual address)
   - API token header name: X-CH-Auth-API-Token
   - API token header value: 718bc4cc02e10139b46a4e31efa2face (placeholder for actual token)

To create a new credential:

1. From the Credentials Vault page, click Add Credential. The Add Credential dialog will open.
2. In the Name field, enter a name using only alpha-numeric characters, dashes, and underscores, for example “TimeLord Credentials."
3. In the Description field, enter a description for the credential.
4. Select a Type, for example "Other."
5. Add the appropriate labels. We'll use these labels to easily find our credentials when making a synthetic test or filtering the Credential List.
6. Click the Add button three times to create a total of four different sets of Key and Value fields for the credential.
7. In each of the four Value fields of the dialog, paste one of the four elements we obtained in Finding Header Elements. Click the eye icon to see the values you’ve entered and confirm their accuracy.
   Note: After saving, these values will be masked for all users. While you can reset the value, you will no longer be able to view it.
8. In the Key field to the left of each Value field, enter the following names:
   - auth_email_header
   - auth_email_value
   - auth_api_token_header
   - auth_api_token_value
   Note: After saving, when your list of key-value pairs is displayed, it will be rearranged to alphabetical order (by key name), so it’s important use a name that is self-explanatory and/or descriptive.
9. Click Add Credential to save your credential.

To create a synthetic test which tests against our own API and uses our credential:

1. On the Synthetics » Test Control Center page, click the Add Test button at top right.
2. In the Application section of the page, click HTTP(S) or API to open a Test Settings Page for the new test.
3. On the settings page, fill in the settings of the Test Information and Target and Agents tabs.
   Note: Credentials are only supported for agents running version 0.6.10 or higher.
4. On the HTTP tab, click the Headers tab of the table in the Configure Request pane. The tab shows Key and Value fields for one key/value pair, which we'll use for the user email header.
5. Click the Add Headers button to add a second key/value pair, which we'll use for the user API token header.
6. Click the Credentials Vault button to pop up the Credentials Vault Popup. The existing credentials to which you have access will be displayed in the Credential list.
7. Use the Filter by name field (case sensitive) or the Find by labels drop-down to narrow the Credentials list and find the credential we added in Creating a Credential.
8. Click the arrow to the right of a credential’s name to expand it. The names of the credential's four keys will be listed under Values.
9. Click the Copy button beside the name that we used earlier for the email header (auth_email_header). The value of this key will be copied to your clipboard.
10. On the Headers tab in the Configure Request pane, paste the value into the Key field of the first key/value pair. The field will display the following (see Value Variables): $vault('TimeLord_Credentials.auth_email_header')
11. Back in the Credentials Vault popup, click Copy beside auth_email_value.
12. On the Headers tab in the Configure Request pane, paste the value into the Value field of the first key/value pair.
13. Repeat steps 9 to 12 to specify the next key/value pair using auth_api_token_header (Key field) and auth_api_token_value (Value field).
    
14. Click the X to close the Credentials Vault popup.
15. Complete the remaining settings for your test (Test Settings Tabs).
16. Click Preview to open the Test Preview Page to confirm that the test is set up to your expectations. Be sure to check the credit usage estimate on the top right corner of the Test Preview page or the bottom left corner of the Test Settings Page.
17. Click Create Test.