Máquina para máquina: Autenticação com Logto

nota:

Este guia assume que você criou um Aplicativo do tipo "Machine-to-machine" no Console de Administração.

Introdução

Máquina para máquina (M2M) é uma prática comum para autenticar quando você tem um aplicativo (não um usuário) que precisa se comunicar diretamente com recursos (geralmente, usando um app M2M não requer interação do usuário, então não possui interface). Por exemplo, um serviço de API que atualiza dados personalizados de usuários no Logto, um serviço de estatísticas que busca pedidos diários, etc.

Como o Logto utiliza o controle de acesso baseado em papel (RBAC) como sua política de controle de acesso, atribuir papéis M2M aos apps M2M é necessário para proteger sua API que precisa de comunicação direta entre serviços.

info:

Para conhecer nosso RBAC atual e a diferença entre papel de usuário e papel M2M, veja Configurar papéis globais para saber mais.

Existem dois casos de uso comuns para aplicativos máquina para máquina no Logto:

1. Acessar a Logto Management API: Neste caso, você precisa atribuir um papel M2M que inclua a permissão all da Logto Management API integrada ao seu app M2M.
2. Acessar seu recurso de API: Neste caso, você precisa atribuir papéis M2M que incluam permissões dos seus recursos de API ao seu app M2M.

Durante o processo de criação de um aplicativo M2M, você será direcionado para uma página onde pode atribuir papéis M2M (M2M roles) aos seus aplicativos:

Ou você também pode atribuir esses papéis na página de detalhes do aplicativo M2M quando já tiver um aplicativo M2M criado:

Agora, vamos passar pelo processo de ponta a ponta. Para maior clareza, vamos separar os passos para acessar a Logto Management API e outros recursos de API. E assumimos que você já criou um app M2M no Logto.

Buscar um token de acesso

Noções básicas sobre solicitação de token de acesso

O aplicativo M2M faz uma solicitação POST ao endpoint de token para obter um token de acesso, adicionando os seguintes parâmetros usando o formato application/x-www-form-urlencoded no corpo da entidade da solicitação HTTP:

• grant_type: Deve ser definido como client_credentials
• resource: O recurso que você deseja acessar
• scope: O escopo da solicitação de acesso

Você também precisa incluir as credenciais do seu aplicativo M2M no cabeçalho da solicitação para que o endpoint de token autentique seu aplicativo M2M.

Isso é alcançado incluindo as credenciais do aplicativo na forma de autenticação básica (Basic authentication) no cabeçalho de Authorization da solicitação, onde o nome de usuário é o App ID e a senha é o App Secret.

Você pode encontrar o App ID e o App Secret na página de detalhes do seu aplicativo M2M:

Um exemplo de solicitação de token de acesso é:

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

Solicitar um token de acesso

nota:

Na demonstração a seguir, substitua https://your.logto.endpoint pelo endpoint Logto que você está utilizando. Para Logto Cloud, será https://{your-tenant-id}.logto.app.

Para Logto Management API

O Logto fornece um recurso interno chamado “Logto Management API”, que é um recurso somente leitura com a permissão all para acessar a Logto Management API. Você pode vê-lo na sua lista de recursos de API. O indicador de recurso da API segue o padrão https://{your-tenant-id}.logto.app/api , e este será o valor do recurso utilizado no corpo da solicitação do token de acesso.

Antes de acessar a Logto Management API, certifique-se de que seu aplicativo M2M foi atribuído com papéis M2M que incluam a permissão all deste recurso interno “Logto Management API”.

info:

O Logto também fornece um papel M2M pré-configurado chamado “Logto Management API access” para novos tenants criados, ao qual já foi atribuída a permissão all do recurso Logto Management API. Você pode usá-lo diretamente sem precisar configurar permissões manualmente. Este papel pré-configurado também pode ser editado e excluído conforme necessário.

Agora, reúna tudo o que vimos e envie a solicitação:

info:

Desde a versão v1.30.1, o Logto oferece um SDK oficial Node.js @logto/api para ajudar você a interagir facilmente com a Logto Management API.

Node.js com `@logto/api` SDK

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('Token de acesso:', value);

// Ou você pode até mesmo pular a obtenção do token de acesso e fazer chamadas de API diretamente
const response = await apiClient.GET('/api/users');
console.log(response.data);

Self-hosted / OSS

Usuários OSS devem usar default como o tenant ID, e também fornecer as configurações baseUrl e 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'; // Substitua pelo seu 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(),
  });
};

cuidado:

Para usuários do Logto Cloud: ao interagir com a Logto Management API, você não pode usar domínio personalizado, utilize o endpoint padrão do Logto https://{your_tenant_id}.logto.app/oidc/token para obter tokens de acesso.

