Clarify webhook auth token details (#996)

Update text about webhook auth tokens to clarify MinIO uses the value
specified as it is. So if it needs `Bearer` or `Basic` or something
else, that must be included in the string.

Affected items:
- `MINIO_LOGGER_WEBHOOK_AUTH_TOKEN`
- `MINIO_AUDIT_WEBHOOK_AUTH_TOKEN`
- `MINIO_NOTIFY_WEBHOOK_AUTH_TOKEN`
- `mc admin config set logger_webhook auth_token`
- `mc admin config set audit_webhook auth_token`
- `mc admin config set notify_webhook auth_token`

Staged:

_Publish Server or Audit Logs to an External Service_

http://192.241.195.202:9000/staging/DOCS-407/linux/operations/monitoring/minio-logging.html#publish-server-logs-to-http-webhook

http://192.241.195.202:9000/staging/DOCS-407/linux/operations/monitoring/minio-logging.html#publish-audit-logs-to-http-webhook

_mc admin config_

http://192.241.195.202:9000/staging/DOCS-407/linux/reference/minio-mc-admin/mc-admin-config.html#mc-conf.logger_webhook.auth_token

http://192.241.195.202:9000/staging/DOCS-407/linux/reference/minio-mc-admin/mc-admin-config.html#mc-conf.audit_webhook.auth_token

http://192.241.195.202:9000/staging/DOCS-407/linux/reference/minio-mc-admin/mc-admin-config.html#mc-conf.notify_webhook.auth_token

_MinIO Server_

http://192.241.195.202:9000/staging/DOCS-407/linux/reference/minio-server/minio-server.html#envvar.MINIO_LOGGER_WEBHOOK_AUTH_TOKEN

http://192.241.195.202:9000/staging/DOCS-407/linux/reference/minio-server/minio-server.html#envvar.MINIO_AUDIT_WEBHOOK_AUTH_TOKEN

http://192.241.195.202:9000/staging/DOCS-407/linux/reference/minio-server/minio-server.html#envvar.MINIO_NOTIFY_WEBHOOK_AUTH_TOKEN


Fixes https://github.com/minio/docs/issues/407

source/includes/common-mc-admin-config.rst

@@ -996,17 +996,6 @@ Specify the URL for the webhook service.
 
 .. end-minio-notify-webhook-endpoint
 
-.. start-minio-notify-webhook-auth-token
-
-Specify the opaque string or JWT authorization token to use for 
-authenticating to the webhook service.
-
-.. versionchanged:: RELEASE.2023-06-23T20-26-00Z
-
-   MinIO redacts this value when returned as part of :mc-cmd:`mc admin config get`.
-
-.. end-minio-notify-webhook-auth-token
-
 .. start-minio-notify-webhook-client-cert
 
 Specify the path to the client certificate to use for performing 

source/operations/monitoring/minio-logging.rst

@@ -75,9 +75,26 @@ runtime configuration settings.
       - Replace ``https://webhook-1.example.net`` with the URL of the HTTP
         webhook endpoint.
 
-      - Replace ``TOKEN`` with a JSON Web Token (JWT) to use for authenticating
+      - Replace ``TOKEN`` with an authentication token of the appropriate type for the endpoint.
-        to the webhook endpoints. Omit for endpoints which do not require
+        Omit for endpoints which do not require authentication.
-        authentication.
+
+        To allow for a variety of token types, MinIO creates the request authentication header using the value *exactly as specified*.
+        Depending on the endpoint, you may need to include additional information.
+
+        For example: for a Bearer token, prepend ``Bearer``:
+
+        .. code-block:: shell
+
+           set MINIO_LOGGER_WEBHOOK_AUTH_TOKEN_myendpoint="Bearer 1a2b3c4f5e"
+
+        Modify the value according to the endpoint requirements.
+        A custom authentication format could resemble the following:
+
+        .. code-block:: shell
+
+           set MINIO_LOGGER_WEBHOOK_AUTH_TOKEN_xyz="ServiceXYZ 1a2b3c4f5e"
+
+        Consult the documenation for the desired service for more details.
 
       Restart the MinIO server to apply the new configuration settings. You
       must specify the same environment variables and settings on 
@@ -97,8 +114,8 @@ runtime configuration settings.
       .. code-block:: shell
          :class: copyable
 
-         mc admin config set ALIAS/ logger_webhook:IDENTIFIER \
+         mc admin config set ALIAS/ logger_webhook:IDENTIFIER  \
-            endpoint="https://webhook-1.example.net" \
+            endpoint="https://webhook-1.example.net"           \
             auth_token="TOKEN" 
 
       - Replace ``<IDENTIFIER>`` with a unique descriptive string for the 
@@ -113,9 +130,32 @@ runtime configuration settings.
       - Replace ``https://webhook-1.example.net`` with the URL of the HTTP
         webhook endpoint.
 
-      - Replace ``TOKEN`` with a JSON Web Token (JWT) to use for authenticating
+      - Replace ``TOKEN`` with an authentication token of the appropriate type for the endpoint.
-        to the webhook endpoints. Omit for endpoints which do not require
+        Omit for endpoints which do not require authentication.
-        authentication.
+
+	To allow for a variety of token types, MinIO creates the request authentication header using the value *exactly as specified*.
+        Depending on the endpoint, you may need to include additional information.
+
+        For example: for a Bearer token, prepend ``Bearer``:
+
+        .. code-block:: shell
+           :class: copyable
+
+            mc admin config set ALIAS/ logger_webhook    \
+               endpoint="https://webhook-1.example.net"  \
+               auth_token="Bearer 1a2b3c4f5e"
+
+        Modify the value according to the endpoint requirements.
+        A custom authentication format could resemble the following:
+
+        .. code-block:: shell
+           :class: copyable
+
+           mc admin config set ALIAS/ logger_webhook    \
+              endpoint="https://webhook-1.example.net"  \
+              auth_token="ServiceXYZ 1a2b3c4f5e"
+
+        Consult the documenation for the desired service for more details.
 
 .. _minio-logging-publish-audit-logs:
 
@@ -162,9 +202,26 @@ settings:
       - Replace ``https://webhook-1.example.net`` with the URL of the HTTP
         webhook endpoint.
 
-      - Replace ``TOKEN`` with a JSON Web Token (JWT) to use for authenticating
+      - Replace ``TOKEN`` with an authentication token of the appropriate type for the endpoint. 
-        to the webhook endpoints. Omit for endpoints which do not require
+        Omit for endpoints which do not require authentication.
-        authentication.
+
+        To allow for a variety of token types, MinIO creates the request authentication header using the value *exactly as specified*. 
+        Depending on the endpoint, you may need to include additional information.
+
+        For example: for a Bearer token, prepend ``Bearer``:
+
+        .. code-block:: shell
+
+           set MINIO_AUDIT_WEBHOOK_AUTH_TOKEN_myendpoint="Bearer 1a2b3c4f5e"
+
+        Modify the value according to the endpoint requirements.
+        A custom authentication format could resemble the following:
+
+        .. code-block:: shell
+
+           set MINIO_AUDIT_WEBHOOK_AUTH_TOKEN_xyz="ServiceXYZ 1a2b3c4f5e"
+
+        Consult the documenation for the desired service for more details.
 
       - Replace ``cert.pem`` and ``cert.key`` with the public and private key
         of the x.509 TLS certificates to present to the HTTP webhook server.
@@ -189,10 +246,10 @@ settings:
       .. code-block:: shell
          :class: copyable
 
-         mc admin config set ALIAS/ audit_webhook:IDENTIFIER \
+         mc admin config set ALIAS/ audit_webhook:IDENTIFIER  \
-            endpoint="https://webhook-1.example.net" \
+            endpoint="https://webhook-1.example.net"          \
-            auth_token="TOKEN" \
+            auth_token="TOKEN"                                \
-            client_cert="cert.pem" \
+            client_cert="cert.pem"                            \
             client_key="cert.key"
 
       - Replace ``<IDENTIFIER>`` with a unique descriptive string for the 
@@ -207,9 +264,32 @@ settings:
       - Replace ``https://webhook-1.example.net`` with the URL of the HTTP
         webhook endpoint.
 
-      - Replace ``TOKEN`` with a JSON Web Token (JWT) to use for authenticating
+      - Replace ``TOKEN`` with an authentication token of the appropriate type for the endpoint.
-        to the webhook endpoints. Omit for endpoints which do not require
+        Omit for endpoints which do not require authentication.
-        authentication.
+
+        To allow for a variety of token types, MinIO creates the request authentication header using the value *exactly as specified*.
+        Depending on the endpoint, you may need to include additional information.
+
+        For example: for a Bearer token, prepend ``Bearer``:
+
+        .. code-block:: shell
+           :class: copyable
+
+            mc admin config set ALIAS/ audit_webhook     \
+               endpoint="https://webhook-1.example.net"  \
+               auth_token="Bearer 1a2b3c4f5e"
+
+        Modify the value according to the endpoint requirements.
+        A custom authentication format could resemble the following:
+
+        .. code-block:: shell
+           :class: copyable
+
+           mc admin config set ALIAS/ audit_webhook     \
+              endpoint="https://webhook-1.example.net"  \
+              auth_token="ServiceXYZ 1a2b3c4f5e"
+
+        Consult the documenation for the desired service for more details.
 
       - Replace ``cert.pem`` and ``cert.key`` with the public and private key
         of the x.509 TLS certificates to present to the HTTP webhook server.
@@ -221,7 +301,7 @@ Audit Log Structure
 
 MinIO audit logs resemble the following JSON document:
 
-- The ``api.timeToFirstBite`` and ``api.timeToResponse`` fields are expressed
+- The ``api.timeToFirstByte`` and ``api.timeToResponse`` fields are expressed
   in nanoseconds.
 
 - For :ref:`erasure coded setups <minio-erasure-coding>` 

source/reference/minio-mc-admin/mc-admin-config.rst

@@ -179,8 +179,32 @@ HTTP Webhook Log Target
 
       *Optional*
 
-      The JSON Web Token (JWT) to use for authenticating to the HTTP webhook.
+      An authentication token of the appropriate type for the endpoint.
-      Omit for webhooks which do not enforce authentication.
+      Omit for endpoints which do not require authentication.
+
+      To allow for a variety of token types, MinIO creates the request authentication header using the value *exactly as specified*.
+      Depending on the endpoint, you may need to include additional information.
+
+      For example: for a Bearer token, prepend ``Bearer``:
+
+      .. code-block:: shell
+         :class: copyable
+
+            mc admin config set myminio logger_webhook   \
+               endpoint="https://webhook-1.example.net"  \
+               auth_token="Bearer 1a2b3c4f5e"
+
+      Modify the value according to the endpoint requirements.
+      A custom authentication format could resemble the following:
+
+      .. code-block:: shell
+         :class: copyable
+
+            mc admin config set myminio logger_webhook   \
+	       endpoint="https://webhook-1.example.net"  \
+               auth_token="ServiceXYZ 1a2b3c4f5e"
+
+      Consult the documenation for the desired service for more details.
 
       This configuration setting corresponds with the :envvar:`MINIO_LOGGER_WEBHOOK_AUTH_TOKEN` environment variable.
 
@@ -279,11 +303,35 @@ HTTP Webhook Audit Log Target
       This configuration setting corresponds with the :envvar:`MINIO_AUDIT_WEBHOOK_ENDPOINT` environment variable.
 
    .. mc-conf:: auth_token
-      
+
       *Optional*
 
-      The JSON Web Token (JWT) to use for authenticating to the HTTP webhook.
+      An authentication token of the appropriate type for the endpoint.
-      Omit for webhooks which do not enforce authentication.
+      Omit for endpoints which do not require authentication.
+
+      To allow for a variety of token types, MinIO creates the request authentication header using the value *exactly as specified*.
+      Depending on the endpoint, you may need to include additional information.
+
+      For example: for a Bearer token, prepend ``Bearer``:
+
+      .. code-block:: shell
+         :class: copyable
+
+         mc admin config set myminio audit_webhook       \
+                  endpoint="http://webhook.example.net"  \
+                  auth_token="Bearer 1a2b3c4f5e"
+
+      Modify the value according to the endpoint requirements.
+      A command for a custom authentication format could resemble the following:
+
+      .. code-block:: shell
+         :class: copyable
+
+         mc admin config set myminio audit_webhook       \
+                  endpoint="http://webhook.example.net"  \
+                  auth_token="ServiceXYZ 1a2b3c4f5e"
+
+      Consult the documenation for the desired service for more details.
 
       This configuration setting corresponds with the :envvar:`MINIO_AUDIT_WEBHOOK_AUTH_TOKEN` environment variable.
 
@@ -2139,9 +2187,36 @@ using these environment variables.
 
       *Optional*
 
-      .. include:: /includes/common-mc-admin-config.rst
+      An authentication token of the appropriate type for the endpoint.
-         :start-after: start-minio-notify-webhook-auth-token
+      Omit for endpoints which do not require authentication.
-         :end-before: end-minio-notify-webhook-auth-token
+
+      To allow for a variety of token types, MinIO creates the request authentication header using the value *exactly as specified*.
+      Depending on the endpoint, you may need to include additional information.
+
+      For example: for a Bearer token, prepend ``Bearer``:
+
+      .. code-block:: shell
+         :class: copyable
+
+            mc admin config set myminio notify_webhook   \
+	       endpoint="https://webhook-1.example.net"  \
+               auth_token="Bearer 1a2b3c4f5e"
+
+      Modify the value according to the endpoint requirements.
+      A custom authentication format could resemble the following:
+
+      .. code-block:: shell
+         :class: copyable
+
+            mc admin config set myminio notify_webhook   \
+               endpoint="https://webhook-1.example.net"  \
+               auth_token="ServiceXYZ 1a2b3c4f5e"
+
+      Consult the documenation for the desired service for more details.
+
+      .. versionchanged:: RELEASE.2023-06-23T20-26-00Z
+
+      MinIO redacts this value when returned as part of :mc-cmd:`mc admin config get`.
 
       This configuration setting corresponds with the :envvar:`MINIO_NOTIFY_WEBHOOK_AUTH_TOKEN` environment variable.
 

source/reference/minio-server/minio-server.rst

@@ -694,8 +694,28 @@ server logs webhook endpoints:
 
    *Optional*
 
-   The JSON Web Token (JWT) to use for authenticating to the HTTP webhook.
+   An authentication token of the appropriate type for the endpoint.
-   Omit for webhooks which do not enforce authentication.
+   Omit for endpoints which do not require authentication.
+
+   To allow for a variety of token types, MinIO creates the request authentication header using the value *exactly as specified*.
+   Depending on the endpoint, you may need to include additional information.
+
+   For example: for a Bearer token, prepend ``Bearer``:
+
+   .. code-block:: shell
+      :class: copyable
+
+      set MINIO_LOGGER_WEBHOOK_AUTH_TOKEN_myendpoint="Bearer 1a2b3c4f5e"
+
+   Modify the value according to the endpoint requirements.
+   A custom authentication format could resemble the following:
+
+   .. code-block:: shell
+      :class: copyable
+
+      set MINIO_LOGGER_WEBHOOK_AUTH_TOKEN_xyz="ServiceXYZ 1a2b3c4f5e"
+
+   Consult the documenation for the desired service for more details.
 
    This environment variable corresponds with the :mc-conf:`logger_webhook auth_token <logger_webhook.auth_token>` configuration setting.
 
@@ -796,8 +816,28 @@ audit log webhook endpoints:
 
    *Optional*
 
-   The JSON Web Token (JWT) to use for authenticating to the HTTP webhook.
+   An authentication token of the appropriate type for the endpoint.
-   Omit for webhooks which do not enforce authentication.
+   Omit for endpoints which do not require authentication.
+
+   To allow for a variety of token types, MinIO creates the request authentication header using the value *exactly as specified*.
+   Depending on the endpoint, you may need to include additional information.
+
+   For example: for a Bearer token, prepend ``Bearer``:
+
+   .. code-block:: shell
+      :class: copyable
+
+      set MINIO_AUDIT_WEBHOOK_AUTH_TOKEN_myendpoint="Bearer 1a2b3c4f5e"
+
+   Modify the value according to the endpoint requirements.
+   A custom authentication format could resemble the following:
+
+   .. code-block:: shell
+      :class: copyable
+
+      set MINIO_AUDIT_WEBHOOK_AUTH_TOKEN_xyz="ServiceXYZ 1a2b3c4f5e"
+
+   Consult the documenation for the desired service for more details.
 
    This environment variable corresponds with the :mc-conf:`audit_webhook auth_token <audit_webhook.auth_token>` configuration setting.
 
@@ -2392,9 +2432,28 @@ endpoints as ``PRIMARY`` and ``SECONDARY`` respectively:
 
    *Required*
 
-   .. include:: /includes/common-mc-admin-config.rst
+   An authentication token of the appropriate type for the endpoint.
-      :start-after: minio-notify-webhook-auth-token
+   Omit for endpoints which do not require authentication.
-      :end-before: minio-notify-webhook-auth-token
+
+   To allow for a variety of token types, MinIO creates the request authentication header using the value *exactly as specified*.
+   Depending on the endpoint, you may need to include additional information.
+
+   For example: for a Bearer token, prepend ``Bearer``:
+
+   .. code-block:: shell
+      :class: copyable
+
+      set MINIO_NOTIFY_WEBHOOK_AUTH_TOKEN_myendpoint="Bearer 1a2b3c4f5e"
+
+   Modify the value according to the endpoint requirements.
+   A custom authentication format could resemble the following:
+
+   .. code-block:: shell
+      :class: copyable
+
+      set MINIO_NOTIFY_WEBHOOK_AUTH_TOKEN_xyz="ServiceXYZ 1a2b3c4f5e"
+
+   Consult the documenation for the desired service for more details.
 
    This environment variable corresponds with the :mc-conf:`notify_webhook auth_token <notify_webhook.auth_token>` configuration setting.