Machine à machine : Authentification avec Logto

remarque:

Ce guide suppose que vous avez créé une Application de type "Machine-to-machine" dans la Console d'administration.

Introduction

Le mode machine à machine (M2M) est une pratique courante pour l'authentification lorsque vous avez une application (et non un utilisateur) qui doit communiquer directement avec des ressources (généralement, l'utilisation d'une application M2M ne nécessite pas d'interactions utilisateur, donc il n'y a pas d'interface utilisateur). Par exemple, un service API qui met à jour les données personnalisées des utilisateurs dans Logto, un service de statistiques qui récupère les commandes quotidiennes, etc.

Puisque Logto utilise le contrôle d’accès basé sur les rôles (RBAC) comme politique de contrôle d'accès, il est nécessaire d'attribuer des rôles M2M aux applications M2M pour protéger votre API nécessitant une communication directe entre services.

info:

Pour en savoir plus sur notre RBAC actuel et la différence entre le rôle utilisateur et le rôle M2M, consultez Configurer les rôles globaux pour plus d'informations.

Il existe deux cas d'utilisation courants des applications machine à machine dans Logto :

1. Accès à la Logto Management API : Dans ce cas, vous devez attribuer à votre application M2M un rôle M2M incluant la permission all de la Logto Management API intégrée.
2. Accès à votre ressource API : Dans ce cas, vous devez attribuer à votre application M2M des rôles M2M incluant des permissions provenant de vos ressources API.

Lors du processus de création d'une application M2M, vous serez dirigé vers une page où vous pourrez attribuer des rôles M2M à vos applications :

Vous pouvez également attribuer ces rôles sur la page de détails de l'application M2M lorsque vous avez déjà créé une application M2M :

Voyons maintenant le processus de bout en bout. Pour plus de clarté, nous séparerons les étapes pour accéder à la Logto Management API et aux autres ressources API. Et nous supposons que vous avez déjà créé une application M2M dans Logto.

Récupérer un jeton d’accès

Principes de base sur la requête de jeton d’accès

L'application M2M effectue une requête POST vers le point de terminaison de jeton pour récupérer un jeton d’accès (Access token) en ajoutant les paramètres suivants en utilisant le format application/x-www-form-urlencoded dans le corps de l'entité de la requête HTTP :

• grant_type : Doit être défini sur client_credentials
• resource : La ressource à laquelle vous souhaitez accéder
• scope : La portée de la requête d’accès

Vous devez également inclure les informations d'identification de votre application M2M dans l'en-tête de la requête pour que le point de terminaison de jeton puisse authentifier votre application M2M.

Cela est réalisé en incluant les informations d'identification de l'application dans le formulaire d' Authentification (Basic authentication) dans l'en-tête de la requête Authorization, où le nom d'utilisateur est l'ID de l'application et le mot de passe est le secret de l'application.

Vous pouvez trouver l'ID de l'application et le secret de l'application sur la page des détails de votre application M2M :

Un exemple de requête de jeton d’accès est :

POST /oidc/token HTTP/1.1
Host: your.logto.endpoint
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&resource=https://shopping.api
&scope=read:products write:products

Demander un jeton d’accès

remarque:

Dans la démonstration suivante, remplacez https://your.logto.endpoint par l’endpoint Logto que vous ciblez. Pour Logto Cloud, ce sera https://{your-tenant-id}.logto.app.

Pour Logto Management API

Logto fournit une ressource intégrée “Logto Management API”, il s'agit d'une ressource en lecture seule avec la permission all pour accéder à Logto Management API, vous pouvez la voir dans votre liste de ressources API. L’indicateur de ressource API suit le modèle https://{your-tenant-id}.logto.app/api , et ce sera la valeur de ressource à utiliser dans le corps de la requête de jeton d’accès.

Avant d’accéder à Logto Management API, assurez-vous que votre application M2M a été assignée à des rôles M2M incluant la permission all de cette ressource intégrée “Logto Management API”.

info:

Logto fournit également un rôle M2M préconfiguré “Logto Management API access” pour les nouveaux locataires créés, auquel la permission all de la ressource Logto Management API a déjà été attribuée. Vous pouvez l’utiliser directement sans configurer manuellement les permissions. Ce rôle préconfiguré peut également être modifié et supprimé selon les besoins.

Maintenant, rassemblez tout ce que nous avons et envoyez la requête :

info:

Depuis la version v1.30.1, Logto propose un SDK officiel Node.js @logto/api pour vous aider à interagir facilement avec Logto Management API.