Resposta do token de acesso (Access token response)

Um corpo de resposta de acesso bem-sucedido seria assim:

{
  "access_token": "eyJhbG...2g", // Use este token para acessar a Logto Management API
  "expires_in": 3600, // Expiração do token em segundos
  "token_type": "Bearer", // Tipo de autenticação para sua requisição ao usar o token de acesso
  "scope": "all" // escopo `all` para Logto Management API
}

nota:

O Logto atualmente não suporta o aplicativo M2M para representar um usuário. O sub no payload do token de acesso será o ID do aplicativo.

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'

Lembre-se de substituir os valores reais pelos seus próprios.

cuidado:

Para usuários do Logto Cloud: ao interagir com a Logto Management API, você não pode usar domínio personalizado, utilize o endpoint padrão do Logto https://{your_tenant_id}.logto.app/oidc/token para obter tokens de acesso.

Resposta do token de acesso (Access token response)

Um corpo de resposta de acesso bem-sucedido seria assim:

{
  "access_token": "eyJhbG...2g", // Use este token para acessar a Logto Management API
  "expires_in": 3600, // Expiração do token em segundos
  "token_type": "Bearer", // Tipo de autenticação para sua requisição ao usar o token de acesso
  "scope": "all" // escopo `all` para Logto Management API
}

nota:

O Logto atualmente não suporta o aplicativo M2M para representar um usuário. O sub no payload do token de acesso será o ID do aplicativo.

Para seu recurso de API

Na sua lista de Recursos de API, encontre o identificador da API que o app precisa acessar. Se você ainda não adicionou o Recurso de API no Logto ou não sabe o que é um Recurso de API, veja Autorização.

Suponha que temos as permissões read:products e write:products sob este recurso de API “Online Shopping”.

Antes de acessar seu recurso de API, certifique-se de que seu app M2M foi atribuído com papéis M2M que incluam permissões do seu recurso de API.

Agora, reúna tudo o que temos e envie a solicitação:

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'

Resposta do token de acesso

Um corpo de resposta de acesso bem-sucedido seria assim:

{
  "access_token": "eyJhbG...2g", // Use este token para acessar a Logto Management API
  "expires_in": 3600, // Expiração do token em segundos
  "token_type": "Bearer", // Tipo de autenticação para sua solicitação ao usar o token de acesso
  "scope": "all" // escopo `all` para Logto Management API
}

nota:

O Logto atualmente não suporta o aplicativo M2M para representar um usuário. O sub no payload do token de acesso será o ID do aplicativo.

Acessar recurso usando token de acesso

Você pode notar que a resposta do token possui um campo token_type, que é fixado como Bearer.

Portanto, você deve colocar o token de acesso no campo Authorization dos cabeçalhos HTTP com o formato Bearer (Bearer YOUR_TOKEN) ao interagir com seu servidor de recurso de API.

Interagir com Logto Management API

Node.js com `@logto/api` SDK

Com o SDK @logto/api, você pode interagir diretamente com qualquer Management API usando o trecho de código abaixo. O token de acesso (Access token) é armazenado em cache internamente e atualizado automaticamente se necessário.

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

Você pode notar que a resposta do token possui um campo token_type, que é fixado como Bearer.

Portanto, você deve colocar o token de acesso no campo Authorization dos cabeçalhos HTTP com o formato Bearer (Bearer YOUR_TOKEN) ao interagir com seu servidor de recurso de API.

const logtoEndpoint = 'https://your.logto.endpoint'; // Substitua pelo seu endpoint Logto
const accessToken = 'eyJhb...2g'; // Token de acesso (Access Token)

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

cURL

Você pode notar que a resposta do token possui um campo token_type, que é fixado como Bearer.

Portanto, você deve colocar o token de acesso no campo Authorization dos cabeçalhos HTTP com o formato Bearer (Bearer YOUR_TOKEN) ao interagir com seu servidor de recurso de API.

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

Lembre-se de substituir os valores reais pelos seus próprios. O valor após Bearer deve ser o token de acesso (Access token) (JWT) que você recebeu.

Interagir com seu recurso de API

Usando o token de acesso solicitado com o recurso de API https://shopping.api para obter todos os produtos na API de compras:

Node.js

const apiEndpoint = 'https://your.api.endpoint';
const accessToken = 'eyJhb...2g'; // Token de acesso

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 # Token de acesso

Autorização (Authorization)

Se você está protegendo seus próprios Recursos de API além da Logto Management API, você precisa implementar a lógica de autorização em seu serviço de API para verificar o token de acesso e checar se o app M2M possui as permissões necessárias para acessar o recurso.

Para mais detalhes, veja Autorização e Validar tokens de acesso.