Código de status HTTP 401 ou 403? Como diferem os erros de autenticação e autorização

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.

O que são códigos de status HTTP#

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:

200: Tudo está perfeito#

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.

301: Nós mudámos#

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.

404: Desculpa, não está aqui#

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.

401: Quem és tu?#

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.

403: Não é para ti#

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.

500: O forno está a pegar fogo#

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.

503: Temporariamente indisponível#

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).

Quando usar 401 Unauthorized?#

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?

1. 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.

2. 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.

3. 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).

4. Cabeçalho de autorização ausente ou malformado

   O cabeçalho de autorização é necessário, mas não é fornecido ou está incorretamente formatado.

5. 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.

6. 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.

Exemplo de resposta

Quando usar 403 Forbidden?#

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.

O que é AuthZ

O que é AuthN

Então, quais são os cenários comuns para usar 403 Forbidden?

1. 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".

2. 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.

3. 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.

4. 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."

5. 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.

6. 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.

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

Exemplo de Resposta:

Como posso resolver um erro 401 unauthorized#

Um erro 401 normalmente indica que a autenticação é necessária e falhou.

Verificar credenciais#

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.

Confirmar método de autenticação#

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.

Inspecionar a resposta do servidor#

Revê o corpo da resposta para detalhes do erro e observa o cabeçalho WWW-Authenticate para instruções de autenticação.

Verificar o pedido#

Confirma o endpoint, parâmetros de consulta, e host estão corretos e assegura-te de que o recurso que estás a acessar requer autenticação.

Verificar problemas de token#

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.

Como posso resolver um erro 403 forbidden#

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:

Verificar permissõ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.

Assegura-te de que a autenticação está correta#

Certifica-te de que estás autenticado corretamente (por exemplo, com um token ou credenciais válidas).

Verifica cuidadosamente o método de autenticação exigido pelo servidor.

Validar o recurso#

Confirma que o recurso solicitado existe e tens acesso a ele. Se estiveres a usar APIs, verifica os requisitos do endpoint na documentação.

Verificar bloqueio de IP ou localização#

Verifica se o teu endereço IP ou localização geográfica está restrito pelo servidor.

Rever políticas do servidor#

Certifica-te de que a ação solicitada não viola regras ou políticas do servidor (por exemplo, acessar um recurso somente leitura).

Inspecionar a resposta do servidor#

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).

1. 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."
2. 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."
3. 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."
4. 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.

Logto Cloud também fornece funcionalidades essenciais de autorização, incluindo Role-Based Access Control (RBAC), Organizações (Multi-Tenancy), e Custom Token Claims para atender a uma variedade de necessidades de autorização.