Secret

A secret is either a username/password or name/ssh-key pair for use in securing access to repositories and other systems. Secrets can be created and managed in the Concord Console user interface as well as the Concord REST API.

The REST API provides support for the following operations related to secrets:

• Create a Secret
  • Example: Generate a new Key Pair
  • Example: Upload an Existing Key Pair
  • Example: Creating a Username and Password Secret
  • Example: Storing a Single Value as Secret
• Update a Secret
• Get Metadata of Secret
• Get Public SSH Key of Secret
• Delete a Secret
• List Secrets
• List Current Access Rules
• Update Access Rules
• Bulk Update Access Rules
• Move Secret to Another Organization

Create a Secret

Creates a new secret to be stored in Concord.

• URI /api/v1/org/${orgName}/secret
• Method POST
• Headers Authorization, Content-Type: multipart/form-data

• Multipart request

  • type - mandatory, supported types:
    • key_pair - a SSH key pair, public and private key files;
    • username_password - a pair of string values;
    • data - binary or text data.
  • name - mandatory, the name of the created secret. Must be unique for the organization;
  • storePassword - optional, a password, will be used to encrypt the created secret and which can be used to retrieve it back;
  • generatePassword - optional, a boolean value. If true, the server will automatically generate and return a storePassword value;
  • visibility - optional, PUBLIC (default) or PRIVATE. See the description of public and private resources;
  • project - optional, a project name. If set, the secret can only be used in the processes of the specified project;

  The rest of the parameters depend of the type of the created secret:

  • type=key_pair:
    • public - a public key file of the key pair;
    • private - a private key file of the key pair.
  • type=username_password:
    • username - a string value;
    • password - a string value.
  • type=data:
    • data - a string or binary value.

  For type=key_pair if a public value is omitted, a new key pair will generated by the server.

• Success response

    Content-Type: application/json
  

    {
      "id": "...",
      "result": "CREATED",
      "ok": true
    }
  

Example: Generate a new Key Pair

You can create a new key pair that is signed by the Concord server as follows:

curl -u myusername \
-F name=myKey \
-F type=key_pair \
https://concord.example.com/api/v1/org/Default/secret

After successful authentication with the provided prompted password, the server generates the new key pair and returns the public key:

{
  "id" : "e7c24546-e0e1-11e7-be9f-fa163e0708eb",
  "result" : "CREATED",
  "publicKey" : "ssh-rsa AAAAB3NzaC1...zri1 concord-server\n",
  "ok" : true
}

This key can be used a deploy key in the git repository of your project to establish the necessary trust between the Concord server and your git repository hosting system.

Example: Upload an Existing Key Pair

You can upload an existing key pair as follows:

curl -H "Authorization: auBy4eDWrKWsyhiDp3AQiw" \
-F name=myKey \
-F type=key_pair \
-F public=@/path/to/id_rsa.pub \
-F private=@/path/to/id_rsa \
https://concord.example.com/api/v1/org/Default/secret

After successful authentication with the prompted password, the server uploads and stores the files. The secret can subsequently be used within your Concord flows.

Example: Creating a Username and Password Secret

You can create a username and password secret as follows:

curl -u myusername \
-F name=myKey \
-F type=username_password \
-F username=myUser \
-F password=myPass \
https://concord.example.com/api/v1/org/Default/secret

After successful authentication with the prompted password, the server creates and stores both values with a secret. It can subsequently be used within your Concord flows.

Example: Storing a Single Value as Secret

You can store a single value as a secret on Concord as follows:

curl -u myusername \
-F name=myKey \
-F type=data \
-F data=myValue \
https://concord.example.com/api/v1/org/Default/secret

Update a Secret

Updates parameters of an existing secret.

• URI /api/v2/org/${orgName}/secret/${secretName}
• Method POST
• Headers Authorization, Content-Type: multipart/form-data

• Body Multipart binary data.

  The values will be interpreted depending on their name:

  • name - New secret name to update;
  • orgId or org - New ID or name of the organization which “owns” the secret;
  • projectId or project - New ID or name of the project for which secret will be restricted;
  • removeProjectLink - remove restriction to a project, boolean, default value is false;
  • ownerId - new secret owner identifier, UUID;
  • storePassword - current store password used to encrypt the created secret and which can be used to retrieve it back;
  • newStorePassword - new store password, storePassword is mandatory to update a new store password, secrets protected by server key cannot be updated to a password protected secret;
  • visibility - new secret visibility, PUBLIC or PRIVATE. See the description of public and private resources;
  • type - type of new secret to be updated, takes values data, username_password, key_pair;

  The secret data to be updated depends on type value and corresponding rest of the parameters are as follows:

  • type=key_pair:
    • public - a public key file of the key pair.
    • private - a private key file of the key pair.
  • type=username_password:
    • username - a string value;
    • password - a string value.
  • type=data:
    • data - a string or binary value(file).

  storePassword should be mandatory to update a password protected secret.

