diff --git a/docs/config.md b/docs/config.md index 587e8844..478dba9e 100644 --- a/docs/config.md +++ b/docs/config.md @@ -189,16 +189,19 @@ ntfy's auth is implemented with a simple [SQLite](https://www.sqlite.org/)-based (`user` and `admin`) and per-topic `read` and `write` permissions using an [access control list (ACL)](https://en.wikipedia.org/wiki/Access-control_list). Access control entries can be applied to users as well as the special everyone user (`*`), which represents anonymous API access. -To set up auth, simply **configure the following two options**: +To set up auth, **configure the following options**: * `auth-file` is the user/access database; it is created automatically if it doesn't already exist; suggested location `/var/lib/ntfy/user.db` (easiest if deb/rpm package is used) * `auth-default-access` defines the default/fallback access if no access control entry is found; it can be set to `read-write` (default), `read-only`, `write-only` or `deny-all`. -Once configured, you can use the `ntfy user` command and the `auth-users` config option to [add or modify users](#users-and-roles). -The `ntfy access` command and the `auth-access` option let you [modify the access control list](#access-control-list-acl) for specific users -and topic patterns. +Once configured, you can use + +- the `ntfy user` command and the `auth-users` config option to [add or modify users](#users-and-roles). +- the `ntfy access` command and the `auth-access` option let you [modify the access control list](#access-control-list-acl) for specific users +and topic patterns. +- the `ntfy token` command and the `auth-tokens` config option to [manage access tokens](#access-tokens) for users. Both of these commands **directly edit the auth database** (as defined in `auth-file`), so they only work on the server, and only if the user accessing them has the right permissions. @@ -244,6 +247,7 @@ Here's an example with two users: `phil` is an admin, `ben` is a regular user. === "Declarative users in /etc/ntfy/server.yml" ``` yaml + auth-file: "/var/lib/ntfy/user.db" auth-users: - "phil:$2a$10$YLiO8U21sX1uhZamTLJXHuxgVC0Z/GKISibrKCLohPgtG7yIxSk4C:admin" - "ben:$2a$10$NKbrNb7HPMjtQXWJ0f1pouw03LDLT/WzlO9VAv44x84bRCkh19h6m:user" @@ -252,6 +256,7 @@ Here's an example with two users: `phil` is an admin, `ben` is a regular user. === "Declarative users via env variables" ``` # Comma-separated list, use single quotes to avoid issues with the bcrypt hash + NTFY_AUTH_FILE='/var/lib/ntfy/user.db' NTFY_AUTH_USERS='phil:$2a$10$YLiO8U21sX1uhZamTLJXHuxgVC0Z/GKISibrKCLohPgtG7yIxSk4C:admin,ben:$2a$10$NKbrNb7HPMjtQXWJ0f1pouw03LDLT/WzlO9VAv44x84bRCkh19h6m:user' ``` @@ -270,6 +275,9 @@ note that you're putting your password in an untrusted website). The access control list (ACL) **manages access to topics for non-admin users, and for anonymous access (`everyone`/`*`)**. Each entry represents the access permissions for a user to a specific topic or topic pattern. +* [Using the CLI](#acl-entries-via-the-cli): Using the `ntfy access` command, you can manually edit the access control list. +* [In the config](#acl-entries-via-the-config): You can provision ACL entries in the `server.yml` file via `auth-access` key. + #### ACL entries via the CLI The ACL can be displayed or modified with the `ntfy access` command: @@ -331,13 +339,26 @@ As an alternative to manually creating ACL entries via the `ntfy access` CLI com entries declaratively in the `server.yml` file by adding them to the `auth-access` array, similar to the `auth-users` option (see [users via the config](#users-via-the-config). -The `auth-access` option is a list of access control entries that are automatically created when the server starts. -Each entry is defined in the format `::`. +The `auth-access` option is a list of access control entries that are automatically created/updated when the server starts. +When entries are removed, they are deleted from the database. Each entry is defined in the format `::`. + +The `` can be any existing, provisioned user as defined in the `auth-users` section (see [users via the config](#users-via-the-config)), +or `everyone`/`*` for anonymous access. The `` can be a specific topic name or a pattern with wildcards (`*`). The +`` can be one of the following: + +* `read-write` or `rw`: Allows both publishing to and subscribing to the topic +* `read-only`, `read`, or `ro`: Allows only subscribing to the topic +* `write-only`, `write`, or `wo`: Allows only publishing to the topic +* `deny-all`, `deny`, or `none`: Denies all access to the topic Here's an example with several ACL entries: === "Declarative ACL entries in /etc/ntfy/server.yml" ``` yaml + auth-file: "/var/lib/ntfy/user.db" + auth-users: + - "phil:$2a$10$YLiO8U21sX1uhZamTLJXHuxgVC0Z/GKISibrKCLohPgtG7yIxSk4C:user" + - "ben:$2a$10$NKbrNb7HPMjtQXWJ0f1pouw03LDLT/WzlO9VAv44x84bRCkh19h6m:user" auth-access: - "phil:mytopic:rw" - "ben:alerts-*:rw" @@ -348,16 +369,15 @@ Here's an example with several ACL entries: === "Declarative ACL entries via env variables" ``` # Comma-separated list + NTFY_AUTH_FILE='/var/lib/ntfy/user.db' + NTFY_AUTH_USERS='phil:$2a$10$YLiO8U21sX1uhZamTLJXHuxgVC0Z/GKISibrKCLohPgtG7yIxSk4C:user,ben:$2a$10$NKbrNb7HPMjtQXWJ0f1pouw03LDLT/WzlO9VAv44x84bRCkh19h6m:user' NTFY_AUTH_ACCESS='phil:mytopic:rw,ben:alerts-*:rw,ben:system-logs:ro,*:announcements:ro' ``` -The `` can be any existing user, or `everyone`/`*` for anonymous access. The `` can be a specific -topic name or a pattern with wildcards (`*`). The `` can be one of the following: - -* `read-write` or `rw`: Allows both publishing to and subscribing to the topic -* `read-only`, `read`, or `ro`: Allows only subscribing to the topic -* `write-only`, `write`, or `wo`: Allows only publishing to the topic -* `deny-all`, `deny`, or `none`: Denies all access to the topic +In this example, the `auth-users` section defines two users, `phil` and `ben`. The `auth-access` section defines +access control entries for these users. `phil` has read-write access to the topic `mytopic`, while `ben` has read-write +access to all topics starting with `alerts-` and read-only access to the topic `system-logs`. The last entry allows +anonymous users (i.e. clients that do not authenticate) to read the `announcements` topic. ### Access tokens In addition to username/password auth, ntfy also provides authentication via access tokens. Access tokens are useful @@ -369,6 +389,10 @@ want to use a dedicated token to publish from your backup host, and one from you and deleting the account, every action can be performed with a token. Granular access tokens are on the roadmap, but not yet implemented. +* [Using the CLI](#tokens-via-the-cli): Using the `ntfy token` command, you can manually add/update/remove tokens. +* [In the config](#tokens-via-the-config): You can provision access tokens in the `server.yml` file via `auth-tokens` key. + +#### Tokens via the CLI The `ntfy token` command can be used to manage access tokens for users. Tokens can have labels, and they can expire automatically (or never expire). Each user can have up to 60 tokens (hardcoded). @@ -386,26 +410,89 @@ ntfy token remove phil tk_th2sxr... # Delete token $ ntfy token add --expires=30d --label="backups" phil $ ntfy token list user phil -- tk_AgQdq7mVBoFD37zQVN29RhuMzNIz2 (backups), expires 15 Mar 23 14:33 EDT, accessed from 0.0.0.0 at 13 Feb 23 13:33 EST +- tk_7eevizlsiwf9yi4uxsrs83r4352o0 (backups), expires 15 Mar 23 14:33 EDT, accessed from 0.0.0.0 at 13 Feb 23 13:33 EST ``` Once an access token is created, you can **use it to authenticate against the ntfy server, e.g. when you publish or subscribe to topics**. To learn how, check out [authenticate via access tokens](publish.md#access-tokens). +#### Tokens via the config +Access tokens can be pre-provisioned in the `server.yml` configuration file using the `auth-tokens` config option. +This is useful for automated setups, Docker environments, or when you want to define tokens declaratively. + +The `auth-tokens` option is a list of access tokens that are automatically created/updated when the server starts. +When entries are removed, they are deleted from the database. Each entry is defined in the format `:[: