9c550a8f9a
Moonraker's external API documentation has been significantly overhauled in an effort to improve clarity and readability. All parameters and responses are documented with specifications. Tables and other elements are used to make documentation more visible and less verbose. Spelling and other corrections have also been added. Signed-off-by: Eric Callahan <arksine.code@gmail.com>
636 lines
20 KiB
Markdown
636 lines
20 KiB
Markdown
|
|
# Authorization and Authentication
|
|
|
|
The Authorization endpoints provide access to the various methods
|
|
used to authorize connections to Moonraker. This includes user
|
|
authentication, API Key authentication, Temporary access via
|
|
"oneshot tokens", and IP and/or domain based authentication
|
|
("ie: trusted clients).
|
|
|
|
Untrusted clients must use either a JSON Web Token or an API key to access
|
|
Moonraker's HTTP APIs. JWTs should be included in the `Authorization`
|
|
header as a `Bearer` type for each HTTP request. If using an API Key it
|
|
should be included in the `X-Api-Key` header for each HTTP Request.
|
|
|
|
Websocket authentication can be achieved via the request itself or
|
|
post connection. Unlike HTTP requests it is not necessary to pass a
|
|
token and/or API Key to each request. The
|
|
[identify connection](./server.md#identify-connection) endpoint takes optional
|
|
`access_token` and `api_key` parameters that may be used to authenticate
|
|
a user already logged in, otherwise the `login` API may be used for
|
|
authentication. Websocket connections will stay authenticated until
|
|
the connection is closed or the user logs out.
|
|
|
|
User authentication can be performed using a choice sources. Moonraker
|
|
currently supports the following authentication sources:
|
|
|
|
| Source Name | Description |
|
|
| ----------- | -------------------------------------------------------------- |
|
|
| `moonraker` | Authentication is performed using credentials stored in |
|
|
| | Moonraker's database. |^
|
|
| `ldap` | Authentication is performed through a connected LDAP provider. |
|
|
| | Requires a valid `[LDAP]` configuration. |^
|
|
{ #auth-source-desc } Authentication Source
|
|
|
|
/// note
|
|
ECMAScript imposes limitations on certain requests that prohibit the
|
|
developer from modifying the HTTP headers (ie: Requests to open a
|
|
websocket, "download" requests that open a user dialog). In these cases
|
|
it is recommended for the developer to request a `oneshot_token`, then
|
|
send the result via the `token` query string argument in the desired
|
|
request.
|
|
///
|
|
|
|
/// warning
|
|
It is strongly recommended that arguments for the below APIs are
|
|
passed in the request's body.
|
|
///
|
|
|
|
## Login User
|
|
```{.http .apirequest title="HTTP Request"}
|
|
POST /access/login
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"username": "my_user",
|
|
"password": "my_password",
|
|
"source": "moonraker"
|
|
}
|
|
```
|
|
|
|
```{.json .apirequest title="JSON-RPC Request"}
|
|
{
|
|
"jsonrpc": "2.0",
|
|
"method": "access.login",
|
|
"params": {
|
|
"username": "my_user",
|
|
"password": "my_password",
|
|
"source": "moonraker"
|
|
},
|
|
"id": 1323
|
|
}
|
|
```
|
|
|
|
/// api-parameters
|
|
open: True
|
|
|
|
| Name | Type | Default | Description |
|
|
| ---------- | :----: | -------------------- | --------------------------------------------------- |
|
|
| `username` | string | **REQUIRED** | The user login name. |
|
|
| `password` | string | **REQUIRED** | The user password. |
|
|
| `source` | string | Set by configuration | A valid [authentication source](#auth-source-desc). |
|
|
|
|
///
|
|
|
|
/// collapse-code
|
|
```{.json .apiresponse title="Example Response"}
|
|
{
|
|
"username": "my_user",
|
|
"token": "eyJhbGciOiAiSFMyNTYiLCAidHlwIjogIkpXVCJ9.eyJpc3MiOiAiTW9vbnJha2VyIiwgImlhdCI6IDE2MTg4NzY4MDAuNDgxNjU1LCAiZXhwIjogMTYxODg4MDQwMC40ODE2NTUsICJ1c2VybmFtZSI6ICJteV91c2VyIiwgInRva2VuX3R5cGUiOiAiYXV0aCJ9.QdieeEskrU0FrH7rXKuPDSZxscM54kV_vH60uJqdU9g",
|
|
"refresh_token": "eyJhbGciOiAiSFMyNTYiLCAidHlwIjogIkpXVCJ9.eyJpc3MiOiAiTW9vbnJha2VyIiwgImlhdCI6IDE2MTg4NzY4MDAuNDgxNzUxNCwgImV4cCI6IDE2MjY2NTI4MDAuNDgxNzUxNCwgInVzZXJuYW1lIjogIm15X3VzZXIiLCAidG9rZW5fdHlwZSI6ICJyZWZyZXNoIn0.btJF0LJfymInhGJQ2xvPwkp2dFUqwgcw4OA_wE-EcCM",
|
|
"action": "user_logged_in",
|
|
"source": "moonraker"
|
|
}
|
|
```
|
|
///
|
|
|
|
/// api-response-spec
|
|
open: True
|
|
|
|
| Field | Type | Description |
|
|
| --------------- | :----: | -------------------------------------------------------------------- |
|
|
| `username` | string | The name of the logged in user. |
|
|
| `token` | string | A JSON Web Token (JWT) used to authenticate requests, also commonly |
|
|
| | | referred to as an `access token`. HTTP requests should include this |^
|
|
| | | token in the `Authorization` header as a `Bearer` type. This token |^
|
|
| | | expires after 1 hour. |^
|
|
| `refresh_token` | string | A JWT that should be used to generate new access tokens after they |
|
|
| | | expire. See the [refresh token section](#refresh-json-web-token) |^
|
|
| | | for details. |^
|
|
| `action` | string | The action taken by the auth manager. Will always be |
|
|
| | | "user_logged_in". |^
|
|
| `source` | string | The [authentication source](#auth-source-desc) used. |
|
|
|
|
///
|
|
|
|
/// note
|
|
This endpoint may be accessed without prior authentication. A 401 will
|
|
only be returned if the authentication fails.
|
|
///
|
|
|
|
## Logout Current User
|
|
|
|
```{.http .apirequest title="HTTP Request"}
|
|
POST /access/logout
|
|
```
|
|
|
|
```{.json .apirequest title="JSON-RPC Request"}
|
|
{
|
|
"jsonrpc": "2.0",
|
|
"method": "access.logout",
|
|
"id": 1323
|
|
}
|
|
```
|
|
|
|
/// collapse-code
|
|
```{.json .apiresponse title="Example Response"}
|
|
{
|
|
"username": "my_user",
|
|
"action": "user_logged_out"
|
|
}
|
|
```
|
|
///
|
|
|
|
/// api-response-spec
|
|
open: True
|
|
|
|
| Field | Type | Description |
|
|
| ---------- | :----: | ----------------------------------------------------- |
|
|
| `username` | string | The name of the logged out user. |
|
|
| `action` | string | The action taken by the auth manager. Will always be |
|
|
| | | "user_logged_out". |^
|
|
|
|
///
|
|
|
|
## Get Current User
|
|
|
|
```{.http .apirequest title="HTTP Request"}
|
|
GET /access/user
|
|
```
|
|
|
|
```{.json .apirequest title="JSON-RPC Request"}
|
|
{
|
|
"jsonrpc": "2.0",
|
|
"method": "access.get_user",
|
|
"id": 1323
|
|
}
|
|
```
|
|
|
|
Returns: An object containing the currently logged in user name, the source and
|
|
the date on which the user was created (in unix time).
|
|
/// collapse-code
|
|
```{.json .apiresponse title="Example Response"}
|
|
{
|
|
"username": "my_user",
|
|
"source": "moonraker",
|
|
"created_on": 1618876783.8896716
|
|
}
|
|
```
|
|
///
|
|
|
|
/// api-response-spec
|
|
open: True
|
|
|
|
| Field | Type | Description |
|
|
| ------------ | :----: | ---------------------------------------------------- |
|
|
| `username` | string | The name of the logged in user. |
|
|
| `source` | string | The [source](#auth-source-desc) used to authenticate |
|
|
| | | the user. |^
|
|
| `created_on` | float | The date, in unix time, the user entry was created. |
|
|
|
|
///
|
|
|
|
## Create User
|
|
|
|
Creates a new local user and logs them in.
|
|
|
|
```{.http .apirequest title="HTTP Request"}
|
|
POST /access/user
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"username": "my_user",
|
|
"password": "my_password"
|
|
}
|
|
```
|
|
|
|
```{.json .apirequest title="JSON-RPC Request"}
|
|
{
|
|
"jsonrpc": "2.0",
|
|
"method": "access.post_user",
|
|
"params": {
|
|
"username": "my_user",
|
|
"password": "my_password"
|
|
},
|
|
"id": 1323
|
|
}
|
|
```
|
|
|
|
/// api-parameters
|
|
open: True
|
|
|
|
| Name | Type | Default | Description |
|
|
| ---------- | :----: | ------------ | -------------------- |
|
|
| `username` | string | **REQUIRED** | The user login name. |
|
|
| `password` | string | **REQUIRED** | The user password. |
|
|
|
|
///
|
|
|
|
|
|
/// collapse-code
|
|
```{.json .apiresponse title="Example Response"}
|
|
{
|
|
"username": "my_user",
|
|
"token": "eyJhbGciOiAiSFMyNTYiLCAidHlwIjogIkpXVCJ9.eyJpc3MiOiAiTW9vbnJha2VyIiwgImlhdCI6IDE2MTg4NzY3ODMuODkxNjE5LCAiZXhwIjogMTYxODg4MDM4My44OTE2MTksICJ1c2VybmFtZSI6ICJteV91c2VyIiwgInRva2VuX3R5cGUiOiAiYXV0aCJ9.oH0IShTL7mdlVs4kcx3BIs_-1j0Oe-qXezJKjo-9Xgo",
|
|
"refresh_token": "eyJhbGciOiAiSFMyNTYiLCAidHlwIjogIkpXVCJ9.eyJpc3MiOiAiTW9vbnJha2VyIiwgImlhdCI6IDE2MTg4NzY3ODMuODkxNzAyNCwgImV4cCI6IDE2MjY2NTI3ODMuODkxNzAyNCwgInVzZXJuYW1lIjogIm15X3VzZXIiLCAidG9rZW5fdHlwZSI6ICJyZWZyZXNoIn0.a6ZeRjk8RQQJDDH0JV-qGY_d_HIgfI3XpsqUlUaFT7c",
|
|
"source": "moonraker",
|
|
"action": "user_created"
|
|
}
|
|
```
|
|
///
|
|
|
|
/// api-response-spec
|
|
open: True
|
|
|
|
| Field | Type | Description |
|
|
| --------------- | :----: | --------------------------------------------------------------------- |
|
|
| `username` | string | The name of the created user. |
|
|
| `token` | string | A JSON Web Token (JWT) used to authenticate requests, also commonly |
|
|
| | | referred to as an `access token`. HTTP requests should include this |^
|
|
| | | token in the `Authorization` header as a `Bearer` type. This token |^
|
|
| | | expires after 1 hour. |^
|
|
| `refresh_token` | string | A JWT that should be used to generate new access tokens after they |
|
|
| | | expire. See the [refresh token section](#refresh-json-web-token) |^
|
|
| | | for details. |^
|
|
| `action` | string | The action taken by the auth manager. Will always be "user_created". |
|
|
| `source` | string | The [authentication source](#auth-source-desc) used. |
|
|
|
|
///
|
|
|
|
/// note
|
|
Unlike `/access/login`, `/access/user` is a protected endpoint. To
|
|
create a new user a client must either be trusted, use the API Key,
|
|
or be logged in as another user.
|
|
///
|
|
|
|
## Delete User
|
|
|
|
/// note
|
|
A request to delete a user MUST come from an authorized login
|
|
other than the account to be deleted. This can be a "trusted user",
|
|
the "api key user", or any other user account.
|
|
///
|
|
|
|
```{.http .apirequest title="HTTP Request"}
|
|
DELETE /access/user
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"username": "my_username"
|
|
}
|
|
```
|
|
|
|
```{.json .apirequest title="JSON-RPC Request"}
|
|
{
|
|
"jsonrpc": "2.0",
|
|
"method": "access.delete_user",
|
|
"params": {
|
|
"username": "my_username"
|
|
},
|
|
"id": 1323
|
|
}
|
|
```
|
|
|
|
/// api-parameters
|
|
open: True
|
|
|
|
| Name | Type | Default | Description |
|
|
| ---------- | :--: | ------------ | ------------------------------------ |
|
|
| `username` | str | **REQUIRED** | The username of the entry to delete. |
|
|
|
|
///
|
|
|
|
/// collapse-code
|
|
```{.json .apiresponse title="Example Response"}
|
|
{
|
|
"username": "my_user",
|
|
"action": "user_deleted"
|
|
}
|
|
```
|
|
///
|
|
|
|
/// api-response-spec
|
|
open: True
|
|
|
|
| Field | Type | Description |
|
|
| ---------- | :----: | ------------------------------------------------- |
|
|
| `username` | string | The username of the deleted entry. |
|
|
| `action` | string | The action taken by the auth manager. Will always |
|
|
| | | be "user_deleted". |^
|
|
|
|
///
|
|
|
|
## List Available Users
|
|
|
|
```{.http .apirequest title="HTTP Request"}
|
|
GET /access/users/list
|
|
```
|
|
|
|
```{.json .apirequest title="JSON-RPC Request"}
|
|
{
|
|
"jsonrpc": "2.0",
|
|
"method": "access.users.list",
|
|
"id": 1323
|
|
}
|
|
```
|
|
|
|
/// collapse-code
|
|
```{.json .apiresponse title="Example Response"}
|
|
{
|
|
"users": [
|
|
{
|
|
"username": "testuser",
|
|
"source": "moonraker",
|
|
"created_on": 1618771331.1685035
|
|
},
|
|
{
|
|
"username": "testuser2",
|
|
"source": "ldap",
|
|
"created_on": 1620943153.0191233
|
|
}
|
|
]
|
|
}
|
|
```
|
|
///
|
|
|
|
/// api-response-spec
|
|
open: True
|
|
|
|
| Field | Type | Description |
|
|
| ------- | :------: | -------------------------------- |
|
|
| `users` | [object] | An array of `User Info` objects. |
|
|
| | | #user-info-spec |+
|
|
|
|
| Field | Type | Description |
|
|
| ------------ | :----: | ---------------------------------------------------- |
|
|
| `username` | string | The username of the entry. |
|
|
| `source` | string | The [source](#auth-source-desc) that must be used to |
|
|
| | | authenticate the user. |^
|
|
| `created_on` | float | The date, in unix time, the user entry was created. |
|
|
{ #user-info-spec } User Info
|
|
|
|
///
|
|
|
|
## Reset User Password
|
|
|
|
```{.http .apirequest title="HTTP Request"}
|
|
POST /access/user/password
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"password": "my_current_password",
|
|
"new_password": "my_new_pass"
|
|
}
|
|
```
|
|
|
|
```{.json .apirequest title="JSON-RPC Request"}
|
|
{
|
|
"jsonrpc": "2.0",
|
|
"method": "access.user.password",
|
|
"params": {
|
|
"password": "my_current_password",
|
|
"new_password": "my_new_pass"
|
|
},
|
|
"id": 1323
|
|
}
|
|
```
|
|
|
|
/// api-parameters
|
|
open: True
|
|
|
|
| Name | Type | Default | Description |
|
|
| -------------- | :----: | ------------ | ---------------------------- |
|
|
| `password` | string | **REQUIRED** | The user's current password. |
|
|
| `new_password` | string | **REQUIRED** | The user's new password. |
|
|
|
|
///
|
|
|
|
|
|
/// collapse-code
|
|
```{.json .apiresponse title="Example Response"}
|
|
{
|
|
"username": "my_user",
|
|
"action": "user_password_reset"
|
|
}
|
|
```
|
|
///
|
|
|
|
/// api-response-spec
|
|
open: True
|
|
|
|
| Field | Type | Description |
|
|
| ---------- | :----: | --------------------------------------------------- |
|
|
| `username` | string | The username of the entry whose password was reset. |
|
|
| `action` | string | Action taken by the Auth manager. Will always be |
|
|
| | | "user_password_reset". |^
|
|
|
|
///
|
|
|
|
## Refresh JSON Web Token
|
|
This endpoint can be used to refresh an expired access token. If this
|
|
request returns an error then the refresh token is no longer valid and
|
|
the user must login with their credentials.
|
|
|
|
```{.http .apirequest title="HTTP Request"}
|
|
POST /access/refresh_jwt
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"refresh_token": "eyJhbGciOiAiSFMyNTYiLCAidHlwIjogIkpXVCJ9.eyJpc3MiOiAiTW9vbnJha2VyIiwgImlhdCI6IDE2MTg4Nzc0ODUuNzcyMjg5OCwgImV4cCI6IDE2MjY2NTM0ODUuNzcyMjg5OCwgInVzZXJuYW1lIjogInRlc3R1c2VyIiwgInRva2VuX3R5cGUiOiAicmVmcmVzaCJ9.Y5YxGuYSzwJN2WlunxlR7XNa2Y3GWK-2kt-MzHvLbP8"
|
|
}
|
|
```
|
|
|
|
```{.json .apirequest title="JSON-RPC Request"}
|
|
{
|
|
"jsonrpc": "2.0",
|
|
"method": "access.refresh_jwt",
|
|
"params": {
|
|
"refresh_token": "eyJhbGciOiAiSFMyNTYiLCAidHlwIjogIkpXVCJ9.eyJpc3MiOiAiTW9vbnJha2VyIiwgImlhdCI6IDE2MTg4Nzc0ODUuNzcyMjg5OCwgImV4cCI6IDE2MjY2NTM0ODUuNzcyMjg5OCwgInVzZXJuYW1lIjogInRlc3R1c2VyIiwgInRva2VuX3R5cGUiOiAicmVmcmVzaCJ9.Y5YxGuYSzwJN2WlunxlR7XNa2Y3GWK-2kt-MzHvLbP8"
|
|
},
|
|
"id": 1323
|
|
}
|
|
```
|
|
|
|
/// api-parameters
|
|
open: True
|
|
|
|
| Name | Type | Default | Description |
|
|
| --------------- | :----: | ------------ | ------------------------------------- |
|
|
| `refresh_token` | string | **REQUIRED** | A valid `refresh_token` for the user. |
|
|
|
|
///
|
|
|
|
|
|
/// collapse-code
|
|
```{.json .apiresponse title="Example Response"}
|
|
{
|
|
"username": "my_user",
|
|
"token": "eyJhbGciOiAiSFMyNTYiLCAidHlwIjogIkpXVCJ9.eyJpc3MiOiAiTW9vbnJha2VyIiwgImlhdCI6IDE2MTg4NzgyNDMuNTE2Nzc5MiwgImV4cCI6IDE2MTg4ODE4NDMuNTE2Nzc5MiwgInVzZXJuYW1lIjogInRlc3R1c2VyIiwgInRva2VuX3R5cGUiOiAiYXV0aCJ9.Ia_X_pf20RR4RAEXcxalZIOzOBOs2OwearWHfRnTSGU",
|
|
"source": "moonraker",
|
|
"action": "user_jwt_refresh"
|
|
}
|
|
```
|
|
///
|
|
|
|
/// api-response-spec
|
|
open: True
|
|
|
|
| Field | Type | Description |
|
|
| ---------- | :----: | -------------------------------------------------------------------- |
|
|
| `username` | string | The username of the entry whose access token ws refreshed. |
|
|
| `token` | string | A JSON Web Token (JWT) used to authenticate requests, also commonly |
|
|
| | | referred to as an `access token`. HTTP requests should include this |^
|
|
| | | token in the `Authorization` header as a `Bearer` type. This token |^
|
|
| | | expires after 1 hour. |^
|
|
| `source` | string | The [authentication source](#auth-source-desc) of the user entry. |
|
|
| `action` | string | The action taken by the Auth Manager. Will always be |
|
|
| | | "user_jwt_refresh". |^
|
|
|
|
///
|
|
|
|
/// note
|
|
This endpoint may be accessed by unauthorized clients. A 401 will
|
|
only be returned if the refresh token is invalid.
|
|
///
|
|
|
|
## Generate a Oneshot Token
|
|
|
|
Javascript is not capable of modifying the headers for some HTTP requests
|
|
(for example, the `websocket`), which is a requirement to apply JWT or API Key
|
|
authorization. To work around this clients may request a Oneshot Token and
|
|
pass it via the query string for these requests. Tokens expire in 5 seconds
|
|
and may only be used once, making them relatively safe for inclusion in the
|
|
query string.
|
|
|
|
```{.http .apirequest title="HTTP Request"}
|
|
GET /access/oneshot_token
|
|
```
|
|
|
|
```{.json .apirequest title="JSON-RPC Request"}
|
|
{
|
|
"jsonrpc": "2.0",
|
|
"method": "access.oneshot_token",
|
|
"id": 1323
|
|
}
|
|
```
|
|
|
|
```{.json .apiresponse title="Example Response"}
|
|
"APDBEGHUTBUD6SOAYBPF3KE5BRMO7YSL"
|
|
```
|
|
|
|
/// api-response-spec
|
|
open: True
|
|
|
|
The response is a string value containing the oneshot token. It may
|
|
added to a request's query string for access to any API endpoint. The query
|
|
string should be added in the form of:
|
|
|
|
```
|
|
?token={base32_random_token}
|
|
```
|
|
|
|
///
|
|
|
|
## Get authorization module info
|
|
|
|
```{.http .apirequest title="HTTP Request"}
|
|
GET /access/info
|
|
```
|
|
|
|
```{.json .apirequest title="JSON-RPC Request"}
|
|
{
|
|
"jsonrpc": "2.0",
|
|
"method": "access.info",
|
|
"id": 1323
|
|
}
|
|
```
|
|
|
|
/// collapse-code
|
|
```{.json .apiresponse title="Example Response"}
|
|
{
|
|
"default_source": "moonraker",
|
|
"available_sources": [
|
|
"moonraker",
|
|
"ldap"
|
|
],
|
|
"login_required": false,
|
|
"trusted": true
|
|
}
|
|
```
|
|
///
|
|
|
|
/// api-response-spec
|
|
open: True
|
|
|
|
| Field | Type | Description |
|
|
| ------------------- | :------: | ---------------------------------------------------- |
|
|
| `default_source` | string | The configured default |
|
|
| | | [authentication source](#auth-source-desc). |^
|
|
| `available_sources` | [string] | An array of available authentication sources. |
|
|
| `login_required` | bool | Set to `true` when `force_logins` is enabled via the |
|
|
| | | configuration at least one user has been created. |^
|
|
| `trusted` | bool | Set to `true` when the connection making the info |
|
|
| | | request is a trusted connection. |^
|
|
|
|
///
|
|
|
|
/// note
|
|
This endpoint may be accessed by unauthorized clients.
|
|
///
|
|
|
|
## Get the Current API Key
|
|
|
|
```{.http .apirequest title="HTTP Request"}
|
|
GET /access/api_key
|
|
```
|
|
|
|
```{.json .apirequest title="JSON-RPC Request"}
|
|
{
|
|
"jsonrpc": "2.0",
|
|
"method": "access.get_api_key",
|
|
"id": 1323
|
|
}
|
|
```
|
|
|
|
```{.json .apiresponse title="Example Response"}
|
|
e514851f37b94c779d955212b6906f95
|
|
```
|
|
|
|
/// api-response-spec
|
|
open: True
|
|
|
|
The response string value containing the current API key.
|
|
|
|
///
|
|
|
|
## Generate a New API Key
|
|
```{.http .apirequest title="HTTP Request"}
|
|
POST /access/api_key
|
|
```
|
|
|
|
```{.json .apirequest title="JSON-RPC Request"}
|
|
{
|
|
"jsonrpc": "2.0",
|
|
"method": "access.post_api_key",
|
|
"id": 1323
|
|
}
|
|
```
|
|
|
|
```{.json .apiresponse title="Example Response"}
|
|
e514851f37b94c779d955212b6906f95
|
|
```
|
|
|
|
/// api-response-spec
|
|
open: True
|
|
|
|
The response string value containing the new API key.
|
|
|
|
///
|
|
|
|
/// note
|
|
After this request executes the API key change is applied immediately.
|
|
All subsequent HTTP requests from untrusted clients must use the new key.
|
|
Changing the API Key will not affect open websockets authenticated using
|
|
the previous API Key.
|
|
///
|