• Success response

    Content-Type: application/json
  

    {
      "ok": true,
      "result": "UPDATED"
    }
  

You can update a single value as a secret on Concord as follows:

curl -u myusername \
-F org=Default \
-F name=mySecret \
-F data="$(echo -n "your-secret-value" | base64)" \
http://concord.example.com/api/v1/org/Default/secret/myKey

Get Metadata of Secret

Retrieves metadata of an existing secret.

• URI /api/v1/org/${orgName}/secret/${secretName}
• Method GET
• Headers Authorization
• Body none
• Success response

    Content-Type: application/json
  

    {
      "id": "...",
      "name": "secretName",
      "orgId": "...",
      "orgName": "...",
      "projectId": "...",
      "projectName": "...",
      "type": "...",
      "storeType": "...",
      "visibility": "..."
    }
  

Get Public SSH Key of Secret

Returns a public key from an existing key pair of a secret.

• URI /api/v1/org/${orgName}/secret/${secretName}/public
• Method GET
• Headers Authorization
• Body none

• Success response

    Content-Type: application/json
  

    {
      "name": "secretName",
      "publicKey": "ssh-rsa AAAA... concord-server",
      "ok": true
    }
  

On a typical Concord installation you can pass your username and be quoted for the password:

curl -u username 'https://concord.example.com/api/v1/org/Default/secret/myKey/public'

The server provides a JSON-formatted response similar to:

{
  "name" : "myKey",
  "publicKey" : "ssh-rsa ABCXYZ... concord-server",
  "ok" : true
}

The value of the publicKey attribute represents the public key of the newly generated key.

The value of the name attribute e.g. myKey identifies the key for usage in Concord.

Delete a Secret

Deletes a secret and associated keys.

• URI /api/v1/org/${orgName}/secret/${secretName}
• Method DELETE
• Headers Authorization
• Body none

• Success response

    Content-Type: application/json
  

    {
      "ok": true
    }
  

List Secrets

List all existing secrets in a specific organization.

• Permissions
• URI /api/v1/org/${orgName}/secret
• Query parameters
  • limit: maximum number of records to return;
  • offset: starting index from which to return;
  • filter: secrets with matching name to return;
• Method GET
• Body none

• Success response

    Content-Type: application/json
  

    [
      { "name": "...", "type": "..." },
      { "name": "...", "type": "..." }
    ]
  

List Current Access Rules

Returns secrets’s current access rules.

• URI /api/v1/org/${orgName}/secret/${secretName}/access
• Method GET
• Headers Authorization
• Body none
• Success response

    Content-Type: application/json
  

    [
      {"teamId": "...", "level":  "..."},
      ...
    ]
  

Update Access Rules

Updates secrets’s access rules for a specific team.

• URI /api/v1/org/${orgName}/secret/${secretName}/access
• Method POST
• Headers Authorization, Content-Type: application/json
• Body

    Content-Type: application/json
  

    {
      "teamId": "9304748c-81e6-11e9-b909-0fe0967f269a",
      "orgName": "myOrg",
      "teamName": "myTeam",
      "level": "READER"
    }
  

  Either teamId or orgName and teamName combinations are allowed. The level parameter accepts one of the three possible values:

  • READER
  • WRITER
  • OWNER
• Success response

    Content-Type: application/json
  

    {
      "ok": true,
      "result": "UPDATED"
    }
  

• Example

    curl -ikn -H 'Content-Type: application/json' \
    -d '{"orgName": "MyOrg", "teamName": "myTeam", "level": "READER"}' \
    http://concord.example.com/api/v1/org/MyOrg/secret/MySecret/access
  

Bulk Update Access Rules

Updates secrets’s access rules for multiple teams.

• URI /api/v1/org/${orgName}/secret/${secretName}/access/bulk
• Method POST
• Headers Authorization, Content-Type: application/json
• Body

    Content-Type: application/json
  

    [{
      "teamId": "9304748c-81e6-11e9-b909-0fe0967f269a",
      "orgName": "myOrg",
      "teamName": "myTeam",
      "level": "READER"
    }]
  

  Accepts a list of access rule elements. See the non-bulk version of this method for description.

• Success response

    Content-Type: application/json
  

    {
      "ok": true,
      "result": "UPDATED"
    }
  

Move Secret to Another Organization

Moves the Secret to the specified Organization (through Organization name ID)

• URI /api/v1/org/${orgName}/secret/${secretName}
• Method POST
• Headers Authorization, Content-Type: application/json
• Body

    Content-Tupe: application/json
  

    {
      "orgName": "anotherOrg"
    }
  

  Also accepts orgId (Unique Organization ID) instead of orgName in the request body.

• Success Response

    Content-Type: application/json
  

    {
      "ok": true,
      "result": "UPDATED"
    }