Store a credential for the collector
A credential is the read-only login the collector uses to reach a system: a SQL login, a Windows account, an SSH key or an Azure service principal. You store it once on an entity, and every resource of that entity and below can use it. This guide shows how to add one, which kind to choose, the connection options of each kind and how a resource finds the credential it uses.
Before you begin
- You need the Entity admin role on the entity that will own the credential.
- The login exists on the monitored system with read-only permissions. For SQL Server, see Prerequisites for availability groups; for every platform, see Permissions.
- Store the credential as high in the entity tree as it is valid. A SQL login used on every server of Ciguapa Inc. belongs on Ciguapa Inc., not on each environment.
Choose the kind
| Kind | User | Secret | Use it for |
|---|---|---|---|
SQL login (sql_login) | SQL login | Password | SQL Server instances and availability groups; their discovered databases and linked servers use the instance's. Also the Reporting Services execution log |
Windows account (windows) | Account (DOMAIN\user) | Password | Windows hosts over WinRM; report servers and web endpoints with Windows authentication (NTLM) |
HTTP user and password (http_basic) | User | Password | Web endpoints and report servers with Basic authentication; the Wazuh checks |
Bearer token (token) | — | Token | Web endpoints with bearer authentication |
SSH key (ssh_key) | User | Private key | Linux hosts |
SSH password (ssh_password) | User | Password | Linux hosts |
Azure service principal (azure_sp) | Client id | Client secret | Azure posture checks and Entra ID identity checks, for a tenant the server's managed identity cannot reach |
Windows-integrated authentication to SQL Server is not supported: the collector runs in a Linux container without a Kerberos ticket. Use a SQL login, which needs the instance to accept SQL Server authentication (mixed mode).
Add a credential
- Open Settings › Credentials and choose the entity in the entity picker, for example Ciguapa Inc..
- Select Add credential.
- Enter a Name you will recognise, such as
sql-monitoring, and choose the Kind. The kind cannot change later. - Check the Entity: resources of this entity and below can use the credential.
- Enter the user and the secret. The labels follow the kind, for example SQL login and Password, or Client id and Client secret.
- Under Connection options, set what the kind needs. See the next section.
- Select Create.
The credential appears in the list with the secret marked stored, how many resources use it and when it was last used.
Connection options
| Kind | Option | Values | Effect |
|---|---|---|---|
| SQL login | encrypt | yes (default), no, strict | Encrypts the connection. strict uses TDS 8 and needs SQL Server 2022 or later |
| SQL login | trust_server_certificate | true (default), false | Most instances use self-signed certificates. Set false once the instance has a certificate the collector trusts |
| SQL login | host_name_in_certificate | A host name | The name to validate when it differs from the host, for example through a listener or an alias |
| SQL login | application_intent | ReadOnly (default), ReadWrite | ReadWrite only changes routing, so per-database checks include the availability databases of a primary that refuses read-intent connections. The login still has no write permission |
| Windows account | auth | kerberos (default), negotiate, ntlm | How WinRM authenticates. The collector image has no Kerberos configuration, so choose negotiate or ntlm |
| SSH key, SSH password | known_hosts | OpenSSH known_hosts lines, one per line | Pins the host keys the collector accepts |
| Azure service principal | tenant_id | The Entra tenant ID | The tenant of the app registration |
Some options are set through the API only, in the credential's attributes:
| Kind | Option | Effect |
|---|---|---|
| Azure service principal | subscriptions | Limits Azure posture checks to these subscriptions. Without it, AZURE_SUBSCRIPTION_IDS applies, or else every subscription the identity can read |
| HTTP user and password | verify_tls | false accepts an untrusted certificate on the Wazuh indexer and manager. Default true |
Option names never hold secrets: the API refuses an option whose name contains pass, secret, token, private or pwd. Put secrets in the secret field.
How the secret is protected
- The secret is write-only. It is encrypted with the installation's data key (
EXCUBIUS_DATA_KEY) and never shown again, on any screen or through the API, which only says whether one is stored. - To change it, edit the credential and enter a new one. Leave the field empty to keep the stored secret, or select Remove the stored secret to clear it.
- The collector receives the secret over the internal network, keeps it in memory only and never logs it.
- Keep
EXCUBIUS_DATA_KEYwith the backup of the.envfile. Without it the stored secrets cannot be decrypted, and checks fail with the error kindconfiguntil you enter them again.
Which credential a resource uses
A resource looks for a credential in this order and takes the first one whose kind suits the check:
- The check's own credential, when one is set.
- The resource's credential.
- The credential of the nearest parent resource. An availability group or a database discovered under an instance uses the instance's SQL login.
For example, the execution log check of a report server is a T-SQL check. When the report server resource holds a Windows account for its portal, the check uses the SQL login of the instance above it, or a SQL login you set on that one check.
To set a credential on one check, use the API: PATCH /api/v1/resources/{id}/checks/{check_id} with credential_id. Pointing a resource or a check at a credential needs the Entity admin role on the entity that owns the credential.
Edit or delete a credential
- Edit changes the name, the user, the secret and the options. The kind stays.
- Delete works only when nothing uses the credential. Change the resources and checks that use it first.
- Deleting an entity also deletes the credentials it owns.
The list shows, for each credential, how many resources and checks use it and when a successful check last used it.
Related content
- How the collector works
- Add a resource, where Test connection proves the credential works
- Collector errors
- Permissions