Replace all TBC/FIXME placeholders with real content

- configuration.rst: Add examples for OIDC, SAML2, Cognito, GitHub,
  GitLab, Google, Keycloak auth settings; fix OIDC_AUTH_URL and
  OIDC_LOGOUT_URL descriptions
- integrations.rst: Document Zabbix, Graylog and Slack integrations
- tutorial-4-alerts.rst: Write groups/types/origins, tags/attributes,
  and raw data sections
- authentication.rst: Document Amazon Cognito setup and HMAC auth
- server.rst: Document operator actions

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: satterly

source/authentication.rst

@@ -409,7 +409,36 @@ the OpenID Connect authentication provider for Alerta follow the steps below.
 Amazon Cognito
 ~~~~~~~~~~~~~~
 
-.. note:: TBC
+To use `Amazon Cognito`_ as the OAuth2 provider for Alerta, set up
+a User Pool and App Client in the AWS Console:
+
+#. Create a Cognito User Pool (or use an existing one) and note the
+   **User Pool ID** (e.g. ``us-east-1_aBcDeFgHi``).
+
+#. Under "App integration", create an App Client for Alerta:
+
+   - App client name: ``Alerta``
+   - Callback URL: ``http://alerta.example.com``
+   - Allowed OAuth Flows: Authorization code grant
+   - Allowed OAuth Scopes: openid, email, profile
+
+#. Configure a Cognito Domain (either a custom domain or the default
+   Amazon Cognito domain prefix), for example: ``alerta-auth``.
+
+#. Copy the generated **Client ID** and **Client Secret**.
+
+#. Add the configuration to the ``alertad.conf`` server configuration:
+
+.. code:: python
+
+    AUTH_PROVIDER = 'cognito'
+    AWS_REGION = 'us-east-1'
+    COGNITO_USER_POOL_ID = 'us-east-1_aBcDeFgHi'
+    COGNITO_DOMAIN = 'alerta-auth'
+    OAUTH2_CLIENT_ID = '1abc2def3ghi4jkl5mno6pqr7s'
+    OAUTH2_CLIENT_SECRET = 'us1-abc123-def456-ghi789'
+
+.. _Amazon Cognito: https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools.html
 
 
 .. _gitlab_oauth2:
@@ -655,4 +684,25 @@ Use the ``api-key`` URL parameter::
 HMAC Auth
 ---------
 
-.. note:: TBC
+HMAC authentication provides a secure method for machine-to-machine
+communication with the Alerta API. Instead of using static API keys,
+HMAC uses a shared secret to sign each request, ensuring both
+authenticity and integrity.
+
+To configure HMAC authentication, add one or more credentials to the
+``alertad.conf`` server configuration:
+
+.. code:: python
+
+    HMAC_AUTH_CREDENTIALS = [
+        {
+            'key': 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',  # access key ID
+            'secret': 'MWYyZDdjMzg3ZjRjNTExZWM4NjNkYzYw',  # secret key (base64)
+            'algorithm': 'sha256'  # valid: sha256, sha384, sha512
+        }
+    ]
+
+The ``key`` is sent as a header to identify the caller, while the
+``secret`` is used to compute the HMAC signature of the request. The
+server verifies the signature against the stored secret for the given
+key, rejecting requests with invalid or missing signatures.

source/configuration.rst

@@ -378,7 +378,13 @@ OpenID Connect Auth Settings
 
 .. code:: python
 
-    FIXME
+    AUTH_PROVIDER = 'openid'
+    OIDC_ISSUER_URL = 'https://accounts.example.com/.well-known/openid-configuration'
+    OAUTH2_CLIENT_ID = '1234567890.apps.example.com'
+    OAUTH2_CLIENT_SECRET = 'ABCDefgh1234'
+    OIDC_VERIFY_TOKEN = False
+    ALLOWED_OIDC_ROLES = ['admin', 'operator']
+    ALLOWED_EMAIL_DOMAINS = ['example.com']
 
 .. index:: OAUTH2_CLIENT_ID, OAUTH2_CLIENT_SECRET, OIDC_ISSUER_URL, OIDC_AUTH_URL
 .. index:: OIDC_TOKEN_AUTH_METHODS, OIDC_LOGOUT_URL, OIDC_VERIFY_TOKEN