Node.js avec le SDK `@logto/api`

Logto Cloud

import { createManagementApi } from '@logto/api/management';

const { apiClient, clientCredentials } = createManagementApi('your-tenant-id', {
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
});

const { value } = await clientCredentials.getAccessToken();
console.log('Access token:', value);

// Ou vous pouvez même ignorer la récupération du jeton d’accès et effectuer directement des appels API
const response = await apiClient.GET('/api/users');
console.log(response.data);

Auto-hébergé / OSS

Les utilisateurs OSS doivent utiliser default comme identifiant de locataire, et également fournir les configurations baseUrl et apiIndicator.

const { apiClient, clientCredentials } = createManagementApi('default', {
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
  baseUrl: 'https://your.logto.endpoint',
  apiIndicator: 'https://default.logto.app/api',
});

Node.js

const logtoEndpoint = 'https://your.logto.endpoint'; // Remplacez par votre endpoint Logto
const tokenEndpoint = `${logtoEndpoint}/oidc/token`;
const applicationId = 'your-application-id';
const applicationSecret = 'your-application-secret';
const tenantId = 'your-tenant-id';

const fetchAccessToken = async () => {
  return await fetch(tokenEndpoint, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded',
      Authorization: `Basic ${Buffer.from(`${applicationId}:${applicationSecret}`).toString(
        'base64'
      )}`,
    },
    body: new URLSearchParams({
      grant_type: 'client_credentials',
      resource: `https://${tenantId}.logto.app/api`,
      scope: 'all',
    }).toString(),
  });
};

attention:

Pour les utilisateurs Logto Cloud : lorsque vous interagissez avec Logto Management API, vous ne pouvez pas utiliser de domaine personnalisé, utilisez l’endpoint Logto par défaut https://{your_tenant_id}.logto.app/oidc/token pour obtenir des jetons d’accès.

Réponse du jeton d’accès

Un corps de réponse d’accès réussi serait le suivant :

{
  "access_token": "eyJhbG...2g", // Utilisez ce jeton pour accéder à l’API de gestion Logto
  "expires_in": 3600, // Expiration du jeton en secondes
  "token_type": "Bearer", // Type d’authentification pour votre requête lors de l’utilisation du jeton d’accès
  "scope": "all" // portée `all` pour l’API de gestion Logto
}

remarque:

Logto ne prend pas actuellement en charge l'application M2M pour représenter un utilisateur. Le sub dans la charge utile du jeton d’accès sera l'ID de l'application.

cURL

curl --location \
  --request POST 'https://your.logto.endpoint' \
  --header 'Authorization: Basic ${your_auth_string}' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'resource=https://${tenantId}.logto.app/api' \
  --data-urlencode 'scope=all'

N’oubliez pas de remplacer les valeurs réelles par les vôtres.

attention:

Pour les utilisateurs Logto Cloud : lorsque vous interagissez avec Logto Management API, vous ne pouvez pas utiliser de domaine personnalisé, utilisez l’endpoint Logto par défaut https://{your_tenant_id}.logto.app/oidc/token pour obtenir des jetons d’accès.

Réponse du jeton d’accès

Un corps de réponse d’accès réussi serait le suivant :

{
  "access_token": "eyJhbG...2g", // Utilisez ce jeton pour accéder à l’API de gestion Logto
  "expires_in": 3600, // Expiration du jeton en secondes
  "token_type": "Bearer", // Type d’authentification pour votre requête lors de l’utilisation du jeton d’accès
  "scope": "all" // portée `all` pour l’API de gestion Logto
}

remarque:

Logto ne prend pas actuellement en charge l'application M2M pour représenter un utilisateur. Le sub dans la charge utile du jeton d’accès sera l'ID de l'application.

Pour votre ressource API

Dans votre liste de ressources API, trouvez l’identifiant de l’API que l’application doit accéder. Si vous n’avez pas ajouté la ressource API dans Logto ou si vous ne savez pas ce qu’est une ressource API, consultez Autorisation.

Supposons que nous ayons les permissions read:products et write:products sous cette ressource API “Online Shopping”.

Avant d’accéder à votre ressource API, assurez-vous que votre application M2M a été assignée à des rôles M2M incluant des permissions de votre ressource API.

Maintenant, rassemblez tout ce que nous avons et envoyez la requête :

Node.js

const logtoEndpoint = 'https://your.logto.endpoint';
const tokenEndpoint = `${logtoEndpoint}/oidc/token`;
const applicationId = 'your-application-id';
const applicationSecret = 'your-application-secret';

