Nginx community edition

Prerrequisitos

Esta guía asume que tienes las siguientes condiciones:

• Servicio Casdoor en funcionamiento. If you haven't installed Casdoor service yet, see Server installation or Try with Docker.
• Edición de código abierto de Nginx con el módulo ngx_http_auth_request_module habilitado en el momento de la compilación. See the Nginx auth_request module to enable it.
• El sitio web en el que deseas habilitar la autenticación está exitosamente desplegado en Nginx, con un nombre de dominio configurado (en lugar de usar una dirección IP), y puede ser accedido normalmente.
• OAuth2-Proxy (choose one of the two popular options on GitHub):

1. oauth2-proxy/oauth2-proxy (usado en este artículo) GitHub O Sitio Oficial
2. vouch/vouch-proxy GitHub

I. Configurar Casdoor

Note: The Casdoor GUI may differ by version; use this article as a reference and adapt to your build.

Nota: Las claves, contraseñas, nombres de usuario y otra información confidencial mencionada en este artículo son todos ejemplos. Por razones de seguridad, debes reemplazarlos con tu propio contenido relevante al desplegar.

1. Inicia sesión en tu cuenta de administrador de Casdoor.

2. En la barra superior, selecciona "Autenticación de Identidad" > "Aplicaciones", y luego haz clic en "Agregar" en la página de "Aplicaciones".

   

3. Completa la configuración de la aplicación basada en la información de tu proyecto. En este artículo, usamos "Nginx-Community" como el nombre de la aplicación de ejemplo.

   

4. Toma nota de los valores de los campos "Client ID" y "Client Secret". Se utilizarán al configurar OAuth2-Proxy más adelante. Luego configura la "URL de Redirección" como https://project.yourdomain.com/oauth2/callback/.

   

5. En la barra superior, selecciona "Gestión de Permisos de Casbin" > "Roles", y luego haz clic en "Agregar" en la página de "Roles".

   

6. Completa la configuración del rol basada en la información de tu proyecto. En este artículo, usamos "nginx_role" como el nombre del rol de ejemplo.

   

7. (Opcional) En la barra superior, selecciona "Gestión de Usuarios" > "Usuarios", y luego agrega nuevos usuarios según tus necesidades. If the users already exist, skip this step. En este artículo, creamos un usuario de ejemplo llamado "usuario".

8. Go back to the "Roles" page mentioned in step 5, edit the nginx_role role, and add the required users to Included Users (e.g. the previously created builtin/user).

II. Configurar Oauth2-Proxy

Note: For Vouch instead of OAuth2-Proxy, see vouch-proxy on GitHub.

Note: This guide assumes HTTPS (or HTTP→HTTPS redirect). For HTTP-only deployment, adjust the commands and see OAuth2-Proxy docs.

Consejos: OAuth2-Proxy proporciona varios métodos de implementación (como compilación de código fuente, instalación de Docker, etc.). Para facilitar la explicación, este artículo utiliza el "binario preconstruido" para la implementación.

1. Ve a la página de GitHub Releases y descarga el paquete binario correspondiente a tu sistema operativo y arquitectura de CPU. A partir del 1 de enero de 2024, la última versión de lanzamiento de OAuth-Proxy es V7.5.1. To download the binary for this version on Linux AMD64, run:

   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

   Se recomienda encarecidamente que verifiques el valor de SHA256SUM proporcionado por el sitio oficial en la página de GitHub Releases después de descargar el paquete comprimido y lo compares con el valor de SHA256SUM del paquete que descargaste, carácter por carácter.

2. Extrae el paquete descargado:

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

3. Entra en el directorio extraído:

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

4. Mueve el archivo binario obtenido a /usr/local/bin y configúralo con permisos de ejecución. Puede que necesites elevar permisos usando sudo dependiendo de tu situación.

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

5. Prueba la instalación del binario. Si la instalación es exitosa, después de ejecutar el siguiente comando, deberías ver una salida similar a oauth2-proxy v7.5.1 (construido con go1.21.1).

   cd ~
   oauth2-proxy --version

6. Ejecuta oauth2-proxy con parámetros de línea de comandos. Los parámetros marcados con [requerido] deben ser configurados de acuerdo a tu situación específica, mientras que los parámetros marcados con [opcional] pueden optimizar el rendimiento pero también pueden ser omitidos. To run oauth2-proxy in the background, use a process manager such as Screen, Supervisor, or a terminal multiplexer.

   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] Use a random string (letters and numbers)
   --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 oauth2-proxy listens on; note this for the Nginx config 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. Omit if not using Redis.
   --redis-connection-url=redis://127.0.0.1:6379/0 \ #[optional] Redis URL. Omit if not using Redis.
   --redis-password=123456 #[optional] Redis password. Omit if not using Redis or if Redis has no password.

III. Configurar Nginx

Note: If building Nginx from source, ensure ngx_http_auth_request_module is enabled (add --with_http_auth_request_module). See the Nginx auth_request module.

Consejos: Nginx instalado usando la herramienta del panel Baota no habilita este módulo por defecto.

1. Abre el archivo de configuración del sitio web que ya has desplegado y quieres proteger, y realiza las siguientes modificaciones:

   Note: Adjust the config for your setup; Nginx version and environment may require changes.

   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. Guarda el archivo y recarga tu Nginx.

Pruebas

• Next, test your implementation.
• En circunstancias normales, tus usuarios pasarán por el siguiente proceso al iniciar sesión en tu servicio:
• Abrir la URL project.yourdomain.com en un navegador -> Solo ver una página que requiere inicio de sesión, incluyendo un botón llamado "Iniciar sesión con OpenID Connect" -> Hacer clic en el botón y ser redirigido a tu dirección de Casdoor, donde se les pedirá que inicien sesión -> Los usuarios ingresan su nombre de usuario y contraseña, y Casdoor verifica sus credenciales -> Redirección automática de vuelta a tu URL project.yourdomain.com -> Acceso exitoso a tu servicio -> A los usuarios se les pedirá que inicien sesión nuevamente cuando expire el tiempo de --cookie-expire que configuraste.

Resolución de problemas

• If it does not run as expected, check your Nginx and OAuth2-Proxy configuration.
• See OAuth2-Proxy documentation.
• To suggest fixes for this doc, open an issue or PR on GitHub.