Código de status HTTP 401 ou 403? Como erros de autenticação e autorização diferem
401 Unauthorized indica que o cliente não está autenticado, requerendo 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 usuários
Lance aplicativos seguros mais rapidamente com o Logto. Integre a autenticação de usuários em minutos e concentre-se no seu produto principal.
Toda vez que você carrega uma página da web, faz um pagamento ou faz login em um aplicativo, há uma conversa invisível acontecendo entre o seu dispositivo e um servidor. É um pouco como enviar uma mensagem e esperar uma resposta—às vezes é um sinal de positivo, às vezes é um educado 'tente novamente,' e ocasionalmente, é um direto 'não.' Essas respostas, conhecidas como códigos de status HTTP, são os heróis desconhecidos da internet, guiando silenciosamente o fluxo de comunicação e garantindo que tudo funcione de maneira suave—ou pelo menos deixando você saber quando não está.
Códigos de status HTTP são como sinais em uma conversa entre um cliente (como seu navegador ou aplicativo) e um servidor. Eles fornecem atualizações rápidas e claras sobre o que aconteceu quando você fez uma solicitação—se tudo correu bem, se algo deu errado ou se é necessária uma ação adicional. Vamos pensar nisso como visitar uma padaria bem organizada:
Você pede um croissant, e o padeiro sorri, entrega e diz, "Aqui está!" Isso é um HTTP 200 OK—a solicitação foi bem-sucedida, e tudo funcionou como esperado.
O código de status HTTP 200 OK é um dos códigos mais comumente usados, indicando que a solicitação do cliente foi recebida, entendida e processada com sucesso pelo servidor.
Você chega à sua padaria favorita, mas há um aviso dizendo, "Nós mudamos para 123 New Street." Isso é um 301 Moved Permanently. O servidor diz ao seu 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 ao cliente (por exemplo, um navegador ou cliente de API) para atualizar seus registros e usar o novo URL para futuras solicitações.
Você pede um scone de chocolate, e o padeiro diz, "Nós não fazemos esses aqui." Isso é um 404 Not Found—o recurso que você está procurando 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 a solicitação do cliente era válida, mas o servidor não conseguiu localizar o recurso pedido.
Você tenta entrar no lounge VIP, mas o segurança te para e diz, "Você precisa mostrar seu cartão de membro." Isso é um 401 Unauthorized—é necessária autenticação antes que você possa acessar o recurso.
O código de status HTTP 401 Unauthorized indica que a solicitação do cliente não foi aplicada porque falta credenciais de autenticação válidas. O servidor requer que o cliente se autentique para acessar o recurso solicitado.
Você mostra seu cartão de membro, mas o segurança diz, "Apenas membros Platinum podem entrar." Isso é um 403 Forbidden—você está autenticado mas não tem as permissões necessárias para acessar o recurso.
O código de status HTTP 403 Forbidden indica que o servidor entende a solicitação do cliente, mas a recusa a cumprir porque o cliente não tem as permissões necessárias. Isso é diferente de um status 401 Unauthorized, pois o cliente está autenticado (ou a solicitação não requer autenticação), mas o acesso ao recurso é explicitamente negado.
Você faz um pedido, mas de repente a fumaça começa a sair da cozinha. O padeiro diz, "Não podemos completar seu 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 a execução da solicitação. É uma resposta de erro genérica e não fornece detalhes específicos sobre o que deu errado.
Você visita a padaria, mas há um aviso "Fechado para Manutenção". A padaria reabrirá mais tarde. Isso é um 503 Service Unavailable—o servidor está temporariamente incapaz de lidar com sua solicitação, geralmente 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 a solicitação. Isso pode ser devido a sobrecarga do servidor, manutenção ou outras condições temporárias. Diferente de um 500 Internal Server Error, um 503 implica que o problema deve ser resolvido em breve.
Códigos de status HTTP são fundamentais para manter uma comunicação eficiente entre clientes e servidores. Eles informam rapidamente aos clientes se suas solicitações foram bem-sucedidas, falharam ou exigem ação adicional. Para desenvolvedores e profissionais de TI, entender esses códigos ajuda a depurar problemas, projetar melhor tratamento de erros e melhorar a experiência geral do usuário.
Pense neles como sinais profissionais e padronizados na conversa contínua da internet.
Neste artigo, quero focar nos erros 401 e 403, pois eles estão intimamente relacionados à autenticação (AuthN) e autorização (AuthZ).
O código de status HTTP 401 Unauthorized é usado quando a solicitação do cliente requer autenticação, mas está ausente, inválida ou falhou. Ele informa ao cliente que eles precisam se autenticar 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 uma solicitação pode prosseguir.
401 unauthorized deve incluir um cabeçalho WWW-Authenticate, fornecendo detalhes sobre como se autenticar.
Então, quais são os cenários comuns para usar 401 Unauthorized?
Autenticação ausente
A solicitação não inclui as credenciais de autenticação necessárias. Por exemplo: Uma solicitação a um endpoint de API protegido é feita sem um cabeçalho de Autorização.
Credenciais de autenticação inválidas
O cliente fornece credenciais, mas elas 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 se autentique novamente. Por exemplo, um token JWT com uma data de expiração passada (claim exp).
Cabeçalho de autorização ausente ou malformado
O cabeçalho de autorização é necessário, mas não é fornecido ou formatado incorretamente.
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 a solicitação e a identidade do cliente (se autenticado) mas nega o acesso devido a permissões insuficientes. Ele sinaliza claramente, "Você não tem permissão para fazer isso," garantindo limites de acesso claros e reforçando políticas de segurança.
A distinção entre 401 Unauthorized e 403 Forbidden reside em seus papéis dentro dos contextos de autenticação e autorização.
A autorização é um mecanismo separado da autenticação. Enquanto a autenticação identifica quem você é, a autorização determina se você pode acessar recursos específicos e quais ações você pode realizar neles.
Para conferir a diferença detalhada sobre AuthN e AuthZ. Confira 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 função necessárias. Por exemplo, um usuário com função "visualizador" tenta deletar 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 a 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 pela política
O cliente está tentando 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 o 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 exclusivos de admin.
Certifique-se de que o cabeçalho de Authorization está presente e formatado corretamente e verifique se as credenciais (chave de API, token ou senha) estão corretas e não expiraram. Digitar o nome de usuário ou senha errados é 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 estiverem alinhados no protocolo de autenticação. Use o método correto (por exemplo, Basic, Bearer, Chave de API) conforme especificado pelo servidor e verifique a sintaxe adequada nos cabeçalhos.
Decodifique e inspecione o token (por exemplo, com https://logto.io/jwt-decoder) para validade, expiração e claims e combine o público (aud) do token com os requisitos da API.
Um erro 403 forbidden geralmente significa que o processo de autorização foi concluído, mas o acesso foi negado. Para resolver este erro, considere as seguintes condições:
Confirme que sua conta, chave de API ou token possui as permissões necessárias para o recurso. Verifique se o recurso é restrito a funções ou grupos específicos.
Examine o corpo da resposta para detalhes que expliquem o motivo do erro 403.
Um única solicitação pode retornar ambos os códigos de status 401 e 403#
Não, uma única solicitação HTTP não pode retornar ambos os códigos de status 401 Unauthorized e 403 Forbidden simultaneamente porque uma resposta HTTP pode incluir apenas 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 de aplicações modernas, 401 Unauthorized e 403 Forbidden são dois códigos de status HTTP que os desenvolvedores encontram frequentemente. Embora possam parecer semelhantes, seus significados e casos de uso são distintamente 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 multifatorial (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: "Você precisa 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 exclusiva para admin sem o papel necessário de admin. O servidor responde e lança um 403 Forbidden: "Você está logado, mas não tem permissão para acessar esta página."
Cenário multi-tenant: O mesmo usuário faz login mas pertence à Tenant A e tenta acessar um recurso na Tenant B, onde ele não tem acesso. O servidor responde e lança um 403 Forbidden: "Você está autenticado, mas não tem permissão para acessar este recurso na Tenant B."
Cenário de MFA: Um usuário tenta fazer login, mas não completou a Autenticação Multifatorial (MFA) necessária. O servidor responde e lança um erro 401 Unauthorized: "A autenticação está incompleta. Por favor, complete a MFA para prosseguir."
Usando Logto como um provedor de autenticação e autorização#
Logto é primeiramente 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ão aberto como OIDC, OAuth 2.0, e SAML.
