Pular para o conteúdo principal

Versão Comunitária do Nginx

Pré-requisitos​

Este guia pressupõe que você tenha as seguintes condições:

  • Serviço Casdoor em execução. Se você ainda não instalou o serviço Casdoor, consulte Instalação do Servidor ou Experimente com Docker.
  • Edição de código aberto do Nginx com o módulo ngx_http_auth_request_module habilitado no momento da compilação. Se você não sabe como habilitar o módulo ngx_http_auth_request_module, consulte o Documento do Módulo Nginx.
  • O site no qual você deseja habilitar a autenticação está implantado com sucesso no Nginx, com um nome de domínio configurado (em vez de usar um endereço IP) e pode ser acessado normalmente.
  • Ferramenta OAuth2-Proxy (atualmente, os dois projetos populares a seguir com muitas estrelas estão disponíveis no GitHub, e você precisa escolher um deles):
  1. oauth2-proxy/oauth2-proxy (usado neste artigo) GitHub OU Site Oficial
  2. vouch/vouch-proxy GitHub

I. Configurar Casdoor​

Nota: As operações neste artigo são baseadas na GUI do Casdoor no momento da publicação, mas a GUI do Casdoor pode mudar dependendo da versão. Siga as referências fornecidas neste artigo para configurar sua versão do Casdoor implantada.

Nota: As chaves, senhas, nomes de usuário e outras informações confidenciais mencionadas neste artigo são todos exemplos. Por razões de segurança, você deve substituí-las pelo seu próprio conteúdo relevante ao implantar.

  1. Faça login na sua conta de administrador do Casdoor.

  2. Na barra superior, selecione 'Autenticação de Identidade' > 'Aplicações', e então clique em 'Adicionar' na página 'Aplicações'.

    addApp

  3. Complete a configuração da aplicação com base nas informações do seu projeto. Neste artigo, usamos 'Nginx-Community' como o nome de aplicação de exemplo.

    ConfigureApp

  4. Anote os valores dos campos 'Client ID' e 'Client Secret'. Eles serão usados ao configurar o OAuth2-Proxy mais tarde. Em seguida, configure a 'URL de Redirecionamento' como https://project.yourdomain.com/oauth2/callback/.

    RecordInfo

  5. Na barra superior, selecione 'Gerenciamento de Permissões Casbin' > 'Funções', e então clique em 'Adicionar' na página 'Funções'.

    AddRole

  6. Complete a configuração da função com base nas informações do seu projeto. Neste artigo, usamos 'nginx_role' como o nome da função de exemplo.

    ConfigureRole

  7. (Opcional) Na barra superior, selecione 'Gerenciamento de Usuários' > 'Usuários', e então adicione novos usuários conforme sua necessidade. Se os usuários que você precisa já existem, você pode pular esta etapa. Neste artigo, criamos um usuário de exemplo chamado 'user'.

  8. Volte para a página 'Funções' mencionada no passo 5, edite a função nginx_role e adicione os usuários necessários à opção 'Usuários Incluídos'. Neste artigo, adicionamos o builtin/user previamente criado aqui.

II. Configurar Oauth2-Proxy​

Nota: Este artigo usa o projeto Oauth2-Proxy como exemplo. Se você quiser usar o Vouch em vez do Oauth2-Proxy, consulte a documentação oficial deles no GitHub.

Nota: Este artigo pressupõe que seu site está configurado com um certificado SSL confiável e permite apenas acesso HTTPS, ou que você configurou redirecionamento automático de visitantes HTTP para HTTPS. Isso ajuda a maximizar a proteção de cookies e impede a leitura maliciosa de tokens de login. Se o seu site precisa ser acessado via protocolo HTTP inseguro, modifique os comandos relevantes de acordo. Para mais ajuda com a implantação via HTTP, consulte a documentação oficial do Oauth2-Proxy no GitHub.

