Перейти до основного вмісту

Версія NginxCommunity

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

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

  • Запущений сервіс Casdoor. Якщо ви ще не встановили сервіс Casdoor, будь ласка, зверніться до Інструкції з встановлення сервера або Спробуйте з Docker.
  • Відкрите джерело Nginx з модулем ngx_http_auth_request_module, увімкненим на момент компіляції. Якщо ви не знаєте, як увімкнути модуль ngx_http_auth_request_module, будь ласка, зверніться до Документації модуля Nginx.
  • Веб-сайт, на якому ви хочете увімкнути аутентифікацію, успішно розгорнуто на Nginx, з налаштованим доменним ім'ям (замість використання IP-адреси) і може бути доступний у звичайному режимі.
  • Інструмент OAuth2-Proxy (наразі на GitHub доступні два популярні проекти з високою кількістю зірок, і вам потрібно вибрати один з них):
  1. oauth2-proxy/oauth2-proxy (використовується в цій статті) GitHub АБО Офіційний сайт
  2. vouch/vouch-proxy GitHub

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

Примітка: Операції в цій статті базуються на Casdoor GUI на момент публікації, але Casdoor GUI може змінюватися залежно від версії. Будь ласка, слідуйте посиланням, наведеним у цій статті, щоб налаштувати вашу розгорнуту версію Casdoor.

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

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

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

    addApp

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

    ConfigureApp

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

    RecordInfo

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

    AddRole

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

    ConfigureRole

  7. (Необов'язково) У верхній панелі виберіть "Керування користувачами" > "Користувачі", а потім додайте нових користувачів відповідно до ваших потреб. Якщо потрібні вам користувачі вже існують, ви можете пропустити цей крок. У цій статті ми створюємо приклад користувача з ім'ям "user".

  8. Поверніться на сторінку "Ролі", згадану на кроці 5, відредагуйте роль nginx_role і додайте потрібних вам користувачів до опції "Включені користувачі". У цій статті ми додаємо раніше створеного builtin/user сюди.

II. Налаштування Oauth2-Proxy​

Примітка: Ця стаття використовує проект Oauth2-Proxy як приклад. Якщо ви хочете використовувати Vouch замість Oauth2-Proxy, будь ласка, зверніться до їх офіційної документації на GitHub.

Примітка: Ця стаття передбачає, що ваш сайт налаштований з довіреним SSL-сертифікатом і дозволяє лише доступ через HTTPS, або що ви налаштували автоматичне перенаправлення відвідувачів з HTTP на HTTPS. Це допомагає максимально захистити файли cookie і запобігає зловмисному читанню токенів входу. Якщо ваш сайт потрібно доступити через незахищений протокол HTTP, будь ласка, відповідно змініть відповідні команди. Для отримання додаткової допомоги з розгортання через HTTP, будь ласка, зверніться до офіційної документації Oauth2-Proxy на GitHub.

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

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

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

    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. Налаштування Nginx​

Примітка: Будь ласка, ще раз переконайтеся, що ваш Nginx увімкнув модуль ngx_http_auth_request_module під час компіляції та встановлення з вихідного коду (команда компіляції включає --with_http_auth_request_module). Якщо ви не знаєте, як увімкнути модуль ngx_http_auth_request_module, будь ласка, зверніться до Документації модуля Nginx.

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

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

    Примітка: Вам потрібно налаштувати цей файл конфігурації відповідно до вашої конкретної ситуації. Через версії Nginx та інші фактори цей файл конфігурації може не працювати гладко на всіх екземплярах Nginx. Будь ласка, відповідно до вашої власної інформації 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. Збережіть файл і перезавантажте ваш Nginx.

Тестування​

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

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

  • Якщо ваш проект не працює так, як очікувалося, будь ласка, перевірте вашу конфігурацію Nginx та параметри конфігурації Oauth2-Proxy на правильність.
  • Ви також можете звернутися до офіційної документації Oauth2-Proxy на GitHub.
  • Якщо ви знайдете помилки в цьому документі, будь ласка, не соромтеся запропонувати правки на GitHub.