Commit 9b44bd39 authored by Nils Bandener's avatar Nils Bandener
Browse files

Updated accounts docs

parent 25ff5a93
...@@ -38,7 +38,6 @@ A typical e-mail account looks like this: ...@@ -38,7 +38,6 @@ A typical e-mail account looks like this:
```json ```json
{ {
"type": "email",
"host": "smtp.example.com", "host": "smtp.example.com",
"port": 465, "port": 465,
"user": "signals", "user": "signals",
...@@ -57,7 +56,7 @@ A typical e-mail account looks like this: ...@@ -57,7 +56,7 @@ A typical e-mail account looks like this:
| password | The password user for authentication. Optional. | | password | The password user for authentication. Optional. |
| enable\_tls | If true, the connection is established by TLS. | | enable\_tls | If true, the connection is established by TLS. |
| enable\_start\_tls | If true, the connection is established using STARTTLS. | | enable\_start\_tls | If true, the connection is established using STARTTLS. |
| trusted_hosts | Only accept server certificates issued to one of the provided hostnames, *and disables certificate issuer validation.* Optional; array of host names. *Security warning: Any certificate matching any of the provided host names will be accepted, regardless of the certificate issuer; attackers can abuse this behavior by serving a matching self-signed certificate during a man-in-the-middle attack.* | | trusted_hosts | Only accept server certificates issued to one of the provided host names, *and disables certificate issuer validation.* Optional; array of host names. *Security warning: Any certificate matching any of the provided host names will be accepted, regardless of the certificate issuer; attackers can abuse this behavior by serving a matching self-signed certificate during a man-in-the-middle attack.* |
| trust_all | If true, trust all hosts and don't validate any SSL keys. Optional. | | trust_all | If true, trust all hosts and don't validate any SSL keys. Optional. |
| default_from | Defines the from address used in e-mails when an e-mail action does not configure an explicit from address. Optional. | | default_from | Defines the from address used in e-mails when an e-mail action does not configure an explicit from address. Optional. |
| default\_to, default\_cc, default\_bcc | Defines the recipient addresses used in e-mails when an e-mail action does not configure an explicit values for the respective recipient types. Optional; array of e-mail addresses | | default\_to, default\_cc, default\_bcc | Defines the recipient addresses used in e-mails when an e-mail action does not configure an explicit values for the respective recipient types. Optional; array of e-mail addresses |
...@@ -73,12 +72,11 @@ A Slack account looks rather simple: ...@@ -73,12 +72,11 @@ A Slack account looks rather simple:
```json ```json
{ {
"type": "slack",
"url": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX" "url": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX"
} }
``` ```
The value for the `url` property must be optained by creating a Slack App inside Slack. See the [Slack docs](https://api.slack.com/incoming-webhooks) for details. The value for the `url` property must be obtained by creating a Slack App inside Slack. See the [Slack docs](https://api.slack.com/incoming-webhooks) for details.
## REST API ## REST API
......
--- ---
title: Delete Destination title: Delete Account
html_title: Delete a destination with the REST API html_title: Delete a account with the REST API
slug: elasticsearch-alerting-rest-api-destination-delete slug: elasticsearch-alerting-rest-api-account-delete
category: signals-rest category: signals-rest
order: 1000 order: 1000
layout: docs layout: docs
...@@ -20,16 +20,16 @@ description: ...@@ -20,16 +20,16 @@ description:
## Endpoint ## Endpoint
``` ```
DELETE /_signals/account/{account_id} DELETE /_signals/account/{account_type}/{account_id}
``` ```
Deletes the account identified by the `{account_id}` path parameter. Deletes the account of type `{account_type}` identified by the `{account_id}` path parameter.
**Important:** Right now, it is possible to delete accounts even if they are still used by watches. After deleting an account which is still used by a watch, the watch will fail to execute.
## Path Parameters ## Path Parameters
**{account_type}** The type of the account to be deleted. Required.
**{account_id}** The id of the account to be deleted. Required. **{account_id}** The id of the account to be deleted. Required.
## Responses ## Responses
...@@ -46,9 +46,13 @@ The user does not have the permission to delete accounts. ...@@ -46,9 +46,13 @@ The user does not have the permission to delete accounts.
An account with the given id does not exist. An account with the given id does not exist.
### 409 Conflict
The account is still used by a watch
## Permissions ## Permissions
For being able to access the endpoint, the user needs to have the privilege `cluster:admin:searchguard:signals:destination/delete` . For being able to access the endpoint, the user needs to have the privilege `cluster:admin:searchguard:signals:account/delete` .
This permission is included in the following [built-in action groups](security_permissions.md): This permission is included in the following [built-in action groups](security_permissions.md):
...@@ -57,7 +61,7 @@ This permission is included in the following [built-in action groups](security_p ...@@ -57,7 +61,7 @@ This permission is included in the following [built-in action groups](security_p
## Examples ## Examples
``` ```
DELETE /_signals/account/my_destination DELETE /_signals/account/slack/my_account
``` ```
......
--- ---
title: Get Destination title: Get Account
html_title: Get a destination with the REST API html_title: Get an account with the REST API
slug: elasticsearch-alerting-rest-api-destination-get slug: elasticsearch-alerting-rest-api-account-get
category: signals-rest category: signals-rest
order: 800 order: 800
layout: docs layout: docs
...@@ -20,14 +20,16 @@ description: ...@@ -20,14 +20,16 @@ description:
## Endpoint ## Endpoint
``` ```
GET /_signals/account/{account_id} GET /_signals/account/{account_type}/{account_id}
``` ```
Retrieves the account configuration identified by the `{account_id}` path parameter. Retrieves the account of type `{account_type}` identified by the `{account_id}` path parameter.
## Path Parameters ## Path Parameters
**{account_type}** The type of the account to be retrieved. Required.
**{account_id}** The id of the account to be retrieved. Required. **{account_id}** The id of the account to be retrieved. Required.
## Responses ## Responses
...@@ -48,7 +50,7 @@ An account with the given id does not exist. ...@@ -48,7 +50,7 @@ An account with the given id does not exist.
## Permissions ## Permissions
For being able to access the endpoint, the user needs to have the privilege `cluster:admin:searchguard:signals:destination/get`. For being able to access the endpoint, the user needs to have the privilege `cluster:admin:searchguard:signals:account/get`.
This permission is included in the following [built-in action groups](security_permissions.md): This permission is included in the following [built-in action groups](security_permissions.md):
......
--- ---
title: Put Destination title: Put Account
html_title: Put a destination with the REST API html_title: Put a account with the REST API
slug: elasticsearch-alerting-rest-api-destination-put slug: elasticsearch-alerting-rest-api-account-put
category: signals-rest category: signals-rest
order: 900 order: 900
layout: docs layout: docs
...@@ -21,20 +21,22 @@ description: ...@@ -21,20 +21,22 @@ description:
## Endpoint ## Endpoint
``` ```
PUT /_signals/account/{account_id} PUT /_signals/account/{account_type}/{account_id}
``` ```
Stores or updates an account identified by the `{account_id}` path parameter. Stores or updates an account of type `{account_type}`identified by the `{account_id}` path parameter.
## Path Parameters ## Path Parameters
**{account_id}** The id of the account to be created or updated. Required. **{account_type}** The type of the account to be stored. Required.
**{account_id}** The id of the account to be stored. Required.
## Request Body ## Request Body
The account needs to be specified as JSON document in the request body. The account needs to be specified as JSON document in the request body.
See TODO for details on the structure of accounts. See the chapter [accounts](accounts.md) for details on the structure of accounts.
## Responses ## Responses
...@@ -55,17 +57,17 @@ If the account specified in the request body was malformed, a JSON document cont ...@@ -55,17 +57,17 @@ If the account specified in the request body was malformed, a JSON document cont
### 403 Forbidden ### 403 Forbidden
The user does not have the permission to create destinations for the currently selected tenant. The user does not have the permission to create accounts.
### 415 Unsupported Media Type ### 415 Unsupported Media Type
The destination was not encoded as JSON document. Destinations need to be sent using the media type application/json. The account was not encoded as JSON document. Accounts need to be sent using the media type application/json.
## Permissions ## Permissions
For being able to access the endpoint, the user needs to have the privilege `cluster:admin:searchguard:signals:destination/put`. For being able to access the endpoint, the user needs to have the privilege `cluster:admin:searchguard:signals:account/put`.
This permission is included in the following [built-in action groups](security_permissions.md): This permission is included in the following [built-in action groups](security_permissions.md):
...@@ -76,11 +78,10 @@ This permission is included in the following [built-in action groups](security_p ...@@ -76,11 +78,10 @@ This permission is included in the following [built-in action groups](security_p
### E-Mail ### E-Mail
``` ```
PUT /_signals/account/default_email PUT /_signals/account/email/default
``` ```
```json ```json
{ {
"type": "email",
"host": "mail.mycompany.example", "host": "mail.mycompany.example",
"port": 587, "port": 587,
"enable_tls": true, "enable_tls": true,
...@@ -99,11 +100,10 @@ PUT /_signals/account/default_email ...@@ -99,11 +100,10 @@ PUT /_signals/account/default_email
### Slack ### Slack
``` ```
PUT /_signals/account/default_slack PUT /_signals/account/slack/default
``` ```
```json ```json
{ {
"type": "slack",
"url": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX" "url": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX"
} }
``` ```
...@@ -118,11 +118,10 @@ PUT /_signals/account/default_slack ...@@ -118,11 +118,10 @@ PUT /_signals/account/default_slack
### Invalid data ### Invalid data
``` ```
PUT /_signals/account/my_email PUT /_signals/account/email/test
``` ```
```json ```json
{ {
"type": "email",
"port": 587, "port": 587,
"enable_tls": true, "enable_tls": true,
"default_from": "signals@mycompany.example.com", "default_from": "signals@mycompany.example.com",
......
--- ---
title: Search Destination title: Search Accounts
html_title: Search a destination with the REST API html_title: Search the configured accounts with the REST API
slug: elasticsearch-alerting-rest-api-destination-search slug: elasticsearch-alerting-rest-api-account-search
category: signals-rest category: signals-rest
order: 850 order: 850
layout: docs layout: docs
...@@ -64,7 +64,7 @@ The user does not have the required to access the endpoint. ...@@ -64,7 +64,7 @@ The user does not have the required to access the endpoint.
## Permissions ## Permissions
For being able to access the endpoint, the user needs to have the privilege `cluster:admin:searchguard:signals:destination/search`. For being able to access the endpoint, the user needs to have the privilege `cluster:admin:searchguard:signals:account/search`.
This permission is included in the following [built-in action groups](security_permissions.md): This permission is included in the following [built-in action groups](security_permissions.md):
...@@ -103,22 +103,20 @@ GET /_signals/account/_search?size=1000 ...@@ -103,22 +103,20 @@ GET /_signals/account/_search?size=1000
"max_score": 1, "max_score": 1,
"hits": [ "hits": [
{ {
"_index": ".signals_destinations", "_index": ".signals_accounts",
"_type": "_doc", "_type": "_doc",
"_id": "default_slack", "_id": "default_slack",
"_score": 1, "_score": 1,
"_source": { "_source": {
"type": "slack",
"url": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX" "url": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX"
} }
}, },
{ {
"_index": ".signals_destinations", "_index": ".signals_accounts",
"_type": "_doc", "_type": "_doc",
"_id": "default_mail", "_id": "email/default",
"_score": 1, "_score": 1,
"_source": { "_source": {
"type": "email",
"host": "mail.mycompany.example", "host": "mail.mycompany.example",
"port": 587, "port": 587,
"enable_tls": true, "enable_tls": true,
...@@ -131,64 +129,4 @@ GET /_signals/account/_search?size=1000 ...@@ -131,64 +129,4 @@ GET /_signals/account/_search?size=1000
] ]
} }
} }
```
### Search for all E-Mail accounts
```
POST /_signals/account/_search?size=1000
```
```
{
"query": {
"match": {
"type": "email"
}
}
}
```
**Response**
```
200 OK
```
```json
{
"took": 3,
"timed_out": false,
"_shards": {
"total": 1,
"successful": 1,
"skipped": 0,
"failed": 0
},
"hits": {
"total": {
"value": 1,
"relation": "eq"
},
"max_score": 0.6931472,
"hits": [
{
"_index": ".signals_destinations",
"_type": "_doc",
"_id": "default_mail",
"_score": 0.6931472,
"_source": {
"type": "email",
"host": "mail.mycompany.example",
"port": 587,
"enable_tls": true,
"default_from": "signals@mycompany.example.com",
"default_bcc": [
"signals@mycompany.example.com"
]
}
}
]
}
}
```
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment