Security - Datanumia Developer Portal

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.

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.

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>
  <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>
  <!-- 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>
  <!-- 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>
  <!-- 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.

<dtn-integration-requirements token="<datanumia-token>"></dtn-integration-requirements>

Inputs

string

required

The authentication token, which can be your own JWT token or a Datanumia token.

string

required

The offer family associated with the authentication.Example: FO-XXXX

string

required

The client ID for the OAuth service.Example: my-client-id

string

Datanumia’s external identifier for the site.Provide this value if the JWT token does not contain the site-external-id claim.

string

Datanumia’s external identifier for a person.Provide this value if the JWT token does not contain the person-external-id claim.

Show json_schema

json_schema

{
  "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"]
}

Outputs

object

An error occurred during the authentication process. Refer to the Error Handling section for more information about the different error types.

Show properties

string

required

A code specific to a type of error.Possible values:

MISSING_DATA
SERVER_ERROR
INVALID_JWT

string

required

A human-readable description providing details about the error that occurred.

string

Additional information about the error.

Show json_schema

json_schema

{
  "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"]
    },
  }
}

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 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.

Home Basic

​General information

​Means of authentication

​Recommandation

​Authenticate using JWT

​Integration requirements web component

​Description

​Usage

​Import the basis scripts

​Using your application JWT

​Using a HOME authentication token

​Inputs

​Outputs

​CSS Variables

​Error handling

General information

Means of authentication

Recommandation

Authenticate using JWT

Integration requirements web component

Description

Usage

Import the basis scripts

Using your application JWT

Using a HOME authentication token

Inputs

Outputs

CSS Variables

Error handling