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

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​

  1. У організації ваших користувачів додайте додаток (або відкрийте наявний).

  2. Додайте зворотний виклик OAuth2 Proxy до Redirect URLs:

    https://app.example.com/oauth2/callback
  3. На вкладці OIDC/OAuth встановіть:

    • Token format: JWT-Standard
    • Token group format: Name (group), щоб групи надходили як devs, а не як my-org/devs
  4. Збережіть і запам'ятайте 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 formatgroupsrolesUnverified email
JWT-Standardfrom userinfo, group namesfrom userinfo, role namessigns in
JWT-Customin the token if Groups is in Token fieldsin the token if you add a token attribute roles (see below)signs in
JWT (default)in the tokenrole objects, not usable for allowed_groupsrejected
JWT-Emptyin the tokenfrom userinfo, role namessigns 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:

NameCategoryValueType
rolesExisting FieldRolesArray

Якщо поле Token fields не порожнє, воно також обмежує те, що повертає точка userinfo (див. Token fields). Включіть Groups (і Roles, якщо ви читаєте ролі з userinfo), або залиште його порожнім.

Якщо вам потрібно залишити формат за замовчуванням JWT, додайте insecure_oidc_allow_unverified_email = true, щоб користувачі з непідтвердженою електронною поштою могли входити, і обмежуйте доступ тільки за groups.

Передача користувача до вашого додатка​

OAuth2 Proxy додає ці заголовки до пересилаваних запитів (pass_user_headers, увімкнено за замовчуванням):

HeaderValue
X-Forwarded-UserCasdoor user ID (the sub claim)
X-Forwarded-Preferred-UsernameІм'я користувача Casdoor, напр. alice
X-Forwarded-EmailEmail address
X-Forwarded-GroupsGroups (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.

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

SymptomCause and fix
issuer did not match the issuer returned by provider at startupoidc_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 verifiedThe 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-inThe 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 listAdd https://app.example.com/oauth2/callback to the application's Redirect URLs.