Pular para o conteúdo principal

Proteger recursos globais de API

Proteja APIs de todo o produto usando controle de acesso baseado em papel (RBAC) no Logto. Atribua papéis globais e permissões para controlar o acesso de todos os usuários e clientes em todo o seu aplicativo.

O que são recursos globais de API?​

Recursos globais de API são endpoints ou serviços em seu aplicativo que são acessíveis a todos os usuários, independentemente de organização ou locatário. Normalmente, são APIs públicas, serviços centrais do produto ou qualquer endpoint que não esteja vinculado a uma organização específica.

Casos de uso incluem

  • APIs públicas ou endpoints compartilhados entre sua base de usuários.
  • Microsserviços que não estão atrelados à multi-tenancy.
  • APIs centrais do aplicativo (por exemplo, /api/users, /api/products) usadas por todos os clientes.

O Logto permite proteger essas APIs usando OAuth 2.1, combinado com controle de acesso flexível baseado em papel.

Como funciona no Logto​

  • Recursos de API e permissões são registrados globalmente: Cada API que você deseja proteger é definida com um indicador de recurso único (URI) e um conjunto de permissões (escopos) que controlam o acesso.
  • O acesso é controlado por papéis globais: Você pode atribuir permissões a papéis, que então são atribuídos a usuários ou clientes.
  • Separado das permissões em nível de organização: Recursos globais de API não têm contexto de organização. No entanto, podem ser usados em conjunto com papéis de organização para fornecer uma camada adicional de contexto, se necessário. Para proteger APIs em nível de organização, veja Proteger recursos de API em nível de organização.
Recursos globais de API RBAC

Visão geral da implementação​

  1. Registre seu recurso de API e defina suas permissões no Logto.
  2. Defina papéis com as permissões necessárias para acessar a API.
  3. Atribua papéis a usuários ou clientes.
  4. Use fluxos de autorização OAuth 2.0 para obter tokens de acesso para a API (o parâmetro resource deve corresponder ao identificador da API registrada).
  5. Valide os tokens de acesso em sua API para aplicar as permissões.

Entendendo indicadores de recurso​

O Logto modela recursos de API de acordo com RFC 8707: Indicadores de Recurso para OAuth 2.0. Um indicador de recurso é um URI que identifica de forma única a API ou serviço de destino solicitado.

