Conch

Contents:

• Installation
  • Helm
  • OCI image
  • Binary
  • OAuth
• Configuration
  • issuer
  • client_id
  • signing_key_dir
  • resources
  • mapper
  • extensions
• HTTP API
  • GET /sign
  • GET /oauth
  • GET /public_key
  • GET /health

Conch is an SSH certificate issuer which authenticates using OAuth access tokens.

It is intended to be used as a part of an interactive workflow where a real human is getting access to a system via SSH.

Flow

The general high-level flow for a client interating with Conch to get a signed certificate is:

        sequenceDiagram
   participant OAuth as OAuth authorisation<br/>server
   actor Client
   participant Conch

   Client->>OAuth: Authenticate
   OAuth->>Client: Access token (JWT)

   Client->>+Conch: /sign<br/>Passing the JWT
   Conch-->>OAuth: Validate JWT
   note over Conch: Extract JWT claims and<br/>map to certificate principals

   Conch->>-Client: Signed certificate
    

Version compatibility

In order to make upgrading reliable and predictable, we define version compatibility explicitly. Conch follows SemVer with the following clarifications:

• Adding a new, required configuration variable is not backwards compatible as it will require a change by the administrator.

• Adding a new, optional configuration variable is backwards compatible.

• Changing the meaning of a configuration variable is not backwards compatible.

• Removing or changing the value of a returned JSON member is not backwards compatible.

• Adding a new member to a returned JSON object is backwards compatible.

JSON responses will contain a version member which will be an integer which increments by 1 each time a backwards-incompatible change is made to it.

We commit, as far as we are able, to making upgrading Conch with a y or z version number change to be safe

While in pre-1.0, a y version change will denote a backwards-incompatible change and a z will denote a backwards-compatible release.

Glossary

Project

A project is intended to describe a time-limited collection of users with access to a particular set of resource.

Resource

In the context of Conch, a resource is anything which can be accessed via SSH. For example it might be a specific batch cluster or a development environment.

Mapper

A configurable function which takes claims and creates principals in the SSH certificate.