Código de status HTTP 401 ou 403? Como diferem os erros de autenticação e autorização
401 Unauthorized indica que o cliente não está autenticado, exigindo credenciais válidas. 403 Forbidden significa que o cliente está autenticado, mas não tem as permissões necessárias para acessar o recurso.
GuamianProduct & Design
Pare de perder semanas com autenticação de utilizadores
Lance aplicações seguras mais rapidamente com o Logto. Integre a autenticação de utilizadores em minutos e concentre-se no seu produto principal.
Sempre que carregas uma página da web, fazes um pagamento ou fazes login numa aplicação, há uma conversa invisível a ocorrer entre o teu dispositivo e um servidor. É um pouco como enviar uma mensagem e esperar uma resposta—às vezes é um polegar para cima, às vezes é um educado 'tente novamente', e ocasionalmente, é um direto 'não.' Estas respostas, conhecidas como códigos de status HTTP, são os heróis incógnitos da internet, orientando silenciosamente o fluxo de comunicação e assegurando que tudo funcione sem problemas—ou pelo menos deixando-te saber quando não funciona.
Os códigos de status HTTP são como sinais numa conversa entre um cliente (como o teu navegador ou aplicação) e um servidor. Eles fornecem atualizações rápidas e claras sobre o que aconteceu quando fizeste um pedido—se tudo correu bem, se algo deu errado ou se uma ação adicional é necessária. Vamos pensar nisso como visitar uma padaria bem administrada:
Pedes um croissant, e o padeiro sorri, entrega-te, e diz: "Aqui está!" Isso é um HTTP 200 OK—o pedido foi bem-sucedido, e tudo correu como esperado.
O código de status HTTP 200 OK é um dos códigos mais utilizados, indicando que o pedido do cliente foi recebido, compreendido e processado com sucesso pelo servidor.
Chegas à tua padaria favorita, mas há um aviso dizendo: "Mudámos para o 123 New Street." Isso é um 301 Moved Permanently. O servidor informa o teu navegador para ir automaticamente para o novo endereço.
O código de status HTTP 301 Moved Permanently indica que o recurso solicitado foi movido permanentemente para um novo URL. Este código de status informa o cliente (por exemplo, um navegador ou cliente de API) para atualizar seus registos e usar o novo URL para futuros pedidos.
Pedes um scone de chocolate, e o padeiro diz: "Não fazemos isso aqui." Isso é um 404 Not Found—o recurso que procuras não existe no servidor.
O código de status HTTP 404 Not Found indica que o servidor não conseguiu encontrar o recurso solicitado. Esta resposta significa que o pedido do cliente era válido, mas o servidor não conseguiu localizar o recurso solicitado.
Tentas entrar no lounge VIP, mas o segurança para-te e diz: "Tens que mostrar o teu cartão de membro." Isso é um 401 Unauthorized—a autenticação é necessária antes que possas acessar o recurso.
O código de status HTTP 401 Unauthorized indica que o pedido do cliente não foi aplicado porque falta credenciais válidas de autenticação. O servidor requer que o cliente autentique-se para acessar o recurso solicitado.
Mostras o teu cartão de membro, mas o segurança diz: "Apenas membros platina podem entrar." Isso é um 403 Forbidden—estás autenticado, mas não tens as permissões necessárias para acessar o recurso.
O código de status HTTP 403 Forbidden indica que o servidor entende o pedido do cliente mas recusa-se a cumpri-lo porque o cliente não tem as permissões necessárias. Isso é diferente de um status 401 Unauthorized, já que o cliente está autenticado (ou o pedido não requer autenticação), mas o acesso ao recurso é explicitamente negado.
Fazes um pedido, mas de repente começa a sair fumaça da cozinha. O padeiro diz: "Não podemos cumprir o teu pedido; algo deu errado internamente." Isso é um 500 Internal Server Error—o servidor encontrou um problema inesperado.
O código de status HTTP 500 Internal Server Error indica que o servidor encontrou uma condição inesperada que impediu o cumprimento do pedido. É uma resposta de erro genérica e não fornece detalhes específicos sobre o que deu errado.
Visitas a padaria, mas há uma placa "Fechado para Manutenção". A padaria reabrirá mais tarde. Isso é um 503 Service Unavailable—o servidor está temporariamente incapaz de lidar com o teu pedido, muitas vezes devido a sobrecarga ou manutenção.
O código de status HTTP 503 Service Unavailable indica que o servidor está temporariamente incapaz de lidar com o pedido. Isso pode ser devido a sobrecarga do servidor, manutenção ou outras condições temporárias. Diferentemente de um 500 Internal Server Error, um 503 implica que o problema está previsto ser resolvido em breve.
Os códigos de status HTTP são fundamentais para manter uma comunicação eficiente entre clientes e servidores. Eles informam rapidamente os clientes se seus pedidos foram bem-sucedidos, falharam ou requerem ação adicional. Para desenvolvedores e profissionais de TI, entender esses códigos ajuda a depurar problemas, a projetar um melhor tratamento de erros e a melhorar a experiência geral do usuário.
Pensa neles como sinais profissionais e padronizados na conversa contínua da internet.
Neste artigo, quero focar nos erros 401 e 403, já que estão intimamente relacionados com autenticação (AuthN) e autorização (AuthZ).
O código de status HTTP 401 Unauthorized é usado quando o pedido do cliente requer autenticação, mas está ausente, inválida ou falhou. Ele informa o cliente de que precisam autenticar-se para acessar o recurso solicitado. A relação entre autenticação e o código de status 401 Unauthorized reside no papel da autenticação em determinar se um pedido pode prosseguir.
401 unauthorized deve incluir um cabeçalho WWW-Authenticate, fornecendo detalhes sobre como autenticar.
Portanto, quais são os cenários comuns para usar 401 Unauthorized?
Falta de autenticação
O pedido não inclui as credenciais de autenticação necessárias. Por exemplo: Um pedido para um endpoint de API protegido é feito sem um cabeçalho de Autorização.
Credenciais de autenticação inválidas
O cliente fornece credenciais, mas estão incorretas ou não correspondem ao que o servidor espera. Por exemplo, um usuário envia uma chave de API inválida ou um token malformado.
Token de autenticação expirado
O token de autenticação é válido, mas expirou, exigindo que o cliente reautentique. Por exemplo, um token JWT com uma data de expiração passada (exp claim).
Cabeçalho de autorização ausente ou malformado
O cabeçalho de autorização é necessário, mas não é fornecido ou está incorretamente formatado.
Esquema de autenticação não suportado
O servidor não suporta o método de autenticação fornecido pelo cliente. Por exemplo: O cliente envia um cabeçalho de autenticação Básica, mas o servidor só suporta tokens Bearer.
Sessão inválida ou revogação de token
A sessão do usuário foi invalidada, ou seu token foi revogado. Por exemplo: Um usuário faz logout, mas o mesmo token é usado para acessar um recurso protegido.
O código de status HTTP 403 Forbidden significa que o servidor entende o pedido e a identidade do cliente (se autenticado) mas nega o acesso devido a permissões insuficientes. Ele sinaliza claramente, "Não tens permissão para fazer isso", assegurando limites claros de acesso e reforçando políticas de segurança.
A distinção entre 401 Unauthorized e 403 Forbidden reside nos seus papéis dentro de contextos de autenticação e autorização.
A autorização é um mecanismo separado da autenticação. Enquanto a autenticação identifica quem és, a autorização determina se podes acessar recursos específicos e quais ações podes realizar neles.
Para verificar a diferença detalhada sobre AuthN e AuthZ, consulta os seguintes artigos.
Então, quais são os cenários comuns para usar 403 Forbidden?
Autenticado mas sem permissão
O cliente está logado ou autenticado, mas não tem as permissões ou papel exigido. Por exemplo, um usuário com papel de "visualizador" tenta excluir um arquivo, o que requer privilégios de "editor".
Acesso ao recurso restrito
O acesso ao recurso é intencionalmente restrito a usuários ou grupos específicos. Por exemplo: Um documento privado compartilhado com usuários específicos é acessado por alguém que não está na lista de acesso.
Bloqueio de IP ou geográfico
O endereço IP ou localização geográfica do cliente é bloqueado pelo servidor. Por exemplo: um usuário de uma região restrita tenta acessar um serviço que só opera em países específicos.
Ações bloqueadas por política
O cliente está a tentar uma ação proibida por políticas ou regras do lado do servidor. Por exemplo: um usuário tenta modificar um recurso que está marcado como "somente leitura."
Recursos estáticos bloqueados
O servidor nega acesso a arquivos ou diretórios estáticos específicos por razões de segurança.
Exemplo: Um usuário tenta acessar um arquivo .htaccess ou um arquivo de configuração do servidor.
Conta suspensa ou desativada
A conta do cliente está desativada ou bloqueada devido a violações ou inatividade. Por exemplo: Um usuário com uma conta suspensa tenta fazer login ou acessar recursos.
Ação requer permissões elevadas
A ação solicitada requer privilégios especiais (por exemplo, admin ou superusuário). Por exemplo: Um usuário padrão tenta acessar endpoints de somente admin.
Assegura-te de que o cabeçalho de Autorização está presente e corretamente formatado e verifica se as credenciais (chave de API, token ou senha) estão corretas e não expiraram. Inserir o nome de utilizador ou senha incorretos é uma das causas mais frequentes de um erro 401.
O servidor pode esperar um método de autenticação diferente do que está sendo fornecido. Isso pode acontecer se o cliente e o servidor não estão alinhados no protocolo de autenticação. Usa o método correto (por exemplo, Basic, Bearer, API Key) conforme especificado pelo servidor e verifica a sintaxe correta nos cabeçalhos.
Decodifica e inspeciona o token (por exemplo, com https://logto.io/jwt-decoder) para validade, expiração e claims e certifica-te de que o público (aud) do token corresponde aos requisitos da API.
Um erro 403 forbidden normalmente significa que o processo de autorização foi concluído, mas o acesso foi negado. Para resolver este erro, considera as seguintes condições:
Confirma que a tua conta, chave de API ou token tem as permissões necessárias para o recurso. Verifica se o recurso está restrito a papéis ou grupos específicos.
Examina o corpo da resposta para detalhes que expliquem o motivo do erro 403.
Um único pedido pode retornar os códigos de status 401 e 403#
Não, um único pedido HTTP não pode retornar simultaneamente os códigos de status 401 Unauthorized e 403 Forbidden porque uma resposta HTTP só pode incluir um código de status.
O uso prático dos códigos de erro 401 e 403 em autenticação e autorização#
No desenvolvimento moderno de aplicações, 401 Unauthorized e 403 Forbidden são dois códigos de status HTTP que os desenvolvedores encontram com frequência. Embora possam parecer semelhantes, seus significados e casos de uso são claramente diferentes. Para esclarecer suas diferenças, este artigo explora exemplos práticos desses códigos em cenários como autenticação, autorização, multi-tenancy e autenticação multifator (MFA).
Cenário de login: Um usuário tenta acessar uma página protegida sem fazer login ou fornecer credenciais válidas. O servidor responde e lança um erro 401 Unauthorized: "Precisas de fazer login ou fornecer credenciais válidas para acessar esta página."
Cenário de controle de acesso: O mesmo usuário faz login com sucesso, mas tenta acessar uma página de somente admin sem o papel de admin exigido. O servidor responde e lança um 403 Forbidden: "Estás logado, mas não tens permissão para acessar esta página."
Cenário de multi-tenant: O mesmo usuário faz login, mas pertence ao Tenant A e tenta acessar um recurso no Tenant B, onde não têm acesso. O servidor responde e lança um 403 Forbidden: "Estás autenticado, mas não tens permissão para acessar este recurso no Tenant B."
Cenário de MFA: Um usuário tenta fazer login, mas não concluiu a Autenticação Multifator (MFA) exigida. O servidor responde e lança um erro 401 Unauthorized: "A autenticação está incompleta. Por favor, conclua a MFA para prosseguir."
Usando Logto como um provedor de autenticação e autorização#
Logto é principalmente um provedor de autenticação, oferecendo métodos chave como login sem senha, email e senha, MFA, SSO Empresarial, e login social, todos baseados em protocolos de padrões abertos como OIDC, OAuth 2.0, e SAML.
