Nginx community edition

Необхідні умови

Цей посібник передбачає, що у вас є наступні умови:

• Запущений сервіс Casdoor. If you haven't installed Casdoor service yet, see Server installation or Try with Docker.
• Відкрите джерело Nginx з модулем ngx_http_auth_request_module, увімкненим на момент компіляції. See the Nginx auth_request module to enable it.
• Веб-сайт, на якому ви хочете увімкнути аутентифікацію, успішно розгорнуто на Nginx, з налаштованим доменним ім'ям (замість використання IP-адреси) і може бути доступний у звичайному режимі.
• OAuth2-Proxy (choose one of the two popular options on GitHub):

1. oauth2-proxy/oauth2-proxy (використовується в цій статті) GitHub АБО Офіційний сайт
2. vouch/vouch-proxy GitHub

I. Налаштування CasDoor

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

Примітка: Ключі, паролі, імена користувачів та інша конфіденційна інформація, згадана в цій статті, є прикладами. З міркувань безпеки ви повинні замінити їх на власний відповідний вміст при розгортанні.

1. Увійдіть до свого адміністративного облікового запису Casdoor.

2. У верхній панелі виберіть "Ідентифікація особи" > "Додатки", а потім натисніть "Додати" на сторінці "Додатки".

   

3. Заповніть конфігурацію додатка на основі інформації про ваш проект. У цій статті ми використовуємо "Nginx-Community" як приклад назви додатка.

   

4. Запишіть значення полів "Client ID" та "Client Secret". Вони будуть використані пізніше при налаштуванні OAuth2-Proxy. Потім налаштуйте "Redirect URL" як https://project.yourdomain.com/oauth2/callback/.

   

5. У верхній панелі виберіть "Керування дозволами Casbin" > "Ролі", а потім натисніть "Додати" на сторінці "Ролі".

   

6. Заповніть конфігурацію ролі на основі інформації про ваш проект. У цій статті ми використовуємо "nginx_role" як приклад назви ролі.

   

7. (Необов'язково) У верхній панелі виберіть "Керування користувачами" > "Користувачі", а потім додайте нових користувачів відповідно до ваших потреб. If the users already exist, skip this step. У цій статті ми створюємо приклад користувача з ім'ям "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

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.

Поради: OAuth2-Proxy пропонує різні методи розгортання (такі як компіляція з вихідного коду, встановлення через Docker тощо). Для спрощення пояснення ця стаття використовує "попередньо зібраний двійковий файл" для розгортання.

1. Перейдіть на сторінку GitHub Releases і завантажте двійковий пакет, що відповідає вашій операційній системі та архітектурі CPU. Станом на 1 січня 2024 року остання версія 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

   Настійно рекомендується перевірити значення SHA256SUM, надане офіційним сайтом на сторінці GitHub Releases після завантаження стислого пакету і порівняти його зі значенням SHA256SUM завантаженого вами пакету, символ за символом.

2. Розпакуйте завантажений пакет:

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

3. Увійдіть до розпакованої директорії:

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

4. Перемістіть отриманий двійковий файл до /usr/local/bin і налаштуйте його з виконавчими правами. Можливо, вам знадобиться підвищити права за допомогою sudo залежно від вашої ситуації.

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

5. Перевірте встановлення двійкового файлу. Якщо встановлення пройшло успішно, після виконання наступної команди ви повинні побачити вивід, схожий на oauth2-proxy v7.5.1 (зібрано з go1.21.1).

   cd ~
   oauth2-proxy --version

6. Запустіть oauth2-proxy з параметрами командного рядка. Параметри, позначені [обов'язкові], повинні бути налаштовані відповідно до вашої конкретної ситуації, тоді як параметри, позначені [необов'язкові], можуть оптимізувати продуктивність, але також можуть бути пропущені. 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

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.

Поради: Nginx, встановлений за допомогою інструменту панелі Baota, за замовчуванням не увімкнує цей модуль.

1. Відкрийте файл конфігурації вже розгорнутого вами веб-сайту, який ви хочете захистити, і внесіть наступні зміни:

   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. Збережіть файл і перезавантажте ваш Nginx.

Тестування

• Next, test your implementation.
• За звичайних обставин ваші користувачі пройдуть наступний процес під час входу до вашого сервісу:
• Відкрийте URL project.yourdomain.com у браузері -> Побачите лише сторінку, що вимагає входу, включаючи кнопку з назвою "Увійти з OpenID Connect" -> Натисніть кнопку і будете перенаправлені на вашу адресу Casdoor, де вас попросять увійти -> Користувачі вводять своє ім'я користувача та пароль, і Casdoor перевіряє їхні дані -> Автоматично перенаправляються назад на ваш URL project.yourdomain.com -> Успішно отримують доступ до вашого сервісу -> Користувачів попросять увійти знову, коли закінчиться час --cookie-expire, який ви встановили.

Усунення несправностей

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