Nginx community edition

Voraussetzungen

Dieser Leitfaden setzt voraus, dass Sie die folgenden Bedingungen haben:

• Laufender Casdoor-Dienst. If you haven't installed Casdoor service yet, see Server installation or Try with Docker.
• Nginx Open-Source-Edition mit aktiviertem ngx_http_auth_request_module Modul zur Kompilierungszeit. See the Nginx auth_request module to enable it.
• Die Website, auf der Sie die Authentifizierung aktivieren möchten, ist erfolgreich auf Nginx bereitgestellt, mit einem konfigurierten Domainnamen (anstatt einer IP-Adresse) und kann normal aufgerufen werden.
• OAuth2-Proxy (choose one of the two popular options on GitHub):

1. oauth2-proxy/oauth2-proxy (in diesem Artikel verwendet) GitHub ODER Offizielle-Webseite
2. vouch/vouch-proxy GitHub

I. Casdoor konfigurieren

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

Hinweis: Die Schlüssel, Passwörter, Benutzernamen und andere vertrauliche Informationen, die in diesem Artikel erwähnt werden, sind alle Beispiele. Aus Sicherheitsgründen müssen Sie sie durch Ihre eigenen relevanten Inhalte ersetzen, wenn Sie sie bereitstellen.

1. Melden Sie sich bei Ihrem Casdoor-Admin-Konto an.

2. In der oberen Leiste wählen Sie "Identitätsauthentifizierung" > "Anwendungen" und klicken Sie dann auf "Hinzufügen" auf der Seite "Anwendungen".

   

3. Vervollständigen Sie die Anwendungskonfiguration basierend auf Ihren Projektinformationen. In diesem Artikel verwenden wir "Nginx-Community" als Beispielanwendungsnamen.

   

4. Beachten Sie die Werte der Felder "Client ID" und "Client Secret". Sie werden später bei der Konfiguration von OAuth2-Proxy verwendet. Dann konfigurieren Sie die "Redirect URL" als https://project.yourdomain.com/oauth2/callback/.

   

5. In der oberen Leiste wählen Sie "Casbin-Berechtigungsmanagement" > "Rollen" und klicken Sie dann auf "Hinzufügen" auf der Seite "Rollen".

   

6. Vervollständigen Sie die Rollenkonfiguration basierend auf Ihren Projektinformationen. In diesem Artikel verwenden wir "nginx_role" als Beispielrollennamen.

   

7. (Optional) In der oberen Leiste wählen Sie "Benutzerverwaltung" > "Benutzer" und fügen dann neue Benutzer basierend auf Ihren Bedürfnissen hinzu. If the users already exist, skip this step. In diesem Artikel erstellen wir einen Beispielbenutzer namens "user".

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. Oauth2-Proxy konfigurieren

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.

Tipps: OAuth2-Proxy bietet verschiedene Bereitstellungsmethoden (wie Quellcodekompilierung, Docker-Installation usw.). Zur Vereinfachung der Erklärung verwendet dieser Artikel das "vorgefertigte Binär" für die Bereitstellung.

1. Gehen Sie zur GitHub Releases Seite und laden Sie das Binärpaket herunter, das Ihrem Betriebssystem und Ihrer CPU-Architektur entspricht. Stand 1. Januar 2024 ist die neueste Release-Version von OAuth-Proxy 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

   Es wird dringend empfohlen, dass Sie den von der offiziellen Website auf der GitHub Releases Seite bereitgestellten SHA256SUM Wert nach dem Herunterladen des komprimierten Pakets überprüfen und ihn Zeichen für Zeichen mit dem SHA256SUM Wert des von Ihnen heruntergeladenen Pakets vergleichen.

2. Extrahieren Sie das heruntergeladene Paket:

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

3. Betreten Sie das extrahierte Verzeichnis:

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

4. Verschieben Sie die erhaltene Binärdatei nach /usr/local/bin und konfigurieren Sie sie mit ausführbaren Berechtigungen. Möglicherweise müssen Sie Berechtigungen mit sudo erhöhen, je nach Ihrer Situation.

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

5. Testen Sie die Binärinstallation. Wenn die Installation erfolgreich ist, sollten Sie nach Ausführung des folgenden Befehls eine Ausgabe ähnlich oauth2-proxy v7.5.1 (gebaut mit go1.21.1) sehen.

   cd ~
   oauth2-proxy --version

6. Führen Sie oauth2-proxy mit Befehlszeilenparametern aus. Parameter, die mit [erforderlich] gekennzeichnet sind, müssen gemäß Ihrer spezifischen Situation konfiguriert werden, während Parameter, die mit [optional] gekennzeichnet sind, die Leistung optimieren können, aber auch weggelassen werden können. 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. Nginx konfigurieren

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.

Tipps: Nginx, das mit dem Baota-Panel-Tool installiert wurde, aktiviert dieses Modul standardmäßig nicht.

1. Öffnen Sie die Konfigurationsdatei der bereits bereitgestellten und zu schützenden Website und nehmen Sie die folgenden Änderungen vor:

   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. Speichern Sie die Datei und laden Sie Ihr Nginx neu.

Testen

• Next, test your implementation.
• Unter normalen Umständen durchlaufen Ihre Benutzer den folgenden Prozess, wenn sie sich bei Ihrem Dienst anmelden:
• Öffnen Sie die URL project.yourdomain.com in einem Browser -> Sehen Sie nur eine Seite, die eine Anmeldung erfordert, einschließlich einer Schaltfläche mit der Aufschrift "Anmelden mit OpenID Connect" -> Klicken Sie auf die Schaltfläche und werden Sie zu Ihrer Casdoor-Adresse weitergeleitet, wo Sie aufgefordert werden, sich anzumelden -> Benutzer geben ihren Benutzernamen und ihr Passwort ein, und Casdoor überprüft ihre Anmeldeinformationen -> Automatische Weiterleitung zurück zu Ihrer URL project.yourdomain.com -> Erfolgreicher Zugriff auf Ihren Dienst -> Benutzer werden aufgefordert, sich erneut anzumelden, wenn die von Ihnen festgelegte --cookie-expire Zeit abläuft.

Fehlerbehebung

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