OAuth2 Proxy
OAuth2 Proxy — це зворотний проксі, який автентифікує користувачів через OIDC-провайдера перед тим, як вони отримають доступ до вашого застосунку. Він також може працювати як ендпоінт forward-auth для Nginx, Caddy або Traefik. Використовуючи Casdoor як провайдера, ви можете дозволити доступ лише учасникам групи Casdoor або користувачам, які мають певну роль Casdoor.
Конфігурація на цій сторінці була протестована кінцевим користувачем (end to end) з OAuth2 Proxy v7.15 та Casdoor v4.17.
Якщо вам потрібен лише вхід через Casdoor перед застосунком і не потрібен сам OAuth2 Proxy, casdoor-forward-auth виконує ту саму роботу для Traefik, Caddy та Nginx і передає групи та ролі користувача в заголовках запиту.
Крок 1: Створення додатка в Casdoor
-
У організації ваших користувачів додайте додаток (або відкрийте наявний).
-
Додайте зворотний виклик OAuth2 Proxy до Redirect URLs:
https://app.example.com/oauth2/callback -
На вкладці OIDC/OAuth встановіть:
- Token format:
JWT-Standard - Token group format:
Name (group), щоб групи надходили якdevs, а не якmy-org/devs
- Token format:
-
Збережіть і запам'ятайте Client ID та Client secret.
Чому JWT-Standard: із форматом за замовчуванням JWT користувач, чия електронна пошта не підтверджена, не може увійти (OAuth2 Proxy відхиляє email_verified: false, а користувачі, створені адміністратором, зазвичай мають непідтверджену електронну пошту), і твердження roles містить цілі об'єкти ролей, а не назви ролей. Див. Що надсилає Casdoor.
Крок 2: Налаштування OAuth2 Proxy
Створіть oauth2-proxy.cfg:
provider = "oidc"
oidc_issuer_url = "https://door.example.com"
client_id = "<client ID>"
client_secret = "<client secret>"
redirect_url = "https://app.example.com/oauth2/callback"
scope = "openid email profile"
email_domains = ["*"]
cookie_secret = "<random secret>"
http_address = "0.0.0.0:4180"
upstreams = ["http://127.0.0.1:8080"]
# Let in only members of the Casdoor group "devs"
oidc_groups_claim = "groups"
allowed_groups = ["devs"]
oidc_issuer_url— це URL-адреса Casdoor без кінцевого слеша. Вона повинна точно відповідатиissuer, показаному наhttps://door.example.com/.well-known/openid-configuration. Casdoor формує issuer зoriginуconf/app.confабо з хоста запиту, якщоoriginпорожній; якщо вони відрізняються, OAuth2 Proxy видасть помилкуissuer did not match.cookie_secretповинен мати довжину 16, 24 або 32 байти, наприклад, результат виконанняopenssl rand -base64 32 | tr -- '+/' '-_'.- Збережіть область
profile: Casdoor повертає групи та ролі зі своєї точки userinfo лише тоді, коли надано доступprofile. upstreams— це ваш додаток.
Запустіть його:
oauth2-proxy --config oauth2-proxy.cfg
Відкрийте https://app.example.com. Після входу через Casdoor учасники групи devs отримають доступ до додатка, а всі інші отримають 403 Forbidden.
Обмеження доступу за роллю натомість
Щоб перевіряти роль Casdoor замість групи, прочитайте твердження roles:
oidc_groups_claim = "roles"
allowed_groups = ["admin"]
allowed_groups тоді міститиме назви ролей без організації.
Перевірка даних, отриманих OAuth2 Proxy
Після входу відкрийте https://app.example.com/oauth2/userinfo. Там показано групи, які витягнув OAuth2 Proxy:
{"user":"d1a5f427-...","email":"alice@example.com","groups":["devs"],"preferredUsername":"alice"}
Якщо groups порожнє, у користувача немає жодної групи чи ролі в Casdoor, або ім'я твердження неправильне. Якщо воно містить довгі JSON-рядки, такі як {"owner":"my-org","name":"admin",...}, додаток все ще використовує формат за замовчуванням JWT з oidc_groups_claim = "roles"; змініть формат на JWT-Standard.
Що надсилає Casdoor
Те, як групи та ролі користувача потрапляють до OAuth2 Proxy, залежить від Token format додатка:
| Token format | groups | roles | Unverified email |
|---|---|---|---|
JWT-Standard | from userinfo, group names | from userinfo, role names | signs in |
JWT-Custom | in the token if Groups is in Token fields | in the token if you add a token attribute roles (see below) | signs in |
JWT (default) | in the token | role objects, not usable for allowed_groups | rejected |
JWT-Empty | in the token | from userinfo, role names | signs in |
У режимі JWT-Standard сам токен містить лише стандартні OIDC-твердження. OAuth2 Proxy шукає будь-яке відсутнє в токені твердження на точці userinfo Casdoor, тому groups та roles все одно надходять, один раз на сесію входу.
Token group format контролює значення груп у всіх форматах: ID (за замовчуванням) дає my-org/devs, Name дає devs, а Path дає my-org/parent/devs для вкладених груп.
Щоб розмістити назви ролей у самому токені, використовуйте JWT-Custom і додайте рядок до Token attributes:
| Name | Category | Value | Type |
|---|---|---|---|
roles | Existing Field | Roles | Array |
Якщо поле Token fields не порожнє, воно також обмежує те, що повертає точка userinfo (див. Token fields). Включіть Groups (і Roles, якщо ви читаєте ролі з userinfo), або залиште його порожнім.
Якщо вам потрібно залишити формат за замовчуванням JWT, додайте insecure_oidc_allow_unverified_email = true, щоб користувачі з непідтвердженою електронною поштою могли входити, і обмежуйте доступ тільки за groups.
Передача користувача до вашого додатка
OAuth2 Proxy додає ці заголовки до пересилаваних запитів (pass_user_headers, увімкнено за замовчуванням):
| Header | Value |
|---|---|
X-Forwarded-User | Casdoor user ID (the sub claim) |
X-Forwarded-Preferred-Username | Ім'я користувача Casdoor, напр. alice |
X-Forwarded-Email | Email address |
X-Forwarded-Groups | Groups (or roles), comma separated |
Переконайтеся, що ваш додаток доступний лише через OAuth2 Proxy, інакше будь-хто зможе надсилати ці заголовки напряму.
Щоб використовувати OAuth2 Proxy як endpoint forward-auth для Nginx (auth_request), Caddy (forward_auth) або Traefik (forwardAuth) замість реверс-проксі, спрямуйте проксі на його endpoint /oauth2/auth; див. Integrations у документації OAuth2 Proxy.
Усунення несправностей
| Symptom | Cause and fix |
|---|---|
issuer did not match the issuer returned by provider at startup | oidc_issuer_url differs from the issuer in Casdoor's discovery document. Set origin in Casdoor's conf/app.conf to its public URL and use the same value here. |
500 after sign-in, log says email in id_token ... isn't verified | The application uses the default JWT format and the user's email is not verified. Switch to JWT-Standard, or set insecure_oidc_allow_unverified_email = true. |
403 Forbidden after sign-in | The user is not in allowed_groups. Open /oauth2/userinfo to see what OAuth2 Proxy received and compare it with Token group format. |
Casdoor shows Redirect URI: ... doesn't exist in the allowed Redirect URI list | Add https://app.example.com/oauth2/callback to the application's Redirect URLs. |