Autenticação na REST API do Magento 2: admin, customer e integration

Toda requisição à REST API do Magento 2 roda como alguém. Pode ser um usuário admin, um cliente, uma integration ou um guest, e essa identidade decide quais rotas a requisição pode chamar. Escolher o método errado é comum. Um exemplo típico é um conector de ERP que faz login como um usuário admin de verdade, com a senha desse usuário guardada em texto puro em outro sistema. Este artigo explica as opções no Magento Open Source e no Adobe Commerce 2.4.8 e quando cada uma serve.

As quatro formas de autenticar

Método	Quem representa	Uso típico
Admin token	Um usuário admin	Scripts de vida curta, testes manuais
Customer token	Um cliente da storefront	Apps mobile, frontends customizados
Integration	Uma integration nomeada com ACL própria	ERPs, PIMs, marketplaces, qualquer conexão entre sistemas
Session	O admin ou cliente logado pelo navegador	JavaScript nas próprias páginas do Magento chamando REST

As rotas declaram o que aceitam pelo node <resources> no webapi.xml. Um recurso de ACL como Magento_Catalog::products exige um admin ou integration com essa permissão. O recurso especial self exige um cliente, e anonymous aceita qualquer um. Como montar essas rotas está no guia de endpoint REST customizado.

Admin tokens

Um admin token é pedido com usuário e senha:

curl -s -X POST https://example.test/rest/V1/integration/admin/token \
  -H "Content-Type: application/json" \
  -d '{"username": "api.user", "password": "secret"}'

A resposta é uma string de token. Envie nas requisições seguintes como Authorization: Bearer <token>. Desde a 2.4.4 esses tokens são JWTs por padrão.

Na 2.4.x, o Magento_TwoFactorAuth vem habilitado de fábrica e muda esse fluxo. Com o 2FA ativo, o endpoint simples de admin token se recusa a emitir um token e você precisa usar um endpoint específico do provider, por exemplo para o Google Authenticator:

curl -s -X POST https://example.test/rest/V1/tfa/provider/google/authenticate \
  -H "Content-Type: application/json" \
  -d '{"username": "api.user", "password": "secret", "otp": "123456"}'

Isso funciona para uma pessoa rodando um script. Não funciona para um sistema sem supervisão, porque não há ninguém para digitar o código. Esse é o principal motivo de conexões entre máquinas deverem usar integrations e não contas de admin. Mais sobre o módulo de 2FA no artigo sobre autenticação em dois fatores no admin.

Admin tokens expiram. A validade é definida em Stores > Configuration > Services > OAuth > Access Token Expiration, com padrão de 4 horas para admins. O token tem as mesmas permissões de ACL do role do usuário admin, então um token de um administrador completo pode fazer tudo que a API permite.

Customer tokens

Customer tokens funcionam do mesmo jeito, com outro endpoint:

curl -s -X POST https://example.test/rest/V1/integration/customer/token \
  -H "Content-Type: application/json" \
  -d '{"username": "[email protected]", "password": "secret"}'

curl -s -H "Authorization: Bearer $CUSTOMER_TOKEN" \
  https://example.test/rest/V1/customers/me

Um customer token só pode chamar rotas com o recurso self ou anonymous. A validade padrão é de 1 hora, definida na mesma seção de configuração. Storefronts que precisam de sessões mais longas devem renovar o token fazendo login de novo ou guardar a sessão em outro lugar. Não suba a validade para semanas só por isso.

No admin, a página de edição do cliente tem um botão Force Sign-In que revoga os tokens do cliente. Isso é útil quando uma conta é comprometida. Para storefronts headless, o GraphQL tem suas próprias mutations de token. Elas estão no artigo sobre autenticação de cliente no GraphQL.

Os endpoints de token são protegidos por authentication locks. Depois de um número configurável de tentativas falhas a conta é bloqueada por um tempo. As configurações ficam na seção de configuração de OAuth, em Authentication Locks. Mantenha habilitado, porque os endpoints de token são alvo natural de tentativas de adivinhar senha.

Integrations

Uma integration é a ferramenta certa para qualquer sistema externo. Você cria em System > Extensions > Integrations, dá um nome e um e-mail e escolhe os recursos de ACL exatos de que ela precisa na aba API. Quando você ativa, o Magento gera quatro valores: consumer key, consumer secret, access token e access token secret.

Vantagens sobre uma conta de admin:

• As permissões ficam limitadas ao que a integration precisa. Uma sincronização de estoque não precisa de acesso a clientes.
• Ela não está ligada a uma pessoa. Troca de equipe e 2FA não a quebram.
• Os tokens não expiram, e você pode rotacioná-los com Reauthorize quando um secret vaza.
• Logs e auditorias mostram uma integration nomeada, não um login de admin compartilhado.

Assinatura OAuth vs bearer tokens

