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

{
  "certificate": "ssh-ed25519-cert-v01@openssh.com AAAAIHNzaC<example snipped>",
  "platforms": {
    "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"
    }
  },
  "projects": {
    "project-a": [
      "batch.cluster1.example",
    ],
    "project-b": [
      "batch.cluster2.example"
    ]
  },
  "short_name": "test_person",
  "user": "test@example.com",
  "version": 2
}

Query Parameters:

public_key (string) – the SSH public key to sign

Request Headers:

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

Response JSON Object:

certificate (string) – the SSH certificate
platforms (Platforms) – the platforms the certificate can be used on. See platforms for the structure.
projects (Project) – the projects the user is part of. This is extracted from the projects claim.
short_name (string) – the short name of the user
user (string) – the email address of the user
version (integer) – the version of the response. Currently 2.

GET /issuer¶

Get the URL of the OIDC 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 /public_key¶

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¶

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.