@@ -393,11 +399,11 @@ OpenID Connect Auth Settings
     issuer URL also known as Discovery Document is used to auto-discover
     all necessary auth endpoints for an OIDC client (required)
 ``OIDC_AUTH_URL``
-    FIXME check
+    authorization endpoint URL, auto-discovered from OIDC issuer URL if not explicitly set (default is ``None``)
 ``OIDC_TOKEN_AUTH_METHODS``
     list of token auth methods in order of preference (``client_secret_basic``, ``client_secret_post``, ``client_secret_jwt``)
 ``OIDC_LOGOUT_URL``
-    FIXME (no default)
+    end session endpoint URL, auto-discovered from OIDC issuer URL if not explicitly set (default is ``None``)
 ``OIDC_VERIFY_TOKEN``
     (default is ``False``)
 ``OIDC_ROLE_CLAIM``
@@ -422,7 +428,13 @@ SAML 2.0 Auth Settings
 
 .. code:: python
 
-    FIXME 
+    AUTH_PROVIDER = 'saml2'
+    SAML2_ENTITY_ID = 'https://alerta.example.com'
+    SAML2_METADATA_URL = 'https://idp.example.com/saml2/metadata'
+    SAML2_USER_NAME_FORMAT = '{givenName} {surname}'
+    SAML2_EMAIL_ATTRIBUTE = 'emailAddress'
+    ALLOWED_SAML2_GROUPS = ['alerta-admins', 'alerta-operators']
+    ALLOWED_EMAIL_DOMAINS = ['example.com']
 
 .. index:: SAML2_ENTITY_ID, SAML2_METADATA_URL, SAML2_USER_NAME_FORMAT, SAML2_EMAIL_ATTRIBUTE
 .. index:: SAML2_CONFIG, ALLOWED_SAML2_GROUPS
@@ -473,7 +485,13 @@ Amazon Cognito Auth Settings
 
 .. code:: python
 
-    FIXME
+    AUTH_PROVIDER = 'cognito'
+    AWS_REGION = 'us-east-1'
+    COGNITO_USER_POOL_ID = 'us-east-1_AbCdEfGhI'
+    COGNITO_DOMAIN = 'my-alerta-app'
+    OAUTH2_CLIENT_ID = '1a2b3c4d5e6f7g8h9i0j'
+    OAUTH2_CLIENT_SECRET = 'ABCDefgh1234'
+    ALLOWED_EMAIL_DOMAINS = ['example.com']
 
 .. index:: AWS_REGION, COGNITO_USER_POOL_ID, COGNITO_DOMAIN
 
@@ -493,7 +511,12 @@ GitHub Auth Settings
 
 .. code:: python
 
-    FIXME
+    AUTH_PROVIDER = 'github'
+    GITHUB_URL = 'https://github.com'
+    OAUTH2_CLIENT_ID = 'f7b68efc0e8e0dde0e0a'
+    OAUTH2_CLIENT_SECRET = 'ABCDefgh1234'
+    ALLOWED_GITHUB_ORGS = ['my-org']
+    ALLOWED_EMAIL_DOMAINS = ['example.com']
 
 .. index:: GITHUB_URL, ALLOWED_GITHUB_ORGS
 
@@ -515,7 +538,12 @@ GitLab Auth Settings
 
 .. code:: python
 
-    FIXME
+    AUTH_PROVIDER = 'gitlab'
+    GITLAB_URL = 'https://gitlab.com'
+    OAUTH2_CLIENT_ID = 'e52ef0a1abcdef1234567890'
+    OAUTH2_CLIENT_SECRET = 'ABCDefgh1234'
+    ALLOWED_GITLAB_GROUPS = ['my-group']
+    ALLOWED_EMAIL_DOMAINS = ['example.com']
 
 .. index:: GITLAB_URL, ALLOWED_GITLAB_GROUPS
 
