accounts.md 4.57 KB
Newer Older
Nils Bandener's avatar
Nils Bandener committed
1
2
3
4
---
title: Accounts
html_title: Using Accounts for Signals Alerting
slug: elasticsearch-alerting-accounts
Jochen Kressin's avatar
Jochen Kressin committed
5
6
category: actions
order: 50
Nils Bandener's avatar
Nils Bandener committed
7
layout: docs
8
edition: beta
Nils Bandener's avatar
Nils Bandener committed
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
description: 
---

<!--- Copyright 2019 floragunn GmbH -->

# Accounts Registry
{: .no_toc}

{% include toc.md %}

## Basics

If you want to use e-mail or Slack actions, you have to configure accounts in the accounts registry beforehand. 

The purpose of the account registry is to:

Jochen Kressin's avatar
Jochen Kressin committed
25
* Make account data reusable thus avoiding configuring the same accounts again and again for each watch.
Nils Bandener's avatar
Nils Bandener committed
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
* Storing credentials for these accounts safely.
* Controlling which external resources can be used by watches.

While watches may be configured by a wide range of users, accounts shall be only defined by administrators. Normal users will then be able to use the predefined accounts.

## Account Types

### E-Mail Accounts

E-mail accounts represent connection data and credentials for SMTP servers. 

A typical e-mail account looks like this:

```json
{
	"host": "smtp.example.com",
	"port": 465,
	"user": "signals",
	"password": "secret",
	"enable_tls": true,
	"default_from": "signals@example.com",
	"default_bcc": "signals@example.com"
}
```

Jochen Kressin's avatar
Jochen Kressin committed
51
52
53
54
55
56
57
58
| Name | Description |
|---|---|
| host | The hostname of the SMTP server to connect to. Required. |
| port | The number of the port to connect to. Required. |
| user | The user name used for authentication. Optional. |
| 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. |
Nils Bandener's avatar
Nils Bandener committed
59
| 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.* |
Jochen Kressin's avatar
Jochen Kressin committed
60
61
62
63
64
65
| 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 |
| session_timeout | Sets the timeout for connecting to and communicating with the SMTP server. Optional; time duration in seconds. |
| proxy\_host, proxy\_port, proxy\_user, proxy\_password | Allows the specification of a SOCKS proxy to connect to the SMTP server. Optional. |
| debug | If true, protocol data is logged to the Elasticsearch log when mails are sent. |
Jochen Kressin's avatar
Jochen Kressin committed
66
{: .config-table}
Nils Bandener's avatar
Nils Bandener committed
67
68
69
70
71
72
73
74
75
76
77
78
79

### Slack Accounts

Slack accounts represent webhook URIs for sending messages to Slack Apps.

A Slack account looks rather simple:

```json
{
	"url": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX"
}
```

Nils Bandener's avatar
Nils Bandener committed
80
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.
Nils Bandener's avatar
Nils Bandener committed
81

Nils Bandener's avatar
Nils Bandener committed
82
83
84
85
86
87
88
89
90
91
92
93
94
95
### PagerDuty Accounts

PagerDuty accounts represent integration keys for PagerDuty services.

A PagerDuty account in Signals looks like this:

```json
{
	"integration_key": "XXXXXXXXXXXXXXXXXXXXXXXX"
}
```

The value for `integration_key` needs to be obtained from PagerDuty. 	See the [PagerDuty documentation](https://support.pagerduty.com/docs/services-and-integrations#section-create-a-generic-events-api-integration) for details. You have to create an integration for the Events API v2.

Nils Bandener's avatar
Nils Bandener committed
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
### Jira Accounts

Jira accounts represent auth tokens for Jira instances. Jira auth tokens are always accompanied by the login email address of the respective user.

A Jira account in Signals looks like this:

```json
{
    "url": "https://examplejira.atlassian.net/",
	"user_name": "example.user@example.com",
	"auth_token": "...."
}
```

The attribute `url` references the base URL of your Jira instance. The attribute `user_name` is the login email address of a user. `auth_token` is an API token obtained from Jira for the user. See the [Jira docs](https://confluence.atlassian.com/cloud/api-tokens-938839638.html) for details on obtaining auth tokens.

Nils Bandener's avatar
Nils Bandener committed
112
113
114
115
## REST API

Accounts may be managed using these REST API endpoints:

Jochen Kressin's avatar
Jochen Kressin committed
116
117
118
119
* [Get Account](rest_api_account_get.md)
* [Put Account](rest_api_account_put.md)
* [Delete Account](rest_api_account_delete.md)
* [Search Account](rest_api_account_search.md)
Nils Bandener's avatar
Nils Bandener committed
120
121