From 32f466d6c0b9b91fa7c8dc1b44f2c571a23afd46 Mon Sep 17 00:00:00 2001 From: noahtalerman <47070608+noahtalerman@users.noreply.github.com> Date: Fri, 20 Nov 2020 16:57:13 -0800 Subject: [PATCH] Add documentation for authentication API endpoints (#44) Endpoints that have been added: - /api/v1/kolide/login POST - /api/v1/kolide/logout POST - /api/v1/kolide/forgot_password POST - /api/v1/kolide/me GET - /api/v1/kolide/change_password POST - /api/v1/kolide/perform_required_password_reset POST - /api/v1/kolide/sso POST - /api/v1/kolide/sso GET --- docs/api/rest-endpoints.md | 487 ++++++++++++++++++++++++++++++++++++- 1 file changed, 475 insertions(+), 12 deletions(-) diff --git a/docs/api/rest-endpoints.md b/docs/api/rest-endpoints.md index 8e78292dc4..1cac0232d9 100644 --- a/docs/api/rest-endpoints.md +++ b/docs/api/rest-endpoints.md @@ -1,24 +1,64 @@ # Fleet REST API endpoints -## Hosts +## Authentication -### List hosts +Making authenticated requests to the Fleet server requires that you are granted permission to access data. The Fleet Authentication API enables you to receive an authorization token. + +All Fleet API requests are authenticated unless noted in the documentation. This means that almost all Fleet API requests will require sending the authentication token in the request header. + +The typical steps to making an authenticated API request are outlined below. + +First, utilize the `/login` endpoint to receive an authentication token. + +`POST /api/v1/kolide/login` + +Request body + +``` +{ + username: "janedoe@example.com" + passsword: "VArCjNW7CfsxGp67" +} +``` + +Default response + +`Status: 200` + +``` +{ + "user": { + "created_at": "2020-11-13T22:57:12Z", + "updated_at": "2020-11-13T22:57:12Z", + "id": 1, + "username": "jane", + "name": "", + "email": "janedoe@example.com", + "admin": true, + "enabled": true, + "force_password_reset": false, + "gravatar_url": "", + "sso_enabled": false + }, + "token": "{your token}" +} +``` + +Then, use the token returned from the `/login` endpoint to authenticate further API requests. The example below utilizes the `/hosts` endpoint. `GET /api/v1/kolide/hosts` -Parameters +Request header -| Name | Type | In | Description | -|-------------------------|---------|-------|------------------------------------------------------------------------------------------| -| page | integer | query | Page number of the results to fetch. | -| per_page | integer | query | Results per page. | -| order_key | string | query | What to order results by. Can be any column in the hosts table. | -| status | string | query | Indicates the status of the hosts to return. Can either be `new`, `online`, `offline`, or `mia`.| -| additional_info_filters | string | query | A comma-delimited list of fields to include in each host's additional information object. See [Fleet Configuration Options](https://github.com/fleetdm/fleet/blob/master/docs/cli/file-format.md#fleet-configuration-options) for an example configuration with hosts' additional information.| +``` +{ + "authentication": "Bearer {your token}" +} +``` -Example +Default response -`GET /api/v1/kolide/hosts?page=0&per_page=100&order_key=host_name` +`Status: 200` ``` { @@ -100,3 +140,426 @@ Example ] } ``` + +### Log in + +Authenticates the user with the specified credentials. Use the token returned from this endpoint to authenticate further API requests. + +`POST /api/v1/kolide/login` + +#### Parameters + +| Name | Type | In | Description | +|-------------------------|---------|-------|---------------------------------------------------| +| username | string | body | **Required**. The user's email. | +| password | string | body | **Required**. The user's plain text password.| + +#### Example + +`POST /api/v1/kolide/login` + +##### Request body + +``` +{ + username: "janedoe@example.com" + passsword: "VArCjNW7CfsxGp67" +} +``` + +##### Default response + +`Status: 200` + +``` +{ + "user": { + "created_at": "2020-11-13T22:57:12Z", + "updated_at": "2020-11-13T22:57:12Z", + "id": 1, + "username": "jane", + "name": "", + "email": "janedoe@example.com", + "admin": true, + "enabled": true, + "force_password_reset": false, + "gravatar_url": "", + "sso_enabled": false + }, + "token": "{your token}" +} +``` +******* + + +### Log out + +Logs out the authenticated user. + +`POST /api/v1/kolide/logout` + +#### Example + +`POST /api/v1/kolide/logout` + +##### Default response + +`Status: 200` +******* + + +### Forgot password + +Sends a password reset email to the specified email. Requires that SMTP is configured for your Fleet server. + +`POST /api/v1/kolide/forgot_password` + +#### Parameters + +| Name | Type | In | Description | +|-------------------------|---------|--------|---------------------------------------------------------------------------| +| email | string | body | **Required**. The email of the user requesting the reset password link. | + +#### Example + +`POST /api/v1/kolide/forgot_password` + +##### Request body + +``` +{ + "email": "janedoe@example.com" +} +``` + +##### Default response + +`Status: 200` + +##### Unknown error + +`Status: 500` + +``` +{ + "message": "Unknown Error", + "errors": [ + { + "name": "base", + "reason": "email not configured", + } + ] +} +``` +******* + + +### Change password + +`POST /api/v1/kolide/change_password` + +Changes the password for the authenticated user. + +#### Parameters + +| Name | Type | In | Description | +|-------------------------|---------|----------|-----------------------------------------------------------------------------| +| old_password | string | body | **Required**. The user's old password. | +| new_password | string | body | **Required**. The user's new password. | + +#### Example + +`POST /api/v1/kolide/change_password` + +##### Request body + +``` +{ + "old_password": "VArCjNW7CfsxGp67", + "new_password": "zGq7mCLA6z4PzArC", +} +``` + +##### Default response + +`Status: 200` + +##### Validation failed + +`Status: 422 Unprocessable entity` + +``` +{ + "message": "Validation Failed", + "errors": [ + { + "name": "old_password", + "reason": "old password does not match" + } + ] +} +``` +******* + + +### Me + +Retrieves the user data for the authenticated user. + +`POST /api/v1/kolide/me` + +#### Example + +`POST /api/v1/kolide/me` + +##### Default response + +`Status: 200` + +``` +{ + "user": { + "created_at": "2020-11-13T22:57:12Z", + "updated_at": "2020-11-16T23:49:41Z", + "id": 1, + "username": "jane", + "name": "", + "email": "janedoe@example.com", + "admin": true, + "enabled": true, + "force_password_reset": false, + "gravatar_url": "", + "sso_enabled": false + } +} +``` +******* + + +### Perform required password reset + +Resets the password of the authenticated user. Requires that `force_password_reset` is set to `true` prior to the request. + +`POST /api/v1/kolide/perform_require_password_reset` + +#### Example + +`POST /api/v1/kolide/perform_required_password_reset` + +##### Request body + +``` +{ + "new_password": "sdPz8CV5YhzH47nK" +} +``` + +##### Default response + +`Status: 200` + +``` +{ + "user": { + "created_at": "2020-11-13T22:57:12Z", + "updated_at": "2020-11-17T00:09:23Z", + "id": 1, + "username": "jane", + "name": "", + "email": "janedoe@example.com", + "admin": true, + "enabled": true, + "force_password_reset": false, + "gravatar_url": "", + "sso_enabled": false + } +} +``` +******* + + +### SSO config + +Gets the current SSO configuration. + +`GET /api/v1/kolide/sso` + +#### Example + +`GET /api/v1/kolide/sso` + +##### Default response + +`Status: 200` + +``` +{ + "settings": { + "idp_name": "IDP Vendor 1", + "idp_image_url": "", + "sso_enabled": false + } +} +``` +******* + + +### Initiate SSO + +`POST /api/v1/kolide/sso` + +#### Parameters + +| Name | Type | In | Description | +|-------------------------|---------|----------|-----------------------------------------------------------------------------| +| relay_url | string | body | **Required**. The relative url to be navigated to after succesful sign in. | + +#### Example + +`POST /api/v1/kolide/sso` + +##### Request body + +``` +{ + "relay_url": "/hosts/manage" +} +``` + +##### Default response + +`Status: 200` + +##### Unknown error + +`Status: 500` + +``` +{ + "message": "Unknown Error", + "errors": [ + { + "name": "base", + "reason": "InitiateSSO getting metadata: Get \"https://idp.example.org/idp-meta.xml\": dial tcp: lookup idp.example.org on [2001:558:feed::1]:53: no such host" + } + ] +} +``` +******* + + +## Hosts + +### List hosts + +`GET /api/v1/kolide/hosts` + +#### Parameters + +| Name | Type | In | Description | +|-------------------------|---------|-------|------------------------------------------------------------------------------------------| +| page | integer | query | Page number of the results to fetch. | +| per_page | integer | query | Results per page. | +| order_key | string | query | What to order results by. Can be any column in the hosts table. | +| status | string | query | Indicates the status of the hosts to return. Can either be `new`, `online`, `offline`, or `mia`.| +| additional_info_filters | string | query | A comma-delimited list of fields to include in each host's additional information object. See [Fleet Configuration Options](https://github.com/fleetdm/fleet/blob/master/docs/cli/file-format.md#fleet-configuration-options) for an example configuration with hosts' additional information.| + +#### Example + +`GET /api/v1/kolide/hosts?page=0&per_page=100&order_key=host_name` + +##### Request query parameters + +``` +{ + "page": 0, + "per_page": 100, + "order_key": "host_name", +} +``` + +##### Default response + +`Status: 200` + +``` +{ + "hosts": [ + { + "created_at": "2020-11-05T05:09:44Z", + "updated_at": "2020-11-05T06:03:39Z", + "id": 1, + "detail_updated_at": "2020-11-05T05:09:45Z", + "label_updated_at": "2020-11-05T05:14:51Z", + "seen_time": "2020-11-05T06:03:39Z", + "hostname": "2ceca32fe484", + "uuid": "392547dc-0000-0000-a87a-d701ff75bc65", + "platform": "centos", + "osquery_version": "2.7.0", + "os_version": "CentOS Linux 7", + "build": "", + "platform_like": "rhel fedora", + "code_name": "", + "uptime": 8305000000000, + "memory": 2084032512, + "cpu_type": "6", + "cpu_subtype": "142", + "cpu_brand": "Intel(R) Core(TM) i5-8279U CPU @ 2.40GHz", + "cpu_physical_cores": 4, + "cpu_logical_cores": 4, + "hardware_vendor": "", + "hardware_model": "", + "hardware_version": "", + "hardware_serial": "", + "computer_name": "2ceca32fe484", + "primary_ip": "", + "primary_mac": "", + "distributed_interval": 10, + "config_tls_refresh": 10, + "logger_tls_period": 8, + "additional": {}, + "enroll_secret_name": "default", + "status": "offline", + "display_text": "2ceca32fe484" + }, + { + "created_at": "2020-11-05T05:09:44Z", + "updated_at": "2020-11-05T06:03:39Z", + "id": 2, + "detail_updated_at": "2020-11-05T05:09:45Z", + "label_updated_at": "2020-11-05T05:14:52Z", + "seen_time": "2020-11-05T06:03:40Z", + "hostname": "4cc885c20110", + "uuid": "392547dc-0000-0000-a87a-d701ff75bc65", + "platform": "centos", + "osquery_version": "2.7.0", + "os_version": "CentOS 6.8.0", + "build": "", + "platform_like": "rhel", + "code_name": "", + "uptime": 8305000000000, + "memory": 2084032512, + "cpu_type": "6", + "cpu_subtype": "142", + "cpu_brand": "Intel(R) Core(TM) i5-8279U CPU @ 2.40GHz", + "cpu_physical_cores": 4, + "cpu_logical_cores": 4, + "hardware_vendor": "", + "hardware_model": "", + "hardware_version": "", + "hardware_serial": "", + "computer_name": "4cc885c20110", + "primary_ip": "", + "primary_mac": "", + "distributed_interval": 10, + "config_tls_refresh": 10, + "logger_tls_period": 8, + "additional": {}, + "enroll_secret_name": "default", + "status": "offline", + "display_text": "4cc885c20110" + }, + ] +} +``` +*******