@@ -533,7 +561,10 @@ Google Auth Settings
 
 .. code:: python
 
-    FIXME
+    AUTH_PROVIDER = 'google'
+    OAUTH2_CLIENT_ID = '123456789012-abc123def456ghi789.apps.googleusercontent.com'
+    OAUTH2_CLIENT_SECRET = 'ABCDefgh1234'
+    ALLOWED_EMAIL_DOMAINS = ['example.com']
 
 .. index:: OAUTH2_CLIENT_ID, OAUTH2_CLIENT_SECRET, ALLOWED_EMAIL_DOMAINS
 
@@ -553,7 +584,12 @@ Keycloack Auth Settings
 
 .. code:: python
 
-    FIXME
+    AUTH_PROVIDER = 'keycloak'
+    KEYCLOAK_URL = 'https://keycloak.example.com'
+    KEYCLOAK_REALM = 'master'
+    OAUTH2_CLIENT_ID = 'alerta-ui'
+    OAUTH2_CLIENT_SECRET = 'ABCDefgh1234'
+    ALLOWED_KEYCLOAK_ROLES = ['alerta-admin', 'alerta-operator']
 
 .. index:: KEYCLOAK_URL, KEYCLOAK_REALM, ALLOWED_KEYCLOAK_ROLES
 

source/gettingstarted/tutorial-4-alerts.rst

@@ -224,17 +224,63 @@ The alert ``service`` is used to detail the list of effected services.
 Step 5: Groups, types and origins
 ---------------------------------
 
-TBC
+The ``group``, ``event_type``, and ``origin`` attributes provide additional
+context for alerts and can be used to organise and filter them.
+
+The ``group`` attribute is used to group related alerts together. For example,
+all network-related alerts might be assigned to a "Network" group, while
+performance alerts could use "Performance".
+
+The ``event_type`` defines the kind of alert, such as ``exceptionAlert``,
+``performanceAlert``, or ``availabilityAlert``. This can be useful for
+routing alerts to different handlers.
+
+The ``origin`` identifies the source of the alert, such as a monitoring
+tool name or a specific host. It helps trace where the alert came from.
+
+.. code-block:: console
+
+  $ alerta send -r user01 -e loginStatus -v loginError -s major -E Production \
+  -S Security -t 'user01 login failed.' --group Security --origin auth-monitor \
+  --type exceptionAlert
+  9c11a5a8-2d8c-4e2f-bc6b-75e0e4c941fd (indeterminate -> major)
 
 Step 6: Tags and Custom attributes
 ----------------------------------
 
-TBC
+Tags and custom attributes allow you to add arbitrary metadata to alerts.
+Tags are simple labels that can be used to categorise alerts, while custom
+attributes are key-value pairs for more structured data.
+
+Tags are useful for filtering alerts in the web console and can be added
+using the ``-T`` option:
+
+.. code-block:: console
+
+  $ alerta send -r user01 -e loginStatus -v loginError -s major -E Production \
+  -S Security -t 'user01 login failed.' -T login -T security
+  a3b5c7d9-1e2f-4a6b-8c0d-2e4f6a8b0c2d (indeterminate -> major)
+
+Custom attributes are added using the ``-A`` option and take the form
+``key=value``:
+
+.. code-block:: console
+
+  $ alerta send -r user01 -e loginStatus -v loginError -s major -E Production \
+  -S Security -t 'user01 login failed.' -A ip=10.0.1.23 -A region=us-east-1
+  a3b5c7d9-1e2f-4a6b-8c0d-2e4f6a8b0c2d (duplicate)
 
 Step 7: Saving raw data
 -----------------------
 
-TBC
+The ``rawData`` attribute can be used to store the original, unprocessed
+data that generated the alert. This is useful for debugging or auditing
+purposes as it preserves the complete source event.
+
+When using the ``alerta`` command-line tool, raw data can be provided
+via standard input or the ``--raw-data`` option. When using webhooks,
+the raw data from the incoming request payload is automatically saved
+to the alert.
 
 Next Steps
 ----------

