diff --git a/source/api/alert.rst b/source/api/alert.rst index fa925a4..ce40ce1 100644 --- a/source/api/alert.rst +++ b/source/api/alert.rst @@ -62,7 +62,7 @@ The following alert attributes are populated at source: default) then alerts must have an ``environment`` attribute that is one of either ``Production`` or ``Development`` and it must define a ``service`` attribute. For more information on configuring - or disabling this plugin see :ref:`plugin config`. + or disabling this plugin see :ref:`plugin settings`. Attributes added when processing alerts --------------------------------------- diff --git a/source/api/reference.rst b/source/api/reference.rst index 409bc16..d53edab 100644 --- a/source/api/reference.rst +++ b/source/api/reference.rst @@ -42,11 +42,11 @@ Input +-----------------+----------+----------------------------------------------+ | ``environment`` | string | environment, used to namespace the resource | +-----------------+----------+----------------------------------------------+ -| ``severity`` | string | see :ref:`severity_table` table | +| ``severity`` | string | see :ref:`severity table` table | +-----------------+----------+----------------------------------------------+ | ``correlate`` | list | list of related event names | +-----------------+----------+----------------------------------------------+ -| ``status`` | string | see :ref:`status_table` table | +| ``status`` | string | see :ref:`status table` table | +-----------------+----------+----------------------------------------------+ | ``service`` | list | list of effected services | +-----------------+----------+----------------------------------------------+ diff --git a/source/authentication.rst b/source/authentication.rst index 7931cbe..3552de3 100644 --- a/source/authentication.rst +++ b/source/authentication.rst @@ -4,8 +4,7 @@ Authentication ============== By default, authentication is not enabled, however there are some features -that are :ref:`not available ` unless users login such as -watching alerts. +that are not available unless users login such as watching alerts. Alerta supports six main authentication strategies: @@ -200,7 +199,7 @@ Refer to pysaml2 documentation and source code if you need additional options: - https://pysaml2.readthedocs.io/en/latest/howto/config.html - https://github.com/rohe/pysaml2/blob/master/src/saml2/config.py -Note: entityid and service provider endpoints are configured by default based on your BASE_URL value which is mandatory if you use SAML (see :ref:`general config`) +Note: entityid and service provider endpoints are configured by default based on your BASE_URL value which is mandatory if you use SAML (see :ref:`general settings`) ``ALLOWED_SAML2_GROUPS`` @@ -625,7 +624,7 @@ the command-line tool. Keys can be easily generated from the Alerta web UI and can have any scopes associated with them. They are valid for 1 year by default but this period is configurable using ``API_KEY_EXPIRE_DAYS`` in the -:ref:`server configuration `. +:ref:`server configuration `. To use an API key in an API query you must put the key in either an HTTP header or a query parameter. diff --git a/source/conf.py b/source/conf.py index dcfe03a..b2d94a4 100644 --- a/source/conf.py +++ b/source/conf.py @@ -43,7 +43,7 @@ myst_heading_anchors = 3 templates_path = ['_templates'] -exclude_patterns = ['Thumbs.db', '.DS_Store'] +exclude_patterns = ['Thumbs.db', '.DS_Store', 'auth/*', 'examples/*', 'thrift/*', 'spelling_wordlist.txt'] # -- Options for HTML output ------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output diff --git a/source/configuration.rst b/source/configuration.rst index 8446fe2..ded86f6 100644 --- a/source/configuration.rst +++ b/source/configuration.rst @@ -293,6 +293,7 @@ Auth Provider Settings valid authentication providers are ``basic``, ``ldap``, ``github``, ``openid``, ``saml2``, ``azure``, ``cognito``, ``gitlab``, ``google``, ``keycloak``, and ``cas`` (default is ``basic``) + .. note:: Any authentication provider that is `OpenID Connect compliant`_ is supported. Set the ``AUTH_PROVIDER`` to ``openid`` and configure the required ``OIDC`` settings @@ -432,13 +433,13 @@ SAML 2.0 Auth Settings (no default) ``SAML2_USER_NAME_FORMAT`` Python format string which will be rendered to user's name using SAML - attributes. See :ref:`saml2` (default is ``'{givenName} {surname}'``) + attributes. See :ref:`saml2_auth` (default is ``'{givenName} {surname}'``) ``SAML2_EMAIL_ATTRIBUTE`` (default is ``'emailAddress'``) ``SAML2_CONFIG`` - ``pysaml2`` configuration ``dict``. See :ref:`saml2` (no default) + ``pysaml2`` configuration ``dict``. See :ref:`saml2_auth` (no default) ``ALLOWED_SAML2_GROUPS`` - list of authorised groups a user must belong to. See :ref:`saml2` for + list of authorised groups a user must belong to. See :ref:`saml2_auth` for details (default is ``*``) ``ALLOWED_EMAIL_DOMAINS`` authorised email domains when using email as login (default is ``*``) @@ -892,6 +893,9 @@ The following settings are specific to the web UI and are not used by the server to sort by newest use ``lastReceiveTime`` or oldest use ``-createTime``. minus means reverse (default is ``lastReceiveTime``) ``DEFAULT_FILTER`` default alert list filter as query filter (default is ``{'status':['open','ack']}``) +``CLIPBOARD_TEMPLATE`` + Jinja2-style template for the copy-to-clipboard button on alerts. Alert attributes + are available as template variables eg. ``{{ resource }}: {{ event }}`` (default is empty string) ``DEFAULT_FONT`` default ``font-family``, ``font-size`` and ``font-weight`` (default is ``Sintony``, ``13px``, ``500``) ``ACTIONS`` @@ -1071,20 +1075,20 @@ General Settings ~~~~~~~~~~~~~~~~ :envvar:`DEBUG` - :ref:`see above ` + :ref:`see above ` :envvar:`BASE_URL` - :ref:`see above ` + :ref:`see above ` :envvar:`USE_PROXYFIX` - :ref:`see above ` + :ref:`see above ` :envvar:`SECRET_KEY` - :ref:`see above ` + :ref:`see above ` Database Settings ~~~~~~~~~~~~~~~~~ :envvar:`DATABASE_URL` - used by both :ref:`Postgres ` and - :ref:`MongoDB ` for database connection strings + used by both Postgres and MongoDB for database connection strings. + See :ref:`database settings` :envvar:`DATABASE_NAME` database name can be used to override default database defined in ``DATABASE_URL`` @@ -1113,53 +1117,53 @@ Authentication Settings ~~~~~~~~~~~~~~~~~~~~~~~ :envvar:`AUTH_REQUIRED` - :ref:`see above ` + :ref:`see above ` :envvar:`AUTH_PROVIDER` - :ref:`see above ` + :ref:`see above ` :envvar:`ADMIN_USERS` - :ref:`see above ` + :ref:`see above ` :envvar:`SIGNUP_ENABLED` - :ref:`see above ` + :ref:`see above ` :envvar:`CUSTOMER_VIEWS` - :ref:`see above ` + :ref:`see above ` :envvar:`OAUTH2_CLIENT_ID` - :ref:`see above ` + :ref:`see above ` :envvar:`OAUTH2_CLIENT_SECRET` - :ref:`see above ` + :ref:`see above ` :envvar:`ALLOWED_EMAIL_DOMAINS` - :ref:`see above ` + :ref:`see above ` :envvar:`AZURE_TENANT` - :ref:`see above ` + :ref:`see above ` :envvar:`GITHUB_URL` - :ref:`see above ` + :ref:`see above ` :envvar:`ALLOWED_GITHUB_ORGS` - :ref:`see above ` + :ref:`see above ` :envvar:`GITLAB_URL` - :ref:`see above ` + :ref:`see above ` :envvar:`ALLOWED_GITLAB_GROUPS` - :ref:`see above ` + :ref:`see above ` :envvar:`KEYCLOAK_URL` - :ref:`see above ` + :ref:`see above ` :envvar:`KEYCLOAK_REALM` - :ref:`see above ` + :ref:`see above ` :envvar:`ALLOWED_KEYCLOAK_ROLES` - :ref:`see above ` + :ref:`see above ` :envvar:`LDAP_BIND_PASSWORD` - :ref:`see above ` + :ref:`see above ` :envvar:`OIDC_ISSUER_URL` - :ref:`see above ` + :ref:`see above ` :envvar:`ALLOWED_OIDC_ROLES` - :ref:`see above ` + :ref:`see above ` Sundry Settings ~~~~~~~~~~~~~~~ :envvar:`CORS_ORIGINS` - :ref:`see above ` + :ref:`see above ` :envvar:`MAIL_FROM` - :ref:`see above ` + :ref:`see above ` :envvar:`SMTP_PASSWORD` - :ref:`see above ` + :ref:`see above ` :envvar:`GOOGLE_TRACKING_ID` :ref:`see above ` @@ -1167,27 +1171,27 @@ Housekeeping Settings ~~~~~~~~~~~~~~~~~~~~~ :envvar:`DELETE_EXPIRED_AFTER` - :ref:`see above ` + :ref:`see above ` :envvar:`DELETE_INFO_AFTER` - :ref:`see above ` + :ref:`see above ` Plugin & Webhook Settings ~~~~~~~~~~~~~~~~~~~~~~~~~ :envvar:`PLUGINS` - :ref:`see above ` + :ref:`see above ` :envvar:`BLACKOUT_DURATION` - :ref:`see above ` + :ref:`see above ` :envvar:`NOTIFICATION_BLACKOUT` - :ref:`see above ` + :ref:`see above ` :envvar:`BLACKOUT_ACCEPT` - :ref:`see above ` + :ref:`see above ` :envvar:`ORIGIN_BLACKLIST` - :ref:`see above ` + :ref:`see above ` :envvar:`ALLOWED_ENVIRONMENTS` - :ref:`see above ` + :ref:`see above ` :envvar:`DEFAULT_ENVIRONMENT` - :ref:`see above ` + :ref:`see above ` Dynamic Settings ---------------- diff --git a/source/conventions.md b/source/conventions.md index 1cc3d6f..111caf9 100644 --- a/source/conventions.md +++ b/source/conventions.md @@ -74,7 +74,7 @@ could then become:: ### Severity Levels -Agree on a subset of [severity levels](api/alert.rst#alert-severities) and +Agree on a subset of {ref}`severity levels ` and be consistent with what they mean. For example, if severity levels are used consistently then integrating with a paging or email system becomes easier. diff --git a/source/customer-views.rst b/source/customer-views.rst index 607df85..008335d 100644 --- a/source/customer-views.rst +++ b/source/customer-views.rst @@ -3,51 +3,255 @@ Customer Views ============== -Multitenancy is acheived using Customer views that are a way of ensuring logged in users only see alerts that relate to their organisation. +Customer views provide **multi-tenancy** for Alerta deployments that serve +multiple customers or teams from a single instance. When enabled, alerts are +automatically partitioned by customer so that each logged-in user only sees +alerts belonging to their organisation. -This is for Alerta deployments that are used to manage multiple customer sites. +A top-level ``customer`` attribute on alerts and heartbeats is used to +partition data. The value is determined by a **customer lookup table** that +maps user logins, email domains, groups, or organisation names to customer +strings. -Roles ------ -The role of an API key is assumed to be "user" if it is a customer generated key. The role of admin +.. contents:: Contents + :local: + :depth: 2 -You can have a customer/user API key and an admin API key, but not a customer/admin API key -- this makes no sense. +Overview +-------- -How it works ------------- +Without customer views every authenticated user sees all alerts. Customer +views add an implicit filter so that: -A new top-level alert attribute called ``customer`` is used to partition alerts for particular customers within the same alert database. +* **Customer users** only see alerts tagged with their customer name. +* **Admin users** (those listed in ``ADMIN_USERS``) see all alerts across + every customer. -When a user logs in to the Alert console, a customer lookup is done to determine what customer value should be assigned to that user. +The customer value is also embedded in API keys generated by a customer +user, so integrations that send alerts on behalf of that customer are +automatically scoped. -The customer value is then used as an implicit additional filter for all alert and heartbeat queries. -It is also assigned to any API keys generated by that user and the ``customer`` field is automatically used whenever that API key is used to generate or query for alerts. +Enabling Customer Views +----------------------- -Configuration -------------- - -To configure customer views follow these three easy steps: - -1. Authentication must be enforced and customer views enabled so in ``alertad.conf``:: +Customer views require authentication to be enabled. Add the following to +``alertad.conf``:: AUTH_REQUIRED = True CUSTOMER_VIEWS = True -2. Define administrators that will have a global view of all customers and will have no restrictions on generating API keys or blackout periods, so in ``alertad.conf``:: +Then define at least one admin user who will have unrestricted access:: + + ADMIN_USERS = ['admin@example.com'] + +.. important:: + + Every non-admin user **must** have a matching entry in the customer + lookup table. If ``CUSTOMER_VIEWS`` is ``True`` and no match is found + for a user at login time, the server returns a ``403 Forbidden`` error + with the message *"No customer lookup configured for user ..."*. + + +How Customer Matching Works +--------------------------- + +When a user authenticates, Alerta calls the customer lookup function with +two inputs: + +1. The user's **login** (typically their email address). +2. A list of **groups** the user belongs to (OAuth organisations, LDAP + groups, OIDC/SAML groups, etc.). + +The lookup iterates over ``[login] + groups`` and checks each value against +the ``match`` field in the customer lookup table. Every matching row's +``customer`` value is collected and returned. + +For example, given the following lookup table: + ++--------------------------+----------------+ +| Match | Customer | ++==========================+================+ +| ``example.com`` | Example Corp | ++--------------------------+----------------+ +| ``ops-team`` | Example Corp | ++--------------------------+----------------+ +| ``bob@partner.io`` | Partner Inc | ++--------------------------+----------------+ + +* A user logging in as ``alice@example.com`` who belongs to group + ``ops-team`` will match on **both** ``example.com`` and ``ops-team``, + resulting in customer ``Example Corp``. +* A user logging in as ``bob@partner.io`` will match on their exact login, + resulting in customer ``Partner Inc``. + +.. note:: + + The ``match`` value is compared as an **exact string** against the + user's login and each of their groups. It is not a regex or glob + pattern. For email-domain matching, the auth provider must include the + domain in the groups list (which is the default behaviour for Google + and GitHub auth). + +Special cases: + +* If any matched customer value is ``*``, the user is treated as having + access to **all** customers. +* If the user's login appears in ``ADMIN_USERS``, the lookup short-circuits + and returns all customers (admin access). + + +Creating Customer Lookups +------------------------- + +Customer lookup entries are managed via the ``/customer`` API endpoint. +Only users with the ``admin:customers`` scope can create, update, or delete +entries. + +Create a lookup +~~~~~~~~~~~~~~~ + +:: + + POST /customer + +.. code-block:: bash + + $ curl -X POST http://localhost:8080/api/customer \ + -H "Authorization: Key " \ + -H "Content-Type: application/json" \ + -d '{ + "match": "example.com", + "customer": "Example Corp" + }' + +Response: + +.. code-block:: json + + { + "customer": { + "customer": "Example Corp", + "href": "http://localhost:8080/api/customer/8e9c4736-...", + "id": "8e9c4736-...", + "match": "example.com" + }, + "id": "8e9c4736-...", + "status": "ok" + } + +List all lookups +~~~~~~~~~~~~~~~~ + +:: + + GET /customers + +.. code-block:: bash + + $ curl http://localhost:8080/api/customers \ + -H "Authorization: Key " + +Update a lookup +~~~~~~~~~~~~~~~ + +:: + + PUT /customer/:id + +.. code-block:: bash + + $ curl -X PUT http://localhost:8080/api/customer/ \ + -H "Authorization: Key " \ + -H "Content-Type: application/json" \ + -d '{ + "customer": "New Customer Name" + }' + +Delete a lookup +~~~~~~~~~~~~~~~ + +:: + + DELETE /customer/:id + +.. code-block:: bash + + $ curl -X DELETE http://localhost:8080/api/customer/ \ + -H "Authorization: Key " + + +How Alerts Are Filtered +----------------------- + +When customer views are enabled the ``customer`` attribute acts as an +implicit filter on all queries: + +* **Sending alerts** -- When an alert is created using an API key that + belongs to a customer user, the ``customer`` field is automatically set + to that user's customer value. There is no need to include ``customer`` + in the alert payload. + +* **Querying alerts** -- When a customer user queries ``GET /alerts``, + the server appends an additional filter so that only alerts matching + their customer are returned. + +* **Heartbeats** -- The same filtering applies to heartbeats. Customer + users only see heartbeats tagged with their customer value. + +* **Blackout periods** -- Customer users can only create blackout periods + that apply to their own customer's alerts. + +This filtering is transparent and requires no changes to API calls. + + +Admin vs Customer Users +----------------------- + ++---------------------------------+-------------------+-------------------+ +| Capability | Admin User | Customer User | ++=================================+===================+===================+ +| View all alerts | Yes | No (own only) | ++---------------------------------+-------------------+-------------------+ +| Create / delete customer | Yes | No | +| lookups | | | ++---------------------------------+-------------------+-------------------+ +| Manage users | Yes | No | ++---------------------------------+-------------------+-------------------+ +| Create API keys | Any scope | Customer-scoped | ++---------------------------------+-------------------+-------------------+ +| Create blackout periods | Any customer | Own customer only | ++---------------------------------+-------------------+-------------------+ +| View heartbeats | All | Own customer only | ++---------------------------------+-------------------+-------------------+ - ADMIN_USERS = ['foo@bar.com'] +A user is considered an admin if their login appears in the ``ADMIN_USERS`` +list **or** if they have been assigned an ``admin`` role via +``ADMIN_ROLES``. -3. Populate the Customer Lookup table in the web console to map Google email domains or Github/Gitlab orgs and groups to customers -Web Console for Users ---------------------- +Configuration Reference +----------------------- -Users that have a `customer view` are limited to what they can do in the web console (and via the API). They cannot create other users, configure blackout periods or modify the customer lookup table. +The following settings in ``alertad.conf`` control customer views: ++---------------------+----------+-----------+---------------------------------------------+ +| Setting | Type | Default | Description | ++=====================+==========+===========+=============================================+ +| ``AUTH_REQUIRED`` | boolean | ``False`` | Must be ``True`` for customer views to work | ++---------------------+----------+-----------+---------------------------------------------+ +| ``CUSTOMER_VIEWS`` | boolean | ``False`` | Enable customer-based alert partitioning | ++---------------------+----------+-----------+---------------------------------------------+ +| ``ADMIN_USERS`` | list | ``[]`` | List of user logins (emails) with full | +| | | | admin access across all customers | ++---------------------+----------+-----------+---------------------------------------------+ +| ``ADMIN_ROLES`` | list | ``['admin | Roles that grant admin privileges | +| | | ']`` | | ++---------------------+----------+-----------+---------------------------------------------+ -Web Console for Administrators ------------------------------- +Related scopes: -Administrators are not limited in what they can do in the web console (or via the API). Importantly, they can configure the customer lookup table. +* ``admin:customers`` -- required to create, update, or delete customer + lookup entries. +* ``read:customers`` -- required to list customer lookup entries. diff --git a/source/deployment.rst b/source/deployment.rst index 2962692..c1ea4eb 100644 --- a/source/deployment.rst +++ b/source/deployment.rst @@ -105,11 +105,11 @@ Authentication & SSL Alerta supports several authentication mechanisms for both the API and the web UI and some key features of the web UI, like -:ref:`watching alerts `, are only available if +watching alerts, are only available if authentication is enabled. The API can be secured using :ref:`API keys` and the web UI can -be secured using :ref:`Basic Auth ` or an :ref:`OAuth ` +be secured using :ref:`Basic Auth ` or an :ref:`OAuth ` provider from either GitHub, GitLab, Google, Keycloak or SAML2. If you plan to make the web UI accessible from a public URL it is @@ -122,7 +122,7 @@ alert data. Authorisation & Customer Views ------------------------------ -To restrict access to certain features use :ref:`roles ` +To restrict access to certain features use :ref:`roles ` and :ref:`customer views `. .. _scalability: @@ -214,7 +214,7 @@ track of realtime statistics on the performance of the Alerta API like alert counts and average processing time. For convenience, these statistics can be viewed in the *About* page of the Alerta web UI or using the ``alerta`` command-line tool -:ref:`status ` command. +``status`` command. The same metrics are also exposed at :file:`/management/metrics` in the `exposition format`_ required by Prometheus so that it can be monitored diff --git a/source/faq.rst b/source/faq.rst index 72ada42..4c954de 100644 --- a/source/faq.rst +++ b/source/faq.rst @@ -43,7 +43,7 @@ attribute is for) and so that the web console can organise by ``environemnt`` and filter alerts by ``service``. However, one of the principles of Alerta is not to enforce its view of the -world on users so the plugin can be :ref:`easily configured `, +world on users so the plugin can be :ref:`easily configured `, :ref:`modified ` or completely disabled. It's up to you. Can I define custom severity codes and levels? diff --git a/source/gettingstarted/tutorial-1-deploy-alerta.rst b/source/gettingstarted/tutorial-1-deploy-alerta.rst index 95f73be..0b38e85 100644 --- a/source/gettingstarted/tutorial-1-deploy-alerta.rst +++ b/source/gettingstarted/tutorial-1-deploy-alerta.rst @@ -135,8 +135,6 @@ on reboot: $ sudo systemctl status uwsgi $ sudo systemctl enable uwsgi -:: - Configure nginx to serve Alerta as a uWsgi application on ``/api`` and the web console as static assets. diff --git a/source/gettingstarted/tutorial-4-customisation.rst b/source/gettingstarted/tutorial-4-customisation.rst index e34d413..bb98a00 100644 --- a/source/gettingstarted/tutorial-4-customisation.rst +++ b/source/gettingstarted/tutorial-4-customisation.rst @@ -1,4 +1,7 @@ +.. _tutorial 4 customisation: +Customising Alerts +================== use two custom attributes that are more meaningful to our business... 1. priority diff --git a/source/index.rst b/source/index.rst index 2aa0b22..0fa5b62 100644 --- a/source/index.rst +++ b/source/index.rst @@ -15,7 +15,7 @@ monitoring_ tools_ and it is easy to add your own using the :ref:`API ` directly, the :ref:`Python SDK ` or the same command-line tool to :ref:`send alerts `. Access to the API and command-line tool can be restricted using :ref:`API keys ` and to the web console using -:ref:`Basic Auth ` or :ref:`OAuth2 ` providers Google, +:ref:`Basic Auth ` or :ref:`OAuth2 ` providers Google, GitHub and GitLab. .. _popular: https://www.pingdom.com @@ -58,6 +58,26 @@ The required API key is ``demo-key``. authorization deployment +.. toctree:: + :caption: Getting Started + :maxdepth: 2 + :hidden: + + gettingstarted/tutorial-1-deploy-alerta + gettingstarted/tutorial-2-housekeeping + gettingstarted/tutorial-3-plugins + gettingstarted/tutorial-4-alerts + gettingstarted/tutorial-4-customisation + gettingstarted/tutorial-5-blackouts + gettingstarted/tutorial-6-auth + gettingstarted/tutorial-7-cusomter-views + gettingstarted/tutorial-8-integration-nagios + gettingstarted/tutorial-8-integration-zabbix + gettingstarted/tutorial-8-webhooks + gettingstarted/tutorial-9-troubleshooting + gettingstarted/tutorial-10-docker + gettingstarted/tutorial-11-kubernetes + .. toctree:: :caption: Extensions :maxdepth: 2 @@ -78,6 +98,7 @@ The required API key is ``demo-key``. design conventions development + lifecycle Tutorials resources faq @@ -94,6 +115,22 @@ The required API key is ``demo-key``. api/alert api/heartbeat +.. toctree:: + :caption: Web UI + :maxdepth: 2 + :hidden: + + webui/alerts + webui/apikeys + webui/authentication + webui/blackouts + webui/configuration + webui/heartbeats + webui/permissions + webui/reports + webui/settings + webui/users + .. toctree:: :caption: More :maxdepth: 2 diff --git a/source/plugins.rst b/source/plugins.rst index 2658aee..060f2af 100644 --- a/source/plugins.rst +++ b/source/plugins.rst @@ -3,8 +3,6 @@ Plug-ins ======== -.. _plugins: - Plugins -------