Conch¶
Contents:
Conch is an SSH certificate issuer which authenticates using OIDC 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 OIDC as OIDC issuer actor Client participant Conch Client->>OIDC: Authenticate OIDC->>Client: Access token (JWT) Client->>+Conch: /sign<br/>Passing the JWT Conch->>OIDC: 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 platform.
- Platform¶
A platform is a collection of resources. In the context of Conch, it 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.