> ## Documentation Index
> Fetch the complete documentation index at: https://docs.datanumia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Security

## General information

This section focuses on implementing authentication for HOME Interfaces.

### Means of authentication

To be able to use HOME Interfaces web components, you first need to authenticate. To do so, HOME Interfaces expose the `dtn-integration-requirements` web component that handle most of the authentication logic. It accepts two types of token as an input:

* A forged HOME authentication token;
* A JSON Web Token (JWT) forged by your authentication process.

<Note>
  #### Recommandation

  We recommend using a JWT since `dtn-integration-requirements` implements the logic to obtain the HOME authentication token. This means less work for your integration team.
</Note>

### Authenticate using JWT

To authenticate using JWT you must follow the following requirements :

* Have a client id and an offer family associated to your company.
* The JWT you forged must contain, in its payload, at least the `person-external-id`.

***

## Integration requirements web component

### Description

The `dtn-integration-requirements` web component is required to correctly handle authentication in the HOME Interfaces context.

The web component can process two types of tokens :

* Json Web Token generated using the OpenID process
* A datanumia access token

### Usage

#### Import the basis scripts

```html theme={null}
<html>
  <head>
    <script src="https://new-front-intersi.qa.datanumia.com/basis/polyfills.js" 
        type="module"></script>
    <script src="https://new-front-intersi.qa.datanumia.com/basis/main.js" 
        type="module"></script>
  </head>
</html>
```

***

#### Using your application JWT

If the JWT's payload contains information on both the person external id and the site external id, you must provide those informations :

```html theme={null}
<html>
  <!-- import, see above-->
  <body>
  <dtn-integration-requirements 
    token="<your_jwt>" 
    offer-family="<offer-family>" 
    client-id="<client-id>">
  </dtn-integration-requirements>
  </body>
</html>
```

If it only contains informations on the person external id, you must provide the site the user wants to observe :

```html theme={null}
<html>
  <!-- import, see above-->
  <body>
  <dtn-integration-requirements 
    token="<your_jwt>" 
    offer-family="<offer-family>"
    site-external-id="<site-external-id>" 
    client-id="<client-id>">
  </dtn-integration-requirements>
  </body>
</html>
```

If it does not contains person external id and site external id, you must provide both information :

```html theme={null}
<html>
  <!-- import, see above-->
  <body>
  <dtn-integration-requirements 
    token="<your_jwt>" 
    offer-family="<offer-family>"
    site-external-id="<site-external-id>"
    person-external-id="<person-external-id>"
    client-id="<client-id>">
  </dtn-integration-requirements>
  </body>
</html>
```

***

#### Using a HOME authentication token

You also can use directly a datanumia token if you already created it.

```html theme={null}
<dtn-integration-requirements token="<datanumia-token>"></dtn-integration-requirements>
```

***

### Inputs

<ParamField path="token" type="string" required>
  The authentication token, which can be your **own JWT token** or a **Datanumia token**.
</ParamField>

<ParamField path="offer-family" type="string" required>
  The offer family associated with the authentication.

  Example: `FO-XXXX`
</ParamField>

<ParamField path="client-id" type="string" required>
  The client ID for the OAuth service.

  Example: `my-client-id`
</ParamField>

<ParamField path="site-external-id" type="string">
  Datanumia's external identifier for the site.

  Provide this value **if the JWT token does not contain the `site-external-id` claim**.
</ParamField>

<ParamField path="person-external-id" type="string">
  Datanumia's external identifier for a person.

  Provide this value **if the JWT token does not contain the `person-external-id` claim**.
</ParamField>

<Expandable title="json_schema">
  ```json json_schema theme={null}
  {
    "type": "object",
    "properties": {
      "token": {
        "type": "string",
        "description": "The authentication token, which can be your **own JWT token** or a **Datanumia token**."
      },
      "offer-family": {
        "type": "string",
        "description": "The offer family associated with the authentication.",
        "example": "FO-XXXX"
        "required
      },
      "client-id": {
        "type": "string",
        "description": "The client ID for the OAuth service.",
        "example": "my-client-id"
      },
      "site-external-id": {
        "type": "string",
        "description": "Datanumia's external identifier for the site. Please provide this input **if the used JWT doesn't provide site-external-id**",
      },
      "person-external-id": {
        "type": "string",
        "description": "Datanumia's external identifier for a person. Please provide this input **if the used JWT doesn't provide person-external-id**"
      }
    },
    "required": ["token", "offer-family", "client-id"]
  }
  ```
</Expandable>

***

### Outputs

<ParamField body="authenticationError" type="object">
  An error occurred during the authentication process.
  Refer to the **Error Handling** section for more information about the different error types.

  <Expandable title="properties">
    <ParamField path="code" type="string" required>
      A code specific to a type of error.

      Possible values:

      * `MISSING_DATA`
      * `SERVER_ERROR`
      * `INVALID_JWT`
    </ParamField>

    <ParamField path="description" type="string" required>
      A human-readable description providing details about the error that occurred.
    </ParamField>

    <ParamField path="cause" type="string">
      Additional information about the error.
    </ParamField>
  </Expandable>
</ParamField>

<Expandable title="json_schema">
  ```json json_schema theme={null}
  {
    "type": "object",
    "properties": {
      "authenticationError": {
        "type": "object",
        "description": "An error occurred in the authentication process. Please reach to the \"Error handling\" section to get more information on the differents errors.",
        "properties": {
          "code": { type: "string", description: "A code specific to a type of error. Can take the following values: `MISSING_DATA`, `SERVER_ERROR`, `INVALID_JWT`." },
          "description": { type: "string", description: "A human readable description that give details about the occurred error." },
          "cause": { type: "string", description: "Some more informations."}
        },
        "required": ["code", "description"]
      },
    }
  }
  ```
</Expandable>

***

### CSS Variables

No customization is available for this web component given that it does not have a human-machine interface (HMI).

***

### Error handling

As specified in the Output section, the errors can have multiple code where each code as an associated meaning :

* `MISSING_DATA`: The input data or the JWT doesn't fit the requirements. Please check the description to get more informations on what's going on and don't hesitate to visit the [Authenticate using JWT](/docs/DeveloperTools/HomeInteface/04-security#authenticate-using-jwt)
  section if needed.
* `SERVER_ERROR`: An error occurred on the server-side.
* `INVALID_JWT`: The JWT is malformed. Please verify that the passed JWT respects all the format requirements.