A credential is whatever a sensor needs to be let in: an SNMP community, a database login, an API token. It is held on an object in the tree, sealed, and reaches every sensor beneath that object that can use it. Credentials are kept apart from sensors on purpose, so a sensor, and any template made from it, never carries a secret.
Where they are held
Select a site, group, device or sensor under Setup, Configuration, and use its Credentials panel. The panel lists the credentials held on that object, by type, name and when each was updated. Values are never shown.
A sensor's own Credentials panel also says where its credential comes from:
- This sensor resolves SNMP / default from Comms Room, 2 levels up. All is well, and it tells you which object to change.
- Nothing resolves for this SNMP sensor, so it will fail to authenticate. Add one on the sensor, or higher up where other sensors can share it. On an HTTP(S) or MongoDB sensor that needs no login, this can be ignored.
Credential types
A credential's type is the sensor type that uses it.
| Type | Fields | Notes |
|---|---|---|
| SNMP | Version, Port, Community | Version and port on the credential take precedence over the sensor's own. SNMP v1 and v2c are supported; v3 fields can be entered but v3 is not yet supported by the probe. |
| HTTP(S) | Username, Password, Bearer token, API key | All optional. Nothing is sent unless the request asks for it with a token, see below. |
| MySQL / MariaDB query | Username, Password | Both required. |
| FTP file fetch | Username, Password | Both required. |
| MongoDB command | Username, Password | Optional. Without them the sensor does not log in. |
| Substitution | Value | A named value for use in requests, see below. |
Ping, TCP port, SMTP and IMAP4 banners, DNS, SIP, RDP and email delivery take no credential.
A sensor that needs a credential and has none is not sent to a probe at all. An SNMP sensor with no community, or a MySQL or FTP sensor with no username, reads STALE rather than failing. If a new sensor of one of those types never reports, check its credentials line first.
How a sensor finds its credential
Starting at the sensor and walking up through its device, groups and site, the first object holding a credential of the sensor's type wins. Each type is found separately, so a device holding its own HTTP(S) login does not stop its SNMP sensors using the community held on the site.
Within a type, the whole credential is taken from that one object; fields are not mixed from different levels. A device holding an HTTP(S) credential with only a bearer token hides a site's HTTP(S) credential with a username and password completely, so give the nearer one every field its sensors need.
That gives a simple pattern:
- Hold the credential most of the estate shares on the site, or on a group.
- Where one device differs, hold a credential of the same type on that device. It overrides the shared one for that device's sensors only.
- Where one sensor differs, hold it on the sensor.
Deleting a credential lets everything that was using it fall back to whatever is held above, or to nothing. Changes reach the probes the next time each collects its configuration, not in the middle of a poll.
Adding and changing
Choose the Type, give a Name and fill in the fields, then press
Save credential. The type and name together identify it on that object: saving the same type and
name again replaces it, and a different name adds a second one. Sensors use a single credential of each type, the
oldest held on the nearest object, so keep one credential per type on an object and leave its name as
default, except for Substitution values, where the name matters.
- A secret field left empty keeps the secret already held, so a port can be corrected without retyping the community. A secret cannot be emptied by saving; delete the credential and add it again.
- Other fields are not kept when left empty. When replacing a credential, fill in every field that is not a secret, such as the SNMP version and port or an HTTP(S) username, even if it has not changed.
- Names may use letters, digits, underscore, hyphen and full stop. Values should be plain ASCII; accented letters and symbols such as the pound sign are removed.
Using credentials in a request
HTTP(S) credentials, and substitution values, are written into a request with {{name}} tokens. They
work in the URL path, headers, body and target override of a web request, and in the equivalent fields of other
sensor types: an SNMP object, a query, a DNS name, a file path, a conversation step.
| Token | Becomes |
|---|---|
{{basicauth}} | Username and password, encoded for basic authentication, as in
Authorization: Basic {{basicauth}} |
{{basicuser}}, {{basicpassword}} | Username and password separately |
{{bearer}} | The bearer token, as in Authorization: Bearer {{bearer}} |
{{apikey}} | The API key, in whatever header the API expects |
{{host}} | The sensor's target address |
{{isodate}}, {{ukdate}}, {{yesterday}}, {{unixtime}} and
similar | The date and time in UK time, useful for a dated log file or a query about today |
{{yourname}} | A Substitution credential named yourname |
A token that is not recognised is sent exactly as written. An HTTP(S) token with no credential behind it becomes empty, which usually shows as an authentication failure.
Substitution values
A Substitution credential holds one value under a name of your choosing: letters, digits and underscore, up to 40 characters, and not one of the built-in names above. Unlike other credentials, every Substitution value above a sensor is available to it, with a nearer value replacing one of the same name. Use them for anything that differs between parts of the estate but not between sensors: a customer code in an API path, a mailbox name, a site identifier.
Security
- Sealed at rest. Every credential is encrypted with authenticated encryption before it is stored, and is never shown again, to anyone.
- Never in a template. Saving a template leaves credentials behind, so templates can be shared without leaking anything, provided no secret has been typed into a request by hand.
- Only where needed. A credential is unsealed only when a probe assigned to a sensor that uses it collects its configuration, over the probe's signed, verified HTTPS connection, and is held by the probe in memory only.
- Isolated. A sensor only ever resolves credentials from its own ancestors in its own estate.
- Audited. Every change and deletion is recorded with who made it, never with the value.
Connections, for notifications
The credentials a notification channel uses to reach the outside world, the SMTP relay email is sent through or the bot account that posts to Matrix, are held separately, under Setup, Actions, on the Connections tab. They are sealed in the same way. See Actions.