Configuração de Autenticação OIDC#

Este guia explica como configurar autenticação OpenID Connect (OIDC) usando Google como provedor de identidade e servidor web Angie com scripts Lua.

A implementação protege endpoints internos com autenticação OAuth2/OIDC e demonstra uma maneira de restringir acesso baseado em domínios de e-mail. Este é apenas um exemplo de abordagem; você pode implementar controle de acesso da forma que preferir, como manter listas de permissão de usuários específicos, verificar associação a domínios ou atributos de grupo na resposta do provedor, ou usar declarações personalizadas do seu sistema IAM privado.

Dica

Esta implementação OIDC fornece uma base para autenticação, mas deve ser adaptada para uso em produção com medidas de segurança adequadas, monitoramento e conformidade com as políticas de segurança da sua organização.

Arquitetura#

A configuração OIDC sugerida aqui consiste em:

  • Angie - com suporte ao módulo Lua para processamento OIDC

  • lua-resty-openidc - biblioteca Lua do OpenResty para autenticação OIDC

  • Google OAuth2 - Provedor de identidade para autenticação de usuários

  • Docker Compose - Usado neste exemplo apenas para inicialização rápida; use a abordagem de implantação que preferir em produção

Pré-requisitos#

Antes de configurar a autenticação OIDC, certifique-se de ter:

  1. Servidor web Angie com suporte ao módulo Lua

  2. Docker e Docker Compose (para implantação)

  3. Um projeto no Google Cloud Console

  4. Credenciais OAuth2 do Google

Configuração do OAuth2 do Google#

Para configurar o Google como seu provedor OIDC:

  1. Navegue até o Google Cloud Console

  2. Crie um novo projeto ou selecione um existente

  3. Configure a tela de consentimento OAuth para seu projeto (Externo ou Interno) e publique-a para que os usuários possam autenticar

  4. Crie credenciais OAuth2:

    • Tipo de aplicativo: Aplicativo da Web

    • URIs de redirecionamento autorizados: http://localhost/auth/callback

  5. Salve seu client_id e client_secret para configuração

Nota

Os Serviços de Identidade do Google padrão já suportam OIDC; a API legada do Google+ não é necessária. Habilite APIs adicionais do Google apenas se seu aplicativo precisar dos dados delas.

Configuração Inicial#

Vamos começar com os arquivos de configuração necessários para a configuração OIDC.

Configuração do Docker Compose#

A implantação Docker usa o seguinte arquivo de configuração:

docker-compose.yml#
services:
  angie:
    image: docker.angie.software/angie:templated
    environment:
      ANGIE_LOAD_MODULES: "lua"
    ports:
      - 80:80
    volumes:
      - ./files/etc/angie/http.d:/etc/angie/http.d

Esta configuração faz o seguinte:

  • Usa a imagem Angie com templates com suporte ao módulo Lua

  • Carrega o módulo Lua para funcionalidade OIDC

  • Mapeia a porta 80 para acesso HTTP

  • Monta arquivos de configuração do diretório local

Para uma demonstração pronta para uso, baixe o pacote de início rápido OIDC, defina seu client_id e client_secret em files/etc/angie/http.d/oidc.lua, e tudo funcionará imediatamente.

Script de Autenticação OIDC#

Crie um script de autenticação OIDC que manipula a lógica de autenticação usando a biblioteca lua-resty-openidc:

/etc/angie/http.d/oidc.lua#
access_by_lua_block {
    local res, err = require("resty.openidc").authenticate({
        redirect_uri = "http://localhost/auth/callback",
        discovery = "https://accounts.google.com/.well-known/openid-configuration",
        logout_path = "/auth/logout",
        redirect_after_logout_uri = "/auth/logged-out",
        revoke_tokens_on_logout = true,
        client_id = "YOUR_CLIENT_ID",
        client_secret = "YOUR_CLIENT_SECRET"
    })
}

Parâmetros de configuração:

  • redirect_uri: URL de callback após autenticação bem-sucedida

  • discovery: Endpoint de descoberta OIDC do Google

  • logout_path: Caminho para logout do usuário

  • redirect_after_logout_uri: Destino de redirecionamento após logout

  • revoke_tokens_on_logout: Revogar tokens no logout para segurança

  • client_id e client_secret: Suas credenciais OAuth2 do Google

Configuração do Angie#

Configure o Angie com os blocos location necessários para autenticação OIDC.

Recursos Protegidos#

Para proteger recursos com autenticação OIDC:

location /internal/ {
    include /etc/angie/http.d/oidc.lua;
    proxy_pass http://127.0.0.1/status/;
}

Esta configuração faz o seguinte:

  • Protege o caminho /internal/ com autenticação OIDC

  • Faz proxy de requisições autenticadas para a API interna em /status/

Endpoints de Autenticação#

Configure os endpoints do fluxo OAuth2:

location /auth/callback {
    include /etc/angie/http.d/oidc.lua;
}

location /auth/logout {
    include /etc/angie/http.d/oidc.lua;
}

location /auth/logged-out {
    default_type text/plain;
    return 200 "Você foi desconectado. Até logo!";
}

Funções dos endpoints:

  • /auth/callback: Manipula callback OAuth2 do Google

  • /auth/logout: Inicia logout do usuário

  • /auth/logged-out: Página de destino após logout bem-sucedido

Acesso à API Interna#

Configure acesso restrito à API interna:

location /status/ {
    api     /status/;
    allow   127.0.0.1;
    deny    all;
}

Isso fornece:

  • Acesso à API de status do Angie

  • Acesso somente localhost (127.0.0.1)

  • Proteção OIDC quando acessado através de /internal/

Etapas de Implantação#

Siga estas etapas para implantar a autenticação OIDC:

Atualização da Configuração#

  1. Atualize as credenciais OAuth2 no seu script Lua OIDC:

    Substitua os valores de espaço reservado em oidc.lua:

    • client_id com seu ID de cliente OAuth2 do Google

    • client_secret com seu segredo de cliente OAuth2 do Google

Inicialização do Serviço#

  1. Inicie os serviços Docker:

    $ docker-compose up -d

  2. Verifique a implantação:

    • Navegue até http://localhost/internal/

    • Você deve ser redirecionado para o Google para autenticação

    • Após login bem-sucedido, você acessará o conteúdo protegido

Configuração de Segurança#

Restrição de Domínio de E-mail#

Implemente validação de domínio para restringir acesso por domínio de e-mail:

if not string.match(res.user.email, "gmail.com$") then
    ngx.exit(ngx.HTTP_FORBIDDEN)
end

Para ambientes de produção, considere o seguinte:

  • Substituir gmail.com pelo domínio da sua organização

  • Implementar uma lista de permissão de endereços de e-mail permitidos

  • Adicionar controle de acesso baseado em funções

Gerenciamento de Tokens#

A implementação OIDC inclui recursos de segurança:

  • Tokens são automaticamente revogados no logout (revoke_tokens_on_logout = true)

  • Sessões são gerenciadas com segurança pela biblioteca lua-resty-openidc

  • Todos os fluxos de autenticação seguem as melhores práticas de segurança OAuth2/OIDC

Aviso

Para implantações em produção:

  • Sempre use HTTPS para callbacks OAuth2

  • Armazene segredos de cliente com segurança, nunca no controle de versão

  • Implemente políticas adequadas de timeout e renovação de sessão

  • Monitore logs de autenticação para eventos de segurança

Fluxo de Autenticação#

O fluxo de autenticação OIDC segue procedimentos padrão OAuth2/OIDC:

  1. Usuário acessa uma URL protegida (por exemplo, http://localhost/internal/)

  2. Se não autenticado, usuário é redirecionado para OAuth2 do Google

  3. Usuário autentica com credenciais do Google

  4. Google redireciona de volta para /auth/callback com código de autorização

  5. Servidor troca código por token de acesso e token de ID

  6. Informações do usuário são validadas (incluindo verificação de domínio de e-mail)

  7. Usuário recebe acesso ao recurso protegido

O processo de logout garante encerramento seguro da sessão:

  1. Usuário navega para http://localhost/auth/logout

  2. Tokens são revogados no endpoint OAuth2 do Google

  3. Dados de sessão local são limpos

  4. Usuário é redirecionado para /auth/logged-out

Configuração Avançada#

Para restringir acesso a um domínio organizacional específico:

if not string.match(res.user.email, "suaempresa.com$") then
    ngx.exit(ngx.HTTP_FORBIDDEN)
end

Para organizações com múltiplos domínios permitidos:

local allowed_domains = {"empresa1.com", "empresa2.com", "gmail.com"}
local email_valid = false

for _, domain in ipairs(allowed_domains) do
    if string.match(res.user.email, domain .. "$") then
        email_valid = true
        break
    end
end

if not email_valid then
    ngx.exit(ngx.HTTP_FORBIDDEN)
end

Acesso a Informações do Usuário#

Acesse declarações adicionais do usuário do provedor OIDC:

-- Acessar informações do usuário a partir do token de ID
local user_name = res.user.name
local user_picture = res.user.picture
local user_locale = res.user.locale
local user_email = res.user.email

Esses valores podem ser usados para registro de logs, personalização ou decisões adicionais de controle de acesso.