Configuration

The native configuration format for Conch is a TOML file, passed as a command-line argument --config.

If you are installing Conch via Helm with a values.yaml then these settings can be set under the config key, e.g.:

config:
  issuer: "https://example.com"

All the examples below show the syntax for both.

issuer
Type:
String (URL)

This must be set as a string containing the URL of the OAuth authorisation server. For example, this could be set to "https://keycloak.example.com/realms/example" (such that https://keycloak.example.com/.well-known/oauth-authorization-server/realms/example/ exists). The issuer must support OAuth 2.0 Authorization Server Metadata.

client_id
Type:
String

The OAuth client ID that is configured at issuer. For example, it could be set to "clifton".

signing_key_dir
Type:
String (path)

This must be set to the path on disk where the private SSH keys are stored. Each resource must have its own signing key, named identically to the resource ID in resources.

resources
Type:
Table

The name of the table should be a string of the name of the resource. It must contain the following keys:

alias

a short string which can be used as an SSH config Host name. You should avoid making the alias a resolvable domain name as it works best if it forms its own namespace.

hostname

a string containing the real hostname of the resource to SSH into.

proxy_jump

an optional string containing the hostname to be used by ProxyJump.

For example, it might look like:

[resources."batch.cluster1.example"]
alias = "cluster1.example"
hostname = "1.access.example.com"
proxy_jump = "bastion.example.com"

[resources."batch.cluster2.example"]
alias = "cluster2.example"
hostname = "2.access.example.com"
proxy_jump = "bastion.example.com"
mapper
Type:
Table

This must be set to the identity mapper to apply. It configures which claims (or combinations thereof) should be put into the certificate principals and returned as an association. The available options are:

single
Type:
String

A claim containing a single string which is common to all resources and should be placed verbatim into the principal list.

It will set the associations return member of the GET /sign endpoint to a mapping of resource to username.

[mapper]
single = "email"
per_resource
Type:
String

Set a username per resource.

Set this to the name of the claim that contains a JSON object with keys matching the resource names, and values being a JSON object with a single key, username with the value being the username on that resource. For example, a claim that looks like:

user claims
{
  //...
  "usernames": {
    "batch.cluster1.example": {
      "username": "foo"
    },
    "batch.cluster2.example": {
      "username": "bar"
    }
  }
  //...
}

would mean that the user has the username foo on batch.cluster1.example and bar on batch.cluster2.example and would be referenced in the config like:

[mapper]
per_resource = "usernames"

It will set the associations return member of the GET /sign endpoint to the value of that claim.

project_infra
Type:
String

This allows for a separate username for each resource and project combination.

"v1"

Use the projects claim as the basis for the principals. There should be a claim called projects which must be a JSON object containing a string key for each project ID, with the value being an object with a name member giving the human-readable project name and a resources member giving the resources (see resources) that the project is available on along with the corresponding username.

For example, this could look like:

{
  "project-a": {
    "name": "Project A",
      "resources": {
        "batch.cluster1.example": {
          "username": "user.proj-a"
        },
        "batch.cluster2.example": {
          "username": "user.proj-a"
        }
     }
  },
  "project-b": {
    "name": "Project B",
      "resources": {
        "batch.cluster2.example": {
          "username": "user.proj-b"
        }
     }
  }
}

It will set the associations return member of the GET /sign endpoint to the value of the projects claim.

[mapper]
project_infra = "v1"
extensions
Type:
Array of Strings
Default:
[]

A list of the SSH certificate extensions that should be enabled on any generated certificates. For example:

extensions = ["permit-pty", "permit-agent-forwarding"]