const fetchAccessToken = async () => {
  return await fetch(tokenEndpoint, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded',
      Authorization: `Basic ${Buffer.from(`${applicationId}:${applicationSecret}`).toString(
        'base64'
      )}`,
    },
    body: new URLSearchParams({
      grant_type: 'client_credentials',
      resource: 'https://shopping.api',
      scope: 'read:products write:products',
    }).toString(),
  });
};

cURL

curl --location \
  --request POST 'https://your.logto.endpoint/oidc/token' \
  --header 'Authorization: Basic ${your_auth_string}' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'resource=https://shopping.api' \
  --data-urlencode 'scope=read:products write:products'

Réponse du jeton d’accès

Un corps de réponse d’accès réussi ressemblera à ceci :

{
  "access_token": "eyJhbG...2g", // Utilisez ce jeton pour accéder à la Logto Management API
  "expires_in": 3600, // Expiration du jeton en secondes
  "token_type": "Bearer", // Type d’authentification pour votre requête lors de l’utilisation du jeton d’accès
  "scope": "all" // portée `all` pour Logto Management API
}

remarque:

Logto ne prend pas actuellement en charge l'application M2M pour représenter un utilisateur. Le sub dans la charge utile du jeton d’accès sera l'ID de l'application.

Accéder à une ressource en utilisant un jeton d’accès

Vous pouvez remarquer que la réponse du jeton a un champ token_type, qui est fixé à Bearer.

Ainsi, vous devez placer le jeton d’accès dans le champ Authorization des en-têtes HTTP avec le format Bearer (Bearer YOUR_TOKEN) lorsque vous interagissez avec votre serveur de ressource API.

Interagir avec Logto Management API

Node.js avec `@logto/api` SDK

Avec le SDK @logto/api, vous pouvez interagir directement avec n'importe quelle Management API en utilisant l'extrait de code ci-dessous. Le jeton d’accès (Access token) est mis en cache en interne et actualisé automatiquement si nécessaire.

import { createManagementApi } from '@logto/api/management';

const { apiClient } = createManagementApi('your-tenant-id', {
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
});

const response = await apiClient.GET('/api/applications');
console.log(response.data);

Node.js

Vous pouvez remarquer que la réponse du jeton a un champ token_type, qui est fixé à Bearer.

Ainsi, vous devez placer le jeton d’accès dans le champ Authorization des en-têtes HTTP avec le format Bearer (Bearer YOUR_TOKEN) lorsque vous interagissez avec votre serveur de ressource API.

const logtoEndpoint = 'https://your.logto.endpoint'; // Remplacez par votre endpoint Logto
const accessToken = 'eyJhb...2g'; // Jeton d’accès (Access token)

const fetchLogtoApplications = async () => {
  return await fetch(`${logtoEndpoint}/api/applications`, {
    method: 'GET',
    headers: {
      Authorization: `Bearer ${accessToken}`,
    },
  });
};

cURL

Vous pouvez remarquer que la réponse du jeton a un champ token_type, qui est fixé à Bearer.

Ainsi, vous devez placer le jeton d’accès dans le champ Authorization des en-têtes HTTP avec le format Bearer (Bearer YOUR_TOKEN) lorsque vous interagissez avec votre serveur de ressource API.

curl --location \
  --request GET 'https://your.logto.endpoint/api/applications' \
  --header 'Authorization: Bearer eyJhbG...2g'

N'oubliez pas de remplacer les valeurs réelles par les vôtres. La valeur après Bearer doit être le jeton d’accès (Access token) (JWT) que vous avez reçu.

Interagir avec votre ressource API

En utilisant le jeton d’accès demandé avec la ressource API https://shopping.api pour obtenir tous les produits dans l’API shopping :

Node.js

const apiEndpoint = 'https://your.api.endpoint';
const accessToken = 'eyJhb...2g'; // Jeton d’accès

const fetchProducts = async () => {
  return await fetch(`${apiEndpoint}/products`, {
    method: 'GET',
    headers: {
      Authorization: `Bearer ${accessToken}`,
    },
  });
};

cURL

curl --location \
  --request GET 'https://your.api.endpoint/products' \
  --header 'Authorization: Bearer eyJhbG...2 # Jeton d’accès

Autorisation

Si vous protégez vos propres ressources API autres que la Logto Management API, vous devez implémenter la logique d’autorisation dans votre service API pour vérifier le jeton d’accès et vérifier si l’application M2M dispose des permissions requises pour accéder à la ressource.

Pour plus de détails, consultez Autorisation et Valider les jetons d’accès.