Skip to main content

Authentication

Every Lagertha user must be authenticated to use the Lagertha API.

An authenticated user is one who has a valid access_token.

All authenticated API calls must include the Authorization header with the value Bearer <access_token>.

To obtain the Lagertha access_token, there are two possibilities:

  • OpenId connect
  • Oauth

Method 1: OpenId Connect​

Authentication with the Lagertha API​

Send a POST request to authenticate the user and obtain an access_token.

curl -X POST https://<BASE_URL>:<PORT>/auth \
-H "Content-Type: application/json" \
-d '{
  "login": "<LOGIN_SUPER_ADMIN>",
  "password": "<PASSWORD_SUPER_ADMIN>",
  "application_id": 0,
  "fingerprint": "<UNIQUE_DEVICE_ID>"
}'

Response

{
  "access_token": "<access_token>",
  "token_type": "Bearer",
  "refresh_token": "<refresh_token>",
  "open_id": "<open_id>"
}

Store the access_token on the client side for later use.

Authentication with the Third-Party API​

Use the open_id to verify validity with the third-party API.

curl -X POST https://<BASE_URL>:<PORT>/oidc/verify \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <access_token_third_part_api>" \
-H "X-NONCE: <RANDOM_NONCE>" \
-H "X-FINGERPRINT: <UNIQUE_DEVICE_ID> \
-d '{
  "open_id_token": "<open_id>"
}'


Response

{
  "id": "string",
  "email": "string",
  "firstname": "string",
  "lastname": "string",
  "login": "string",
  "roles": [
    "string"
  ],
  "created_at": "string"
}

If the token is valid, you will receive the user information in return.

The third-party API can then log in the user and provide their own authentication token.

Method 2: OAuth​

Authentication with the Third-Party API​

The third-party API generates a unique code (state) and verifies with the Lagertha API if a user exists by providing their ID.

curl -X GET https://<BASE_URL>:<PORT>/oauth/token?client_id=<CLIENT_ID>&state=<STATE> \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <access_token_third_part_api>" \
-H "X-NONCE: <RANDOM_NONCE>" \
-H "X-FINGERPRINT: <UNIQUE_DEVICE_ID> \

In return, the third-party API retrieves an authorization_code.

{
  "authorization_code": "string"
}

The third-party API can then log in the user by providing their access token, the authorization_code, and the generated state.

Validation and Exchange of the Authorization Code​

The client can now exchange their authorization_code for an access_token from the Lagertha API.

curl -X POST https://<BASE_URL>:<PORT>/oauth/authorize \
-H "Content-Type: application/json" \
-d '{
  "authorization_code": "<AUTHORIZATION_CODE>",
  "state": "<STATE>",
  "application_id": 0,
  "fingerprint": "<UNIQUE_DEVICE_ID>"
}'

Response:

{
  "access_token": "<access_token>",
  "token_type": "Bearer",
  "refresh_token": "<refresh_token>",
  "open_id": "<open_id>"
}

Using the Refresh Token​

A refresh_token is also returned during the initial authentication. This token allows obtaining a new access_token without requiring a full re-authentication.

Renewing the Access Token​

To renew an access_token, send a POST request with the refresh_token.

curl -X POST https://<BASE_URL>:<PORT>/auth/refresh \
-H "Content-Type: application/json" \
-d '{
  "refresh_token": "<refresh_token>",
  "application_id": 0,
  "fingerprint": "<UNIQUE_DEVICE_ID>"
}'

Response:

{
  "access_token": "<new_access_token>",
  "token_type": "Bearer",
  "refresh_token": "<new_refresh_token>"
}

Store the new access_token and refresh_token on the client side for later use.

Two-Factor Authentication (MFA)​

To enhance security, the Lagertha API supports two-factor authentication (MFA). This adds an extra layer of security by requiring a verification code in addition to the password.

Enabling MFA​

To enable MFA, the user must generate a Time-based One-Time Password (TOTP) code.

curl -X GET https://<BASE_URL>:<PORT>/users/2fa/code \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <access_token>"

Réponse:

{
  "totp_url": "<totp_url>"
}

The user can use this URL to set up their authentication app (like Google Authenticator).

Verification and Activation of MFA​

The user verifies the TOTP code to activate MFA.

curl -X PUT https://<BASE_URL>:<PORT>/users/2fa/activate \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <access_token>" \
-d '{
  "code": "<TOTP_CODE>",
  "is_activate": true
}'

Authentication with MFA​

After enabling MFA, the user must provide the TOTP code at each login.

curl -X POST https://<BASE_URL>:<PORT>/auth \
-H "Content-Type: application/json" \
-d '{
  "login": "<LOGIN_SUPER_ADMIN>",
  "password": "<PASSWORD_SUPER_ADMIN>",
  "application_id": 0,
  "fingerprint": "<UNIQUE_DEVICE_ID>",
  "code_2fa": "<TOTP_CODE>"
}'

Response :

{
  "access_token": "<access_token>",
  "token_type": "Bearer",
  "refresh_token": "<refresh_token>",
  "open_id": "<open_id>"
}