O jeito previsto de usar as credenciais de uma integration é o OAuth 1.0a: cada requisição é assinada com consumer key, consumer secret, access token e access token secret. A maioria das bibliotecas de cliente HTTP tem um plugin de OAuth 1.0a, e ferramentas como o Postman suportam direto.

Desde a 2.4.4, usar só o access token da integration como bearer token vem desabilitado por padrão. Muitos conectores antigos dependem disso e começam a retornar erros 401 depois de um upgrade. Você pode religar em Stores > Configuration > Services > OAuth > Consumer Settings com a opção que permite usar OAuth access tokens como bearer tokens independentes, ou pela CLI:

bin/magento config:set oauth/consumer/enable_integration_as_bearer 1
bin/magento cache:clean config

É uma troca de vantagens. Um bearer token é mais simples de usar, mas qualquer um que o veja pode reutilizá-lo. Requisições assinadas carregam um timestamp e um nonce, então uma requisição capturada não pode simplesmente ser enviada de novo mais tarde. Se o sistema externo suporta OAuth 1.0a, use e deixe a configuração desligada. Se você habilitar, garanta que o token trafegue só por HTTPS e seja guardado como secret do outro lado.

Integrations no código

Um módulo também pode declarar uma integration em etc/integration/config.xml e sua ACL em etc/integration/api.xml. O Magento a cria durante o setup:upgrade, e um admin ainda precisa ativá-la para gerar os tokens. Isso é útil quando você entrega um módulo conector e quer que a integration e suas permissões sejam versionadas junto com o código.

Autenticação por sessão

Quando o JavaScript da própria storefront ou do admin do Magento chama a REST API, a requisição pode usar o cookie de sessão existente. É assim que algumas funcionalidades do checkout e de customer do core falam com o REST. Só faz sentido para código rodando no mesmo domínio dentro de páginas do Magento. Clientes externos nunca devem tentar reaproveitar cookies de sessão.

Sabendo quem está chamando dentro do seu código

Num método de serviço atrás de uma rota REST, injete Magento\Authorization\Model\UserContextInterface para descobrir quem fez a requisição:

<?php
declare(strict_types=1);

namespace Acme\Notice\Model;

use Magento\Authorization\Model\UserContextInterface;
use Magento\Framework\Exception\AuthorizationException;

class CallerGuard
{
    public function __construct(
        private readonly UserContextInterface $userContext
    ) {
    }

    public function requireCustomerId(): int
    {
        if ($this->userContext->getUserType() !== UserContextInterface::USER_TYPE_CUSTOMER) {
            throw new AuthorizationException(__('This action is only available to customers.'));
        }
        return (int) $this->userContext->getUserId();
    }
}

As constantes de tipo de usuário cobrem integrations, admins, clientes e guests. Para rotas de cliente, prefira o recurso self com um parâmetro %customer_id% forçado no webapi.xml. Use o user context quando a lógica depende de quem chama de formas que a configuração da rota não consegue expressar.

Padrões seguros

1. Crie uma integration por sistema externo, cada uma com a menor ACL de que precisa.
2. Prefira a assinatura OAuth 1.0a. Habilite bearer tokens de integration só quando o cliente não consegue assinar, e documente essa decisão.
3. Nunca dê a um terceiro um usuário e senha de admin de verdade.
4. Mantenha o 2FA habilitado para pessoas. Não o desabilite para fazer um script de API funcionar.
5. Mantenha curta a validade dos customer tokens e use Force Sign-In quando uma conta estiver em risco.
6. Rotacione os tokens de integration quando alguém com acesso sair, ou quando suspeitar de vazamento.

Para uma visão mais ampla de como conectar o Magento a sistemas de back office, veja o artigo sobre padrões de integração com ERP.

FAQ

Por que minha integration começou a retornar 401 depois de atualizar para a 2.4.4 ou posterior?

Desde a 2.4.4, os access tokens de integration não podem ser usados como bearer tokens independentes, a menos que você habilite essa opção nas consumer settings do OAuth. Habilite a opção ou troque o cliente para requisições assinadas com OAuth 1.0a.

Por que o endpoint de admin token falha quando o 2FA está habilitado?

Com o Magento_TwoFactorAuth ativo, os admin tokens precisam ser pedidos por um endpoint do provider que inclui o código de uso único, como /V1/tfa/provider/google/authenticate. Para sistemas sem supervisão, use uma integration.

Quanto tempo duram os tokens de admin e de customer?

Por padrão, 4 horas para admin tokens e 1 hora para customer tokens. Os dois são configuráveis em Stores, Configuration, Services, OAuth, Access Token Expiration.

Os tokens de integration expiram?

Não. Eles continuam válidos até a integration ser reautorizada ou apagada, e é por isso que precisam ser guardados como secrets.

Atendo como freelancer em Magento e Adobe Commerce. Se você precisa de ajuda para conectar um sistema externo ao Magento com segurança, fale comigo.