HTTP API¶

Conch provides a HTTP API to perform signing requests.

GET /sign¶

Sign a public SSH key, using the provided JWT to authorise.

Example request:

GET /sign?public_key=ssh-ed25519%20AAAAC3NzaC1lZ<example-snipped> HTTP/1.1
Host: example.com
Accept: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cC<example snipped>

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "resources": {
    "batch.cluster1.example": {
      "alias": "cluster1.example",
      "hostname": "1.access.example.com",
      "proxy_jump": "bastion.example.com"
    },
    "batch.cluster2.example": {
      "alias": "cluster2.example",
      "hostname": "2.access.example.com",
      "proxy_jump": "bastion.example.com"
    }
  },
  "associations": {
    "project-a": {
      "name": "Project A",
      "resources": {
        "batch.cluster1.example": {
          "username": "user.proj-a",
          "certificate": "ssh-ed25519-cert-v01@openssh.com AAAAIHNzaC<example snipped>"
        },
        "batch.cluster2.example": {
          "username": "user.proj-a",
          "certificate": "ssh-ed25519-cert-v01@openssh.com AAAAIHNzaC<example snipped>"
        }
      }
    },
    "project-b": {
      "name": "Project B",
      "resources": {
        "batch.cluster2.example": {
          "username": "user.proj-b",
          "certificate": "ssh-ed25519-cert-v01@openssh.com AAAAIHNzaC<example snipped>"
        }
      }
    }
  },
  "user": "test@example.com",
  "version": 3
}

Query Parameters:

public_key (string) – the SSH public key to sign

Request Headers:

Authorization – an OAuth access token in JWT form. See Claims required for more information on the contents.

Response JSON Object:

resources (Resources) – the resources the certificate can be used on. See resources for the structure.

associations (Associations) –

The associations between the resources and their projects or user details.

Depending on the value of mapper, the contents of this will vary:

single/per_resource:

"associations": {
  "resources": {
    "batch.cluster1.example": {
      "username": "foo",
      "certificate": "ssh-ed25519-cert-v01@openssh.com AAAAIHNzaC<example snipped>"
    },
    "batch.cluster2.example": {
      "username": "bar",
      "certificate": "ssh-ed25519-cert-v01@openssh.com AAAAIHNzaC<example snipped>"
    }
  }
}

project_infra v1:

"associations": {
  "project-a": {
    "name": "Project A",
    "resources": {
      "batch.cluster1.example": {
        "username": "user.proj-a",
        "certificate": "ssh-ed25519-cert-v01@openssh.com AAAAIHNzaC<example snipped>"
      },
      "batch.cluster2.example": {
        "username": "user.proj-a",
        "certificate": "ssh-ed25519-cert-v01@openssh.com AAAAIHNzaC<example snipped>"
      }
    }
  },
  "project-b": {
    "name": "Project B",
    "resources": {
     "batch.cluster2.example": {
       "username": "user.proj-b",
        "certificate": "ssh-ed25519-cert-v01@openssh.com AAAAIHNzaC<example snipped>"
      }
    }
  }
},

user (string) – the email address of the user
version (integer) – the version of the response. Currently 3.

GET /issuer¶

Deprecated since version 0.3: Use GET /oauth instead.

Get the URL of the OAuth issuer.

Example request:

GET /issuer HTTP/1.1
Host: example.com

Example response:

HTTP/1.1 200 OK

https://keycloak.example.com/realms/example

GET /oidc¶: Deprecated since version 0.4: Use GET /oauth instead.

GET /oauth¶

Added in version 0.3.

Get the details of the OAuth authorisation server and client information to use.

Example request:

GET /client_id HTTP/1.1
Host: example.com

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "issuer": "https://keycloak.example.com/realms/example",
  "client_id": "clifton",
  "version": 1
}

Response JSON Object:

issuer (string) – the URL of the OAuth issuer.
client_id (string) – the ID of the OAuth client to use when talking to the issuer.
version (integer) – the version of the response. Currently 1.

GET /public_key¶

Added in version 0.2.

Get the public part of the currently used signing key.

Example request:

GET /public_key HTTP/1.1
Host: example.com

Example response:

HTTP/1.1 200 OK

ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIBsaKBqZPg<example snipped>

GET /health¶

Added in version 0.1.3.

Check the health of the service.

Example request:

GET /health HTTP/1.1
Host: example.com

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{}

Status Codes:

200 OK – Conch is running and working.