The following plugin provides functionality available through Pipeline-compatible steps. Read more about how to integrate steps into your Pipeline in the Steps section of the Pipeline Syntax page.

For a list of other such plugins, see the Pipeline Steps Reference page.

Keeper Secrets Manager

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.


Was this page helpful?

Please submit your feedback about this page through this quick form.

Alternatively, if you don't wish to complete the quick form, you can simply indicate if you found this page helpful?

    


See existing feedback here.