Skip to content

Commit

Permalink
Update README to describe new RESTful API
Browse files Browse the repository at this point in the history
  • Loading branch information
@stevapple
stevapple committed Aug 27, 2024
1 parent 88fed75 commit 324e3ad
Showing 1 changed file with 74 additions and 28 deletions.
102 changes: 74 additions & 28 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -84,31 +84,77 @@ Recovery settings configures Vlab recovery service support of `sshmux`. They are
| `usernames` | `[]string` | Usernames dedicated to the recovery server. | No | `["recovery", "console"]` |
| `token` | `string` | Token used to authenticate with the recovery backend. | No | `"long-and-random-token"` |

## API server

`sshmux` requires an API server to perform authentication and authorization for a user.

The API accepts JSON input with the following keys:

| Key | Type | Description |
| ----------------- | -------- | -------------------------------------------------------------------------------------------------------- |
| `auth_type` | `string` | The authentication type. Always set to `"key"` at the moment. |
| `username` | `string` | Vlab username. Omitted if the user is authenticating with public key. |
| `password` | `string` | Vlab password. Omitted if the user is authenticating with public key. |
| `public_key_type` | `string` | SSH public key type. Omitted if the user is authenticating with username and password. |
| `public_key_data` | `string` | Base64-encoded SSH public key payload. Omitted if the user is authenticating with username and password. |
| `unix_username` | `string` | UNIX username the user is requesting access to. |
| `token` | `string` | Token used to authenticate the `sshmux` instance. |

The API responds with JSON output with the following keys:

| Key | Type | Description |
| ---------------- | --------- | ---------------------------------------------------------------------------------------------------------------- |
| `status` | `string` | The authentication status. Should be `"ok"` if the user is authorized. |
| `address` | `string` | TCP host and port of the downstream SSH server the user is requesting for. |
| `private_key` | `string` | SSH private key to authenticate for the downstream. |
| `cert` | `string` | The certificate associated with the SSH private key. |
| `vmid` | `integer` | ID of the requested VM. Only used for recovery access. |
| `proxy_protocol` | `integer` | PROXY protocol version to use for the downstream. Should be `1`, `2` or omitted (which disables PROXY protocol). |

Note that if the user is not authorized, the API server should return a `status` other than `"ok"`, and other keys can be safely ommitted.
## Auth API

`sshmux` uses a RESTful API to perform authentication and authorization for a user.

### `POST /v1/auth/:username`

#### Input

| Key | Type | Description | Position | Optional |
| ----------------- | --------------------- | ---------------------------------------------------------------------------------------- | -------- | -------- |
| `username` | `string` | SSH user name. Usually the one for logging in the target server. | Path | No |
| `method` | `string` | SSH authentication method. Usually one of `none`, `publickey` or `keyboard-interactive`. | Body | No |
| `public_key` | `string` | User public key, serialized in OpenSSH format. | Body | Yes |
| `payload` | `Map<string, string>` | Authentication payload constructed from interactive input. | Body | Yes |

#### Output: `200 OK`

| Key | Type | Description | Optional |
| ---------------- | ----------------------- | ----------------------------- | -------- |
| `upstream` | [`Upstream`](#upstream) | SSH upstream information. | No |
| `proxy` | [`Proxy`](#proxy) | PROXY protocol configuration. | Yes |

##### `Upstream`

| Key | Type | Description | Optional |
| ------------- | -------- | --------------------------------------------------------------------------- | -------- |
| `host` | `string` | Host name or IP of upstream SSH server. | No |
| `port` | `uint` | Port number of upstream SSH server. Defaults to `22`. | Yes |
| `private_key` | `string` | Private key for authenticating with upstream, serialized in OpenSSH format. | Yes |
| `certificate` | `string` | Certificate for authenticating with upstream, serialized in OpenSSH format. | Yes |
| `password` | `string` | Password for authenticating with upstream. | Yes |

##### `Proxy`

| Key | Type | Description | Optional |
| ------------- | -------- | ----------------------------------------------------------------------------------- | -------- |
| `host` | `string` | Host name or IP of the proxy server. Defaults to `upstream.host`. | Yes |
| `port` | `uint` | Port number of the proxy server. Defaults to `upstream.port`. | Yes |
| `protocol` | `string` | PROXY protocol version to use. Must be one of `"v1"` or `"v2"`. Defaults to `"v2"`. | Yes |

#### Output: `401 Not Authorized`

| Key | Type | Description | Optional |
| ------------ | --------------------------- | ------------------------------------------------------------------------------------------------ | -------- |
| `challenges` | [`[]Challenge`](#challenge) | Challenges for extra inputs from user. Only applicable to `keyboard-interactive` authentication. | No |

##### `Challenge`

| Key | Type | Description | Optional |
| ------------- | ------------------------------------- | ---------------------------------- | -------- |
| `instruction` | `string` | Instruction for the challenge. | No |
| `fields` | [`[]ChallengeField`](#challengefield) | Requested fields by the challenge. | Yes |

##### `ChallengeField`

| Key | Type | Description | Optional |
| -------- | -------- | ---------------------------------------------------------- | -------- |
| `key` | `string` | Key to set the user input on. | No |
| `prompt` | `string` | Prompt for the input field. | No |
| `secret` | `bool` | Whether to treat the input as secret. Defaults to `false`. | Yes |

#### Output: `403 Forbidden`

| Key | Type | Description | Optional |
| --------- | --------------------- | ------------------------- | -------- |
| `failure` | [`Failure`](#failure) | Auth failure information. | Yes |

##### `Failure`

| Key | Type | Description | Optional |
| ------------ | -------- | --------------------------------------------------------------------------- | -------- |
| `message` | `string` | Message from the server to describe the failure. | No |
| `disconnect` | `string` | Whether to disconnect the downstream user. Defaults to `false`. | Yes |
| `reason` | `uint` | SSH disconnect reason code. Defaults to `11` (`DISCONNECT_BY_APPLICATION`). | Yes |

0 comments on commit 324e3ad

Please sign in to comment.