########
Channels
########

Channels receive data from clients using various protocols and also implement an authentication
layer. The currently supported protocols are:

.. __: https://mqtt.org/
.. __: https://www.rfc-editor.org/rfc/rfc9110.html

* MQTT__ (MQTT Broker);
* HTTP__ (HTTP Server).

*************
MQTT Channels
*************

The MQTT Channels provide access to the built-in MQTT Broker. The channel used to authenticate
the client is determined when the MQTT client attempts to establish a connection to the broker.
The channel resolution logic is as follows:

.. __: https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html#_Toc3901059
.. __: https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html#_Toc3901071

1. Channels bound to the `Client Identifier (ClientID)`__;
2. Channels bound to the `Username`__;
3. Anonymous channel (if enabled).

The first matching channel found is used for client authentication.

++++++++++++++
Authentication
++++++++++++++

The currently supported authentication methods are:

* Basic_
* `JSON Web Token`_ (JWT)

Anonymous access can also be allowed.

.. _Basic:

====================
Basic Authentication
====================

.. _MQTT CONNECT control message: https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html#_Toc3901033

Basic authentication uses a username/password pair, which is transmitted in
the `MQTT CONNECT control message`_.


.. _JSON Web Token:

==================
JWT Authentication
==================

.. _JSON Web Tokens: https://datatracker.ietf.org/doc/html/rfc7519

JWT Authentication is based on `JSON Web Tokens`_. Currently, only tokens signed with
ECDSA (ES256) are supported.

The MQTT Channel stores the public key and validates the JWT when a client connects to the channel.
The client signs the JWT using its private key and sends it in the Password field of
the `MQTT CONNECT control message`_. The Username field is mandatory when using MQTT v3.11.

*************
HTTP Channels
*************

The HTTP Channels provide an `API <./api.html>`__ for uploading messages to *Internal Queues* over HTTP/1.1
from where they can be retrieved by :ref:`Internal Queue Connector`. Both HTTP and HTTPS
are supported.

An HTTP Channel provides access only to the *Internal Queues* to which it is explicitly bound.

++++++++++++++
Authentication
++++++++++++++

The currently supported authentication methods are:

* `Basic HTTP Authentication <HTTP Basic Authentication_>`__
* `JSON Web Token <HTTP JSON Web Token_>`__ (JWT)

Anonymous access can also be allowed.

.. _HTTP Basic Authentication:

====================
Basic Authentication
====================

Basic Authentication follows the standard defined in the
`HTTP Basic Authentication Scheme <https://www.rfc-editor.org/rfc/rfc2617.html#section-2>`__.

The client must include an ``Authorization`` header containing the username and password,
separated by a single colon and encoded in base64::

    Authorization: Basic <base64(username:password)>

.. _HTTP JSON Web Token:

==================
JWT Authentication
==================

JWT Authentication is based on `JSON Web Tokens`_. Currently, only tokens signed with
ECDSA (ES256) are supported.

The HTTP Channel stores the public key and validates the JWT when it receives an HTTP request
from a client. The client signs the JWT using its private key and includes it
in the ``Authorization`` HTTP header::

    Authorization: Bearer <token>

+++++++++++
Message API
+++++++++++

To upload a message, a client must send a POST request with the payload encoded
as JSON to the HTTP channel URL::

    {
      "header": {
        "queues": ["my_queue1", "my_queue1"]
      }
      "message" : {
        ...
      }
    }