Dicas: OAuth2-Proxy oferece vários métodos de implantação (como compilação de código-fonte, instalação via Docker, etc.). Para facilitar a explicação, este artigo usa o 'binário pré-construído' para implantação.

  1. Vá para a página GitHub Releases e baixe o pacote binário correspondente ao seu sistema operacional e arquitetura de CPU. Até 1 de janeiro de 2024, a versão de lançamento mais recente do OAuth-Proxy é V7.5.1. Se você quiser baixar o pacote binário para esta versão, você pode executar o seguinte comando para Linux com AMD64:

    wget -O oauth2-proxy-linux.tar.gz https://github.com/oauth2-proxy/oauth2-proxy/releases/download/v7.5.1/oauth2-proxy-v7.5.1.linux-amd64.tar.gz

    É altamente recomendável que você verifique o valor SHA256SUM fornecido pelo site oficial na página GitHub Releases após baixar o pacote compactado e compare-o com o valor SHA256SUM do pacote que você baixou, caractere por caractere.

  2. Extraia o pacote baixado:

    tar -zxvf oauth2-proxy-*.tar.gz

  3. Entre no diretório extraído:

    cd oauth2-proxy-v7.5.1.linux-amd64

  4. Mova o arquivo binário obtido para /usr/local/bin e configure-o com permissões de execução. Você pode precisar elevar permissões usando sudo dependendo da sua situação.

    cp ./oauth2-proxy /usr/local/bin
    cd /usr/local/bin
    chmod +x ./oauth2-proxy

  5. Teste a instalação do binário. Se a instalação for bem-sucedida, após executar o seguinte comando, você deve ver uma saída semelhante a oauth2-proxy v7.5.1 (construído com go1.21.1).

    cd ~
    oauth2-proxy --version

  6. Execute o oauth2-proxy com parâmetros de linha de comando. Parâmetros marcados com [obrigatório] devem ser configurados de acordo com sua situação específica, enquanto parâmetros marcados com [opcional] podem otimizar o desempenho, mas também podem ser omitidos. Para garantir que o oauth2-proxy possa ser executado em segundo plano, você pode usar ferramentas de monitoramento de processos como Screen ou Supervisor ou ferramentas de terminal.

    oauth2-proxy \ 
    --provider=oidc \ #[required] Do not change
    --client-id=abc123456def \ #[required] "Client ID" obtained in step I.4 above
    --client-secret=abc123456def \ #[required] "Client Secret" obtained in step I.4 above
    --oidc-issuer-url=https://auth.yourdomain.com \ #[required] Your Casdoor URL (domain name or public IP)
    --redirect-url=https://project.yourdomain.com/oauth2/callback \ #[required] https://domain-of-the-project-to-protect/oauth2/callback 
    --scope=email+profile+groups+openid \ #[required] Obtained from Casdoor: user email, user profile, groups, and login authentication
    --cookie-domain=project.yourdomain.com \ #[required] Domain name of the project you want to protect
    --whitelist-domain=project.yourdomain.com \ #[required] Domain name of the project you want to protect
    --cookie-secret=abc123456def \ #[required] Please generate a random string of numbers and letters and fill it in here
    --email-domain=* \ #[required] List of acceptable user email domains (* means accept all domains). If the user's email suffix is not in this list, a 403 error will be returned even if the login is successful.
    --insecure-oidc-allow-unverified-email=true \ #[required] Whether to accept users with unverified email addresses
    --http-address=http://127.0.0.1:65534 \ #[required] Address that oauth2-proxy listens on. The port number here can be set arbitrarily. Please record the value you set, as it will be needed for configuring Nginx later.
    --cookie-expire=24h0m0s \ #[optional] Cookie expiration time. After this period, users will need to log in again.
    --custom-sign-in-logo=https://cdn.yourdomain.com/pic/proj.png \ #[optional] Icon displayed on the login page. It is recommended to use a rectangular image rather than a square one.
    --session-store-type=redis \ #[optional] Use Redis cache. If you don't need Redis, you can delete this item.
    --redis-connection-url=redis://127.0.0.1:6379/0 \ #[optional] Redis URL. If you don't need Redis, you can delete this item.
    --redis-password=123456 #[optional] Redis connection password. If you don't need Redis or Redis has no password, you can delete this item.

III. Configurar Nginx​

Nota: Por favor, confirme novamente que seu Nginx habilitou o módulo ngx_http_auth_request_module ao compilar e instalar a partir do código-fonte (o comando de compilação inclui --with_http_auth_request_module). Se você não sabe como habilitar o módulo ngx_http_auth_request_module, consulte o Documento do Módulo Nginx.