Pontos-chave

  • Indicadores de recurso devem ser URIs absolutos (por exemplo, https://api.example.com)
  • Sem componente de fragmento; evite usar query strings sempre que possível.
  • Indicadores de recurso permitem tokens restritos por público e suporte para arquiteturas multi-API.

Exemplo

  • Management API: https://my-tenant.logto.app/api
  • API global personalizada: https://api.yourapp.com

Fluxo de autorização: autenticando e protegendo sua API​

O fluxo abaixo se aplica tanto à autenticação interativa do usuário (navegador / aplicativo) quanto a cenários backend máquina para máquina (M2M).

Observe que o fluxo não inclui detalhes exaustivos sobre os parâmetros ou cabeçalhos necessários, mas foca nas etapas principais envolvidas. Continue lendo para ver como o fluxo funciona na prática.

Autenticação do usuário = navegador / aplicativo. M2M = serviço backend ou script usando credenciais de cliente.

nota:

O parâmetro resource deve corresponder exatamente ao identificador da API (indicador de recurso) que você registrou no Logto.

Etapas de implementação​

Registre seus recursos de API​

  1. Vá para Console → Recursos de API.
  2. Crie um novo recurso de API (por exemplo, https://api.yourapp.com/org) e defina suas permissões (escopos).

Para etapas completas de configuração, veja Definir recursos de API com permissões.

Configure papéis globais​

  1. Vá para Console → Papéis.
  2. Crie papéis que correspondam às permissões da sua API (por exemplo, read:products, write:products).
  3. Atribua esses papéis a usuários ou clientes que precisam de acesso à API.

Para etapas completas de configuração, veja Usar papéis globais.

Obtenha tokens de acesso para recursos globais de API​

Antes de acessar um recurso global de API, seu cliente deve obter um token de acesso. O Logto emite JSON Web Tokens (JWTs) como tokens de acesso para recursos globais de API. Isso normalmente é feito usando o fluxo de código de autorização OAuth 2.0, fluxo de refresh token ou o fluxo de client credentials.

Fluxo de código de autorização ou refresh token​

Todos os SDKs oficiais do Logto suportam a obtenção de tokens de acesso para recursos globais de API usando o fluxo de refresh token nativamente. Uma biblioteca padrão de cliente OAuth 2.0 / OIDC também pode ser usada para implementar esse fluxo.

Ao inicializar o cliente Logto, adicione o indicador de recurso ao parâmetro resources (array), depois adicione as permissões desejadas (escopos) ao parâmetro scopes.

Uma vez que o usuário esteja autenticado, passe o indicador de recurso no parâmetro resource ou parâmetro de nome similar ao solicitar o token de acesso (por exemplo, ao chamar getAccessToken()).

Para detalhes sobre cada SDK, veja os Comece rápido.

Fluxo de client credentials​

Para cenários máquina para máquina (M2M), você pode usar o fluxo de client credentials para obter um token de acesso para seu recurso global de API. Fazendo uma requisição POST para o endpoint /oidc/token do Logto, você pode solicitar um token de acesso usando seu client ID e secret.

Há dois parâmetros principais a serem incluídos na requisição:

  • resource: O URI indicador de recurso da API que você deseja acessar (por exemplo, https://api.yourapp.com).
  • scope: As permissões que você deseja solicitar para a API (por exemplo, read:products write:products).

Aqui está um exemplo não normativo da solicitação de token usando o tipo de concessão client credentials:

POST /oidc/token HTTP/1.1
Host: your.logto.endpoint
Content-Type: application/x-www-form-urlencoded
Authorization: Basic base64(client_id:client_secret)

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

Validando tokens de acesso JWT em sua API​

Os JWTs emitidos pelo Logto contêm reivindicações que sua API pode usar para aplicar autorização.

Quando sua API recebe uma requisição com um token de acesso emitido pelo Logto, você deve:

  • Verificar a assinatura do token (usando os JWKs do Logto).
  • Confirmar que o token não está expirado (reivindicação exp).
  • Verificar se o iss (emissor) corresponde ao endpoint do seu Logto.
  • Garantir que o aud (público) corresponde ao identificador do recurso de API que você registrou (por exemplo, https://api.yourapp.com).
  • Separar a reivindicação scope (separada por espaço) e verificar as permissões necessárias.

Para guias passo a passo e específicos por linguagem, veja Como validar tokens de acesso.

Opcional: Lidar com alteração de permissão do usuário​

info:

👷 Trabalho em andamento. 🚧

Boas práticas e dicas de segurança​

  • Mantenha as permissões orientadas ao negócio: Use nomes claros que correspondam a ações reais.
  • Mantenha a expiração do token curta: Reduz o risco caso um token seja vazado.
  • Limite os escopos concedidos: Dê aos tokens apenas as permissões realmente necessárias.
  • Use restrição de público: Sempre verifique a reivindicação aud para evitar uso indevido.

Perguntas frequentes​

E se meu cliente não suportar o parâmetro resource?​

Defina um recurso de API padrão no Console do Logto. Os tokens terão esse público por padrão quando nenhum parâmetro resource for especificado na solicitação de token.

Por que recebo 401 Não autorizado da minha API?​

Verifique os seguintes problemas comuns:

  • Assinatura do token: Verifique se seu backend está buscando os JWKs corretos do Logto
  • Expiração do token: Certifique-se de que o token não expirou (reivindicação exp)
  • Público: Confirme se a reivindicação aud corresponde ao indicador de recurso de API registrado
  • Escopos necessários: Verifique se o token contém as permissões necessárias na reivindicação scope

Como testar sem um cliente completo?​

Use um token de acesso pessoal para simular chamadas autenticadas. Isso permite testar seus endpoints de API sem implementar um fluxo OAuth completo em seu aplicativo cliente.

Leitura adicional​

Como validar tokens de acesso

RBAC na prática: Implementando autorização segura para seu aplicativo

 Personalizando reivindicações de token RFC 8707: Indicadores de Recurso