source/integrations.rst

@@ -148,7 +148,7 @@ The following is a list of integrations, webbhooks and plugins that highlight
 the use of bi-directional integration in different ways.
 
 * AWS Cloudwatch webhook - includes the `SNS subscription confirmation`_ link in the text of the alert
-* Zabbix integration & plugin - TBC
+* Zabbix integration & plugin - uses the `zabbix-alerta`_ gateway to forward Zabbix triggers to Alerta and includes a link back to the Zabbix trigger page via the ``moreInfo`` alert attribute
 * Grafana webhook - includes `rule and image links`_ in Grafana alert attributes if available
 * NewRelic webhook - includes `incident and runbook links`_ in NewRelic alerts
 * PagerDuty webhook - includes the `incident URL`_ in alert history text when status changes
@@ -160,6 +160,7 @@ the use of bi-directional integration in different ways.
 .. _incident and runbook links: https://github.com/alerta/alerta/blob/master/alerta/webhooks/newrelic.py#L33-L37
 .. _incident URL: https://github.com/alerta/alerta/blob/master/alerta/webhooks/pagerduty.py#L18
 .. _external and generator URLs: https://github.com/alerta/alerta/blob/master/alerta/webhooks/prometheus.py#L62-L65
+.. _zabbix-alerta: https://github.com/alerta/zabbix-alerta
 .. _moreInfo: https://github.com/alerta/zabbix-alerta/blob/master/zabbix_alerta.py#L67
 
 .. _webhooks:
@@ -226,7 +227,24 @@ For details on how to set this up see `Grafana webhook`_ page and in the
 Graylog
 ~~~~~~~
 
-TBC
+Alerta can be configured to receive Graylog alerts by adding a webhook
+endpoint as an HTTP alert notification.
+
+For details on how to set this up see the `Graylog HTTP alert notification`_
+page and in the URL input box append :file:`/webhooks/graylog` to the Alerta API URL.
+
+.. _Graylog HTTP alert notification: https://go2docs.graylog.org/current/interacting_with_your_log_data/notifications.html
+
+**Example Graylog Webhook URL**
+
+:file:`https://alerta.example.com/api/webhooks/graylog`
+
+**Example Graylog Webhook URL with authentication**
+
+:file:`https://alerta.example.com/api/webhooks/graylog?api-key=xxxxx`
+
+**The following parameters can be set in the URL**
+     environment, event, event_type, service, severity
 
 New Relic
 ~~~~~~~~~
@@ -333,7 +351,22 @@ For details on how to set this up see `SeverDensity webhook`_ page and in the
 Slack
 ~~~~~
 
-TBC
+Alerta can be configured to receive interactive messages from Slack using the
+Slack webhook. This enables operators to take actions on alerts (such as
+acknowledge, close, or watch) directly from Slack message buttons.
+
+To set up the integration, create a `Slack app`_ with interactive components
+and configure the Request URL to point to the Alerta API webhook endpoint.
+
+.. _Slack app: https://api.slack.com/slack-apps
+
+**Example Slack Webhook URL**
+
+:file:`https://alerta.example.com/api/webhooks/slack`
+
+**Example Slack Webhook URL with authentication**
+
+:file:`https://alerta.example.com/api/webhooks/slack?api-key=xxxxx`
 
 Google Stackdriver
 ~~~~~~~~~~~~~~~~~~

source/server.rst

@@ -102,7 +102,16 @@ Operator Actions
 Actions taken against alerts can be used as triggers for further integrations
 with external systems.
 
-TBC
+Operators can perform actions such as ``ack``, ``close``, ``open``, or
+custom-defined actions on alerts via the web UI or API. Each action triggers
+the ``take_action()`` method on all configured plugins, allowing them to
+respond to the action. For example, a plugin could send a notification to
+a Slack channel when an alert is acknowledged, or update an external
+incident management system when an alert is closed.
+
+Custom actions can be defined to extend the default set, enabling
+workflows specific to your organisation such as "escalate", "assign",
+or "create ticket".
 
 .. _status_change: