Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

RESTful API for authentication #12

Merged
merged 20 commits into from
Aug 30, 2024
Merged

RESTful API for authentication #12

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
20 commits
Select commit Hold shift + click to select a range
61c095e
Mark current authenticator as legacy
stevapple Aug 24, 2024
75845fe
Initial implementation of new auth protocol
stevapple Aug 24, 2024
34ffee1
Use new API internally
stevapple Aug 24, 2024
3d8c40c
Split server host and port in new API
stevapple Aug 24, 2024
a2cf2d4
Allow using RESTful API via settings
stevapple Aug 24, 2024
8ff8056
Add tests against new API
stevapple Aug 24, 2024
659e34d
Add functionality to send headers to API
stevapple Aug 24, 2024
0f8ba33
More robust endpoint URL parsing
stevapple Aug 24, 2024
ed3872d
Replace hard-coded `log.Fatalf`s
stevapple Aug 24, 2024
f67c087
Change API response `proxy_protocol` to string
stevapple Aug 24, 2024
f2e3650
Don't rely on DTOs in tests
stevapple Aug 26, 2024
37713b4
Fix address parsing on handshake
stevapple Aug 26, 2024
88fed75
Allow fine-grained control on PROXY protocol
stevapple Aug 26, 2024
3cf9c63
Update README to describe new RESTful API
stevapple Aug 27, 2024
4a051d6
Address feedback from review
stevapple Aug 28, 2024
2cec205
Clarify that recovery settings are dedicated to legacy API
stevapple Aug 28, 2024
2816549
Fix setting headers on authentication API call
stevapple Aug 28, 2024
2d0905d
Fix potential infinite loop caused by API error
stevapple Aug 28, 2024
e575731
Replace `fmt` calls when they're unncessary
stevapple Aug 28, 2024
8256e73
Fix typos in comments
stevapple Aug 28, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
137 changes: 96 additions & 41 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,23 +37,42 @@ SSH settings configure the integrated SSH server in `sshmux`. They are grouped u

Auth settings configures the authentication and authorization API used by `sshmux`. They are grouped under `auth` in the TOML file.

| Key | Type | Description | Required | Example |
| -------------------------- | ---------- | -------------------------------------------------------------------------- | -------- | ----------------------------- |
| `endpoint` | `string` | Endpoint URL that `sshmux` will use for authentication and authorization. | Yes | `"http://127.0.0.1:5000/ssh"` |
| `token` | `string` | Token used to authenticate with the API endpoint. | Yes | `"long-and-random-token"` |
| `all-username-nopassword` | `bool` | If set to `true`, no users will be asked for UNIX password. | No | `true` |
| `usernames-nopassword` | `[]string` | Usernames that won't be asked for UNIX password. | No | `["vlab", "ubuntu", "root"]` |
| `invalid-usernames` | `[]string` | Usernames that are known to be invalid. | No | `["user"]` |
| `invalid-username-message` | `string` | Message to display when the requested username is invalid. | No | `"Invalid username %s."` |
| Key | Type | Description | Required | Example |
| ---------- | -------------- | -------------------------------------------------------------------------- | -------- | -------------------------------------------------- |
| `endpoint` | `string` | Endpoint URL that `sshmux` will use for authentication and authorization. | Yes | `"http://127.0.0.1:5000/ssh"` |
| `version` | `string` | Auth endpoint API version (`"legacy"`, `"v1"`). Defaults to `"legacy"`. | No | `"v1"` |
| `headers` | `[]HTTPHeader` | Extra HTTP headers to send to API server. | No | See [`fixtures/config.toml`](fixtures/config.toml) |

#### Legacy Auth Settings

The following settings are only used by `legacy` auth APIs. They are also grouped under `auth` in the TOML file.

| Key | Type | Description | Required | Example |
| -------------------------- | ---------- | ----------------------------------------------------------- | ------------------------------- | ---------------------------- |
| `token` | `string` | Token used to authenticate with the API endpoint. | If `auth.version` is `"legacy"` | `"long-and-random-token"` |
| `all-username-nopassword` | `bool` | If set to `true`, no users will be asked for UNIX password. | No | `true` |
| `usernames-nopassword` | `[]string` | Usernames that won't be asked for UNIX password. | No | `["vlab", "ubuntu", "root"]` |
| `invalid-usernames` | `[]string` | Usernames that are known to be invalid. | No | `["user"]` |
| `invalid-username-message` | `string` | Message to display when the requested username is invalid. | No | `"Invalid username %s."` |

#### Recovery Settings

Recovery settings configures Vlab recovery service support of `sshmux` for `legacy` auth APIs. They are grouped under `recovery` in the TOML file.

| Key | Type | Description | Required | Example |
| ----------- | ---------- | ----------------------------------------------------- | -------- | ------------------------- |
| `address` | `string` | SSH host and port of the recovery server. | No | `"172.30.0.101:2222"` |
| `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"` |

### Logger Settings

Logger settings configures the logger behavior of `sshmux`. They are grouped under `logger` in the TOML file.

| Key | Type | Description | Required | Example |
| ---------- | -------- | ----------------------------------------------------------------------------- | ---------------------- | ------------------------ |
| `enabled` | `bool` | Whether the logger is enabled. Defaults to `false`. | No | `true` |
| `endpoint` | `string` | Endpoint URL that `sshmux` will log onto. Only `udp` scheme is supported now. | If `enabled` is `true` | `"udp://127.0.0.1:5556"` |
| Key | Type | Description | Required | Example |
| ---------- | -------- | ----------------------------------------------------------------------------- | ----------------------------- | ------------------------ |
| `enabled` | `bool` | Whether the logger is enabled. Defaults to `false`. | No | `true` |
| `endpoint` | `string` | Endpoint URL that `sshmux` will log onto. Only `udp` scheme is supported now. | If `logger.enabled` is `true` | `"udp://127.0.0.1:5556"` |

### PROXY Protocol Settings

Expand All @@ -65,41 +84,77 @@ PROXY protocol settings configures [PROXY protocol](https://www.haproxy.com/blog
| `hosts` | `[]string` | Host names from which PROXY protocol is allowed. | No | `["nginx.local", "127.0.0.22"]` |
| `networks` | `[]string` | Network CIDRs from which PROXY protocol is allowed. | No | `["10.10.0.0/24"]` |

### Recovery Settings
## Auth API

Recovery settings configures Vlab recovery service support of `sshmux`. They are grouped under `recovery` in the TOML file.
`sshmux` uses a RESTful API to perform authentication and authorization for a user.

| Key | Type | Description | Required | Example |
| ----------- | ---------- | ----------------------------------------------------- | -------- | ------------------------- |
| `address` | `string` | SSH host and port of the recovery server. | No | `"172.30.0.101:2222"` |
| `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"` |
### `POST /v1/auth/:username`
stevapple marked this conversation as resolved.
Show resolved Hide resolved

#### Input

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

#### Output: `200 OK`

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

##### `Upstream`

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

##### `Proxy`

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

#### Output: `401 Not Authorized`

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

##### `Challenge`

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

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

The API accepts JSON input with the following keys:
| Key | Type | Description | Required |
| -------- | -------- | ---------------------------------------------------------- | -------- |
| `key` | `string` | Key to set the user input on. | Yes |
| `prompt` | `string` | Prompt for the input field. | Yes |
| `secret` | `bool` | Whether to treat the input as secret. Defaults to `false`. | No |

| 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. |
#### Output: `403 Forbidden`

The API responds with JSON output with the following keys:
| Key | Type | Description | Required |
| --------- | --------------------- | ------------------------- | -------- |
| `failure` | [`Failure`](#failure) | Auth failure information. | No |

| 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). |
##### `Failure`

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.
| Key | Type | Description | Required |
| ------------ | -------- | --------------------------------------------------------------------------- | -------- |
| `message` | `string` | Message from the server to describe the failure. | Yes |
| `disconnect` | `string` | Whether to disconnect the downstream user. Defaults to `false`. | No |
| `reason` | `uint` | SSH disconnect reason code. Defaults to `11` (`DISCONNECT_BY_APPLICATION`). | No |
Loading
Loading