withKsm: Inject secrets with Keeper Secrets Manager

• application (optional)
  Array / List of Nested Object
  • credentialsId : String (optional)
  • secrets (optional)
    Array / List of Nested Object
    Setting up Keeper Notation to environmental variables.
    • notation : String (optional)

      Overview

      Notation is used to pull a value from a secret record. Notation is prefixed with keeper://. The prefix is used to designate that environmental variable contains notation.

      The notation is divided into three parts separated by a forward slash.

      Record UID / <field|custom_field|file> / Label, Type, or File Name

      The first part is the UID of the record.

      The second is an enumeration for the three places a value can be stored in a secret.

      • field - Standard field of the record, which are based on the record type. Examples of these are login and password. The field is referenced by its type.
      • custom_field - Custom fields a user can attach to a secret. The field is referenced by its label or its type.
      • file - Attached files on a record. The field is referenced by its file name.

      The third part is how the field is referenced. This is either the field type, label or name of the file. Some fields are complex. They can include multiple values and also dictionaries for the values.

      Examples

      Below is a record that contains the structure found in a record. The examples will reference this structure.

          $ ksm secret get --title "My Record" --json
      
          {
              "uid": "Atu8tVgMxpB-iO4xT-Vu3Q",
              "title": "My Database",
              "type": "databaseCredentials",
              "fields": [
                  {
                      "type": "text",
                      "value": [
                          "postgresql"
                      ]
                  },
                  {
                      "type": "host",
                      "value": [
                          {
                              "hostName": "db.hostname",
                              "port": "5432"
                          }
                      ]
                  },
                  {
                      "type": "login",
                      "value": [
                          "root"
                      ]
                  },
                  {
                      "type": "password",
                      "value": [
                          "abc123"
                      ]
                  },
              ],
              "custom_fields": [
                  {
                      "label": "Admin Template",
                      "type": "text",
                      "value": [
                          "template1"
                      ]
                  },
                  {
                      "label": "Admin Contact",
                      "type": "name",
                      "value": [
                          {
                              "first": "John",
                              "middle": "X",
                              "last": "Smith"
                          }
                      ]
                  },
                  {
                      "label": "phone",
                      "type": "phone",
                      "value": [
                          {
                              "number": "555-5555555",
                              "ext": "55",
                              "type": "Work"
                          },
                          {
                              "number": "777-7777777",
                              "ext": "77",
                              "type": "Home"
                          }
                      ]
                  }
              ],
              "files": [
                  {
                      "name": "orm.svg",
                      "title": "orm.svg",
                      "type": "mage/svg+xml",
                      "last_modified": 1622044028400,
                      "size": 30744
                  },
              ]
          }
      

      Example 1 - Simple Values

      A simple values is where there is only one literal value for the field. It looks like an array with only one string value. For our Database record type sample, the following will return a single value.

      keeper://Atu8tVgMxpB-iO4xT-Vu3Q/field/text
keeper://Atu8tVgMxpB-iO4xT-Vu3Q/field/login
keeper://Atu8tVgMxpB-iO4xT-Vu3Q/field/password
keeper://Atu8tVgMxpB-iO4xT-Vu3Q/custom_field/Admin Template


      If you attempt to retrieve a simple value of the field that contains a complex, you will get a JSON value. The notation keeper://Atu8tVgMxpB-iO4xT-Vu3Q/field/host would return {"hostName": "db.hostname", "port": "5432"}.

      Also if retrieving a simple value of a field that has multiple values in array will result in only the first item being returned.

      Example 2 - Arrays and Dictionaries

      Arrays

      Some fields contain multiple values. The additional values can be accessed using a index that starts at 0. This means the first value has an index of 0, the second has an index of 1, and so on. The following notation ..

      keeper://Atu8tVgMxpB-iO4xT-Vu3Q/custom_field/phone[1]

      would return the second item in the array.

      {"number": "777-7777777", "ext": "77", "type": "Home"}

      Dictionaries

      Some values are dictionaries. For example the phone and host fields.

      keeper://Atu8tVgMxpB-iO4xT-Vu3Q/custom_field/phone[1][number]
keeper://Atu8tVgMxpB-iO4xT-Vu3Q/custom_field/host[hostName]


      To get the specific value in the dictionary, add the key to the notation.

      Example 3 - The Full Value

      To get the full value, the entire array returned in a JSON format, just use an empty []. The following notation

      keeper://Atu8tVgMxpB-iO4xT-Vu3Q/custom_field/phone[]

      would return the entire value in a JSON format.

      [{"number": "555-5555555", "ext": "55", "type": "Work"}, {"number": "777-7777777", "ext": "77", type": "Home"}]

      Example 4 - Files

      With notation, you can download files into an environmental variables. This works well with text based files, however mileage may var with binary files. Binary files may cause exceptions to be thrown. Also, there is a limit on the size of the file based on your OS's handling of environmental variables.

      keeper://Atu8tVgMxpB-iO4xT-Vu3Q/file/orm.svg
    • destination : String (optional)
    • envVar : String (optional)

      The environmental variable the secret will be placed.

      Environmental variables can only contain letters, numbers, and underscores (_). Spaces are not allowed. The environmental variable also cannot start with a number.

    • filePath : String (optional)

      The optional directories and file name, in the workspace, where the secret file will be created. If the directories in the path do not exist, they will be created.

      The file will be removed when the path is done. Any directories created will not be removed. If you copy the secret file in your script, the copy will not be removed.