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 se você tem um aplicativo (não usuário) que precisa se comunicar diretamente com recursos (geralmente, usando um aplicativo M2M não precisa de interações do usuário, então não tem interface de usuário). Por exemplo, um serviço de API que atualiza dados personalizados dos usuários no Logto, um serviço de estatísticas que coleta pedidos diários, etc.

Como o Logto usa RBAC como sua política de controle de acesso, atribuir papéis M2M aos aplicativos M2M é necessário para proteger sua API que precisa de comunicação direta de serviço.

info

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

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

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

Durante o processo de criação do aplicativo M2M, você será direcionado para uma página onde pode atribuir papéis M2M 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 percorrer o processo de ponta a ponta. Para clareza, separaremos os passos para acessar Logto Management API e outros recursos de API. E assumimos que você já criou um aplicativo M2M no Logto.

Obter 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á direcionando. Para Logto Cloud, será https://{your-tenant-id}.logto.app.

Para Logto Management API

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

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

info

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

Agora, componha tudo o que temos e envie a solicitação:

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(),
  });
};

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: quando você estiver interagindo com Logto Management API, não pode usar domínio personalizado, use o endpoint padrão do Logto https://{your_tenant_id}.logto.app/oidc/token para conceder tokens de acesso.

Para seu recurso de API

Na sua lista de Recursos de API, encontre o identificador de API que o aplicativo 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 Recurso de API.

Assuma que temos 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 aplicativo M2M foi atribuído com papéis M2M que incluem permissões do seu recurso de API.

Agora, componha 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 o 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

Usando o token de acesso solicitado com o recurso de API de gerenciamento Logto embutido https://[your-tenant-id].logto.app/api para obter todos os aplicativos no Logto:

Node.js

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

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

cURL

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

Autenticação (Authentication)

Se você estiver protegendo seus próprios Recursos de API além do Logto Management API, lembre-se de implementar a autenticação para seu recurso. Veja Proteger sua API para detalhes.