Dicas: Nginx instalado usando a ferramenta do painel Baota não habilita este módulo por padrão.

  1. Abra o arquivo de configuração do site que você já implantou e deseja proteger, e faça as seguintes modificações:

    Nota: Você precisa ajustar este arquivo de configuração de acordo com sua situação específica. Devido a versões do Nginx e outros fatores, este arquivo de configuração pode não funcionar sem problemas em todas as instâncias do Nginx. Ajuste o conteúdo relevante com base nas informações do seu próprio Nginx.

    server {
        listen 443 ssl http2;

        include /path/to/ssl.conf;

        # Add the following content
        location ^~ /oauth2/ {
            proxy_pass       http://127.0.0.1:65534; # Change this to the "--http-address" configured in step II.6

            proxy_set_header Host                    $host;
            proxy_set_header X-Real-IP               $remote_addr;
            proxy_set_header X-Scheme                $scheme;

            proxy_set_header X-Auth-Request-Redirect $request_uri;
            # or, if you are handling multiple domains:
            # proxy_set_header X-Auth-Request-Redirect $scheme://$host$request_uri;
        }
        location = /oauth2/auth {
            proxy_pass       http://127.0.0.1:65534; # Change this to the "--http-address" configured in step II.6

            proxy_set_header Host             $host;
            proxy_set_header X-Real-IP        $remote_addr;
            proxy_set_header X-Scheme         $scheme;
            proxy_set_header Content-Length   "";
            proxy_pass_request_body           off;
        }
        location ^~ / {
            auth_request /oauth2/auth;
            error_page 401 = /oauth2/sign_in;

            auth_request_set $user   $upstream_http_x_auth_request_user; 
            auth_request_set $email  $upstream_http_x_auth_request_email; 
            proxy_set_header X-User  $user; # Pass the username of the user logged in to your backend service
            proxy_set_header X-Email $email; # Pass the email of the user logged in to your backend service

            auth_request_set $token  $upstream_http_x_auth_request_access_token;
            proxy_set_header X-Access-Token $token; # Pass the user's login token to your backend service

            # The following configurations are related to cookie validation for user login
            auth_request_set $auth_cookie $upstream_http_set_cookie;
            add_header Set-Cookie $auth_cookie;

            auth_request_set $auth_cookie_name_upstream_1 $upstream_cookie_auth_cookie_name_1;

            if ($auth_cookie ~* "(; .*)") {
                set $auth_cookie_name_0 $auth_cookie;
                set $auth_cookie_name_1 "auth_cookie_name_1=$auth_cookie_name_upstream_1$1";
            }   

            if ($auth_cookie_name_upstream_1) {
                add_header Set-Cookie $auth_cookie_name_0;
                add_header Set-Cookie $auth_cookie_name_1;
            }
            proxy_no_cache $cookie_session;

            # Provide the web page to the user after successful validation

            proxy_pass http://127.0.0.1:8080; # The address where your backend service runs
            # Note: This is not the Casdoor deployment address or the Oauth2-Proxy running address, but the address where your backend service that needs login protection runs.

            # Then add configurations to pass user IP, Connection request headers, etc., to your backend service, for example:
            proxy_set_header X-Forwarded-For $remote_addr;
            proxy_http_version 1.1;
            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection upgrade;
            proxy_set_header Accept-Encoding gzip;
        }
        access_log /path/to/access_log.log;
        error_log /path/to/error_log.log;
    }

  2. Salve o arquivo e recarregue seu Nginx.

Testando​

  • A seguir, você pode testar sua implementação.
  • Em circunstâncias normais, seus usuários passarão pelo seguinte processo ao fazer login no seu serviço:
  • Abrir a URL project.yourdomain.com em um navegador -> Ver apenas uma página que requer login, incluindo um botão chamado 'Entrar com OpenID Connect' -> Clicar no botão e ser redirecionado para o endereço do seu Casdoor, onde será solicitado a fazer login -> Usuários inserem seu nome de usuário e senha, e o Casdoor verifica suas credenciais -> Redirecionamento automático de volta para a sua URL project.yourdomain.com -> Acesso bem-sucedido ao seu serviço -> Usuários serão solicitados a fazer login novamente quando o tempo --cookie-expire que você definiu expirar.

Solução de problemas​

  • Se o seu projeto não estiver funcionando conforme o esperado, verifique a correção dos parâmetros de configuração do Nginx e do Oauth2-Proxy.
  • Você também pode consultar a documentação oficial do Oauth2-Proxy no GitHub.
  • Se você encontrar algum erro neste documento, sinta-se à vontade para solicitar edições no GitHub.