Comms API - `POST /authentication` endpoint implementation

[GGP1]

Epic
#24305

Description

The API will use the JSON Web Tokens (JWTs) open standard (RFC 7519) to authenticate client requests. Any agent communicating with this API will be required to authenticate using a POST /authentication endpoint, which will be implemented in this issue.

The credentials provided by the agent will be compare against the ones obtained from the agent list index stored in the Wazuh indexer.

Authentication flow

Flow

```mermaid flowchart TD subgraph Agents Endpoints Clouds Other end subgraph Server["Server cluster"] subgraph Wazuh1["Server node n"] api1["Agent comms API"] end end subgraph Indexer subgraph Data_states["Data states"] agents_list["Agents list"] end end subgraph lb["Load Balancer"] lb_node["Per request"] end Agents -- 1. /login --> lb lb -- 1. /login --> Wazuh1 Wazuh1 -- 2. Read credentials --> agents_list Indexer -- 3. Credentials response --> Wazuh1 Wazuh1 -- 4. Authentication response --> Agents style Wazuh1 fill:#abc2eb style Data_states fill:#abc2eb ```

JWT token

Algorithm

The algorithm used to sign the tokens will be the Elliptic Curve Digital Signature Algorithm with the P-256 curve and the SHA-256 cryptographic hash function (ES256).

Payload

The payload will contain public claims such as the issuer, audience, subject and timestamps indicating when the token was issued and when it expires.

Additionally, it will contain a uuid field that will store the agent's UUID. This way, the API will be able to identify which agent is doing the request and respond according to it.

{
  "iss": "wazuh", > issuer
  "aud": "Wazuh Communications API", > audience
  "iat": 1717524220, > issued at
  "exp": 1717525120, > expiration
  "uuid": "018fe477-31c8-7580-ae4a-e0b36713eb05", > agent UUID v7
}

Timestamp and expiration

The iat field will be populated with the timestamp at which the token is issued and the exp field will be set to the timestamp at which the token is considered expired (iat + expiration_time).

The expiration time we will use is 900 seconds (15m), which is what we are using currently in the Server management API.

Request

The request body will contain a UUID and a key.

{
    "uuid": "<UUID>",
    "key": "<KEY>"
}

Responses

Success

A successful response will contain a 200 HTTP status and a JSON struct with a token field and the token itself in the value.

{
    "token": "<TOKEN>"
}

Failure

A failed response will contain a JSON struct following format defined in https://github.com/wazuh/wazuh/issues/23395#issuecomment-2178737901 and an HTTP status between 300 and 505.

{
    "error": {
        "message": "Invalid JWT token",
        "code": 403
    }
}

Dependencies

• https://github.com/wazuh/wazuh/issues/24616
• https://github.com/wazuh/wazuh/issues/24615

[GGP1]

Update

• Implemented the authentication endpoint and the class to authenticate agents on other endpoints
• Created a class to handle exceptions within routers
• Updated framework authentication methods to reuse them with a different elliptic curve
• Converted the timeout middleware to a decorator and updated its unit tests

[GGP1]

Update

• Integrated the new indexer client to obtain and compare agent credentials
• Created a function to handle request validation errors better
• Created unit tests for all the functions and methods added

[GGP1]

Update

• Created an indexer client method to update agents
• Setup the development environment with and opensearch container
• Tested the implementation and applied minor corrections, tests logs were left in the PR's description

[GGP1]

Update

Applied the changes suggested.

[GGP1]

Update

Applied the changes suggested.

[GGP1]

Update

Added a dot to the end of the docstrings.