Skip to content
GitLab
Commit 9b44bd39 authored by Nils Bandener's avatar Nils Bandener
Browse files

Updated accounts docs

parent 25ff5a93
Hide whitespace changes
Inline Side-by-side
_content/_docs_signals/accounts.md
View file @ 9b44bd39
......@@ -38,7 +38,6 @@ A typical e-mail account looks like this:
```json
{
"type": "email",
"host": "smtp.example.com",
"port": 465,
"user": "signals",
......@@ -57,7 +56,7 @@ A typical e-mail account looks like this:
| password | The password user for authentication. Optional. |
| enable\_tls | If true, the connection is established by TLS. |
| 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. |
| 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 |
......@@ -73,12 +72,11 @@ A Slack account looks rather simple:
```json
{
"type": "slack",
"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
......
_content/_docs_signals/rest_api_account_delete.md
View file @ 9b44bd39
---
title: Delete Destination
html_title: Delete a destination with the REST API
slug: elasticsearch-alerting-rest-api-destination-delete
title: Delete Account
html_title: Delete a account with the REST API
slug: elasticsearch-alerting-rest-api-account-delete
category: signals-rest
order: 1000
layout: docs
......@@ -20,16 +20,16 @@ description:
## Endpoint
```
DELETE /_signals/account/{account_id}
DELETE /_signals/account/{account_type}/{account_id}
```
Deletes the account 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.
Deletes the account of type `{account_type}` identified by the `{account_id}` path parameter.
## Path Parameters
**{account_type}** The type of the account to be deleted. Required.
**{account_id}** The id of the account to be deleted. Required.
## Responses
......@@ -46,9 +46,13 @@ The user does not have the permission to delete accounts.
An account with the given id does not exist.
### 409 Conflict
The account is still used by a watch
## 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):
......@@ -57,7 +61,7 @@ This permission is included in the following [built-in action groups](security_p
## Examples
```
DELETE /_signals/account/my_destination
DELETE /_signals/account/slack/my_account
```
......
_content/_docs_signals/rest_api_account_get.md
View file @ 9b44bd39
---
title: Get Destination
html_title: Get a destination with the REST API
slug: elasticsearch-alerting-rest-api-destination-get
title: Get Account
html_title: Get an account with the REST API
slug: elasticsearch-alerting-rest-api-account-get
category: signals-rest
order: 800
layout: docs
......@@ -20,14 +20,16 @@ description:
## 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
**{account_type}** The type of the account to be retrieved. Required.
**{account_id}** The id of the account to be retrieved. Required.
## Responses
......@@ -48,7 +50,7 @@ An account with the given id does not exist.
## 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):
......
_content/_docs_signals/rest_api_account_put.md
View file @ 9b44bd39
---
title: Put Destination
html_title: Put a destination with the REST API
slug: elasticsearch-alerting-rest-api-destination-put
title: Put Account
html_title: Put a account with the REST API
slug: elasticsearch-alerting-rest-api-account-put
category: signals-rest
order: 900
layout: docs
......@@ -21,20 +21,22 @@ description:
## 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
**{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
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
......@@ -55,17 +57,17 @@ If the account specified in the request body was malformed, a JSON document cont
### 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
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
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):
......@@ -76,11 +78,10 @@ This permission is included in the following [built-in action groups](security_p
### E-Mail
```
PUT /_signals/account/default_email
PUT /_signals/account/email/default
```
```json
{
"type": "email",
"host": "mail.mycompany.example",
"port": 587,
"enable_tls": true,
......@@ -99,11 +100,10 @@ PUT /_signals/account/default_email
### Slack
```
PUT /_signals/account/default_slack
PUT /_signals/account/slack/default
```
```json
{
"type": "slack",
"url": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX"
}
```
......@@ -118,11 +118,10 @@ PUT /_signals/account/default_slack
### Invalid data
```
PUT /_signals/account/my_email
PUT /_signals/account/email/test
```
```json
{
"type": "email",
"port": 587,
"enable_tls": true,
"default_from": "signals@mycompany.example.com",
......
_content/_docs_signals/rest_api_account_search.md
View file @ 9b44bd39
---
title: Search Destination
html_title: Search a destination with the REST API
slug: elasticsearch-alerting-rest-api-destination-search
title: Search Accounts
html_title: Search the configured accounts with the REST API
slug: elasticsearch-alerting-rest-api-account-search
category: signals-rest
order: 850
layout: docs
......@@ -64,7 +64,7 @@ The user does not have the required to access the endpoint.
## 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):
......@@ -103,22 +103,20 @@ GET /_signals/account/_search?size=1000
"max_score": 1,
"hits": [
{
"_index": ".signals_destinations",
"_index": ".signals_accounts",
"_type": "_doc",
"_id": "default_slack",
"_score": 1,
"_source": {
"type": "slack",
"url": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX"
}
},
{
"_index": ".signals_destinations",
"_index": ".signals_accounts",
"_type": "_doc",
"_id": "default_mail",
"_id": "email/default",
"_score": 1,
"_source": {
"type": "email",
"host": "mail.mycompany.example",
"port": 587,
"enable_tls": true,
......@@ -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

floragunn GmbH - Tempelhofer Ufer 16 - 10963 Berlin - Germany- Managing Directors: Claudia Kressin, Jochen Kressin - Amtsgericht Charlottenburg HRB 147010 - VAT-ID: DE287373363