Использовать OIDC-приложение и OAuth2 Proxy для настройки единого входа в приложения, не поддерживающие SSO

Не в каждом приложении реализована встроенная поддержка технологии единого входа (SSO). При этом иногда возникает потребность в настройке аутентификации пользователей в них с помощью Yandex Identity Hub.

В данном руководстве вы воспользуетесь утилитой OAuth2 Proxy в связке с прокси-сервером, чтобы настроить интеграцию простейшего приложения с Yandex Identity Hub и организовать доступ к этому приложению только для заданных пользователей Identity Hub с помощью технологии единого входа по стандарту OpenID Connect (OIDC).

В качестве прокси-сервера в данном руководстве используется nginx, а в качестве тестового приложения — статическая HTML-страница. Чтобы ваши пользователи Identity Hub могли получить доступ к тестовому приложению, вы создадите и настроите OIDC-приложение. Дополнительно вам потребуется виртуальная машина Yandex Compute Cloud, на которой будут запущены nginx и OAuth2 Proxy, а также размещено тестовое приложение. Кроме этого, для реализации защищенного доступа к тестовому приложению вам понадобятся доменное имя и выпущенный для него SSL-сертификат.

Управлять OIDC-приложениями может пользователь, которому назначена роль organization-manager.oauthApplications.admin или выше.

Чтобы настроить доступ в приложение для ваших пользователей Identity Hub:

1. Создайте и настройте OIDC-приложение в Identity Hub.
2. Подготовьте виртуальную машину с тестовым приложением.
3. Настройте интеграцию.
4. Убедитесь в корректной работе интеграции.

Создайте и настройте OIDC-приложение в Identity HubСоздайте и настройте OIDC-приложение в Identity Hub

Создайте OIDC-приложениеСоздайте OIDC-приложение

Настройте Redirect URIНастройте Redirect URI

yc iam oauth-client update \
  --id <идентификатор_OAuth-клиента> \
  --redirect-uris "https://<ваш_домен>/oauth2/callback"

  id: ajeiu3otac08********
  name: website-oauth-client
  redirect_uris:
    - https://example.com/oauth2/callback
  scopes:
    - email
    - openid
    - profile
  folder_id: b1gkd6dks6i1********
  status: ACTIVE

Добавьте пользователяДобавьте пользователя

Чтобы ваши пользователи Identity Hub могли проходить аутентификацию в тестовом приложении с помощью протокола OIDC, необходимо явно добавить в OIDC-приложение нужных пользователей и/или группы пользователей.

Добавьте пользователя в приложение:

Подготовьте виртуальную машину с тестовым приложениемПодготовьте виртуальную машину с тестовым приложением

В данном руководстве вы развернете тестовое приложение, а также настроите утилиты nginx и OAuth2 Proxy на виртуальной машине под управлением ОС Ubuntu 24.04.

Подготовьте окружение Yandex CloudПодготовьте окружение Yandex Cloud

Прежде чем создавать виртуальную машину, убедитесь, что в вашем каталоге есть облачная сеть и подсеть. При необходимости воспользуйтесь следующими инструкциями, чтобы создать их:

• Создать облачную сеть
• Создать подсеть

Кроме того, в вашей облачной сети создайте группу безопасности, разрешающую входящий TCP-трафик для портов 22, 80 и 443, а также любой исходящий трафик.

Создайте виртуальную машинуСоздайте виртуальную машину

  yc compute instance create \
    --name my-nginx-vm \
    --zone <зона_доступности_ВМ> \
    --create-boot-disk image-folder-id=standard-images,image-family=ubuntu-2404-lts,auto-delete=true \
    --ssh-key <путь_к_открытому_SSH-ключу> \
    --network-interface subnet-name=<имя_подсети>,nat-ip-version=ipv4,security-group-ids=<идентификатор_группы_безопасности>

done (29s)
id: epdvqa1rtvjj********
folder_id: b1gt6g8ht345********
created_at: "2026-01-22T12:03:52Z"
name: my-nginx-vm
zone_id: ru-central1-b
platform_id: standard-v2
resources:
  memory: "2147483648"
  cores: "2"
  core_fraction: "100"
status: RUNNING
metadata_options:
  gce_http_endpoint: ENABLED
  aws_v1_http_endpoint: ENABLED
  gce_http_token: ENABLED
  aws_v1_http_token: DISABLED
boot_disk:
  mode: READ_WRITE
  device_name: epdbi403v2or********
  auto_delete: true
  disk_id: epdbi403v2or********
network_interfaces:
  - index: "0"
    mac_address: d0:0d:1f:d2:83:be
    subnet_id: e2lqsms4cdl3********
    primary_v4_address:
      address: 192.168.2.31
      one_to_one_nat:
        address: 89.169.***.***
        ip_version: IPV4
    security_group_ids:
      - enp378h7n0cm********
serial_port_settings:
  ssh_authorization: OS_LOGIN
gpu_settings: {}
fqdn: epdvqa1rtvjj********.auto.internal
scheduling_policy: {}
network_settings:
  type: STANDARD
placement_policy: {}
hardware_generation:
  legacy_features:
    pci_topology: PCI_TOPOLOGY_V2
application: {}

Настройте интеграциюНастройте интеграцию

Создайте тестовое приложение и настройте nginxСоздайте тестовое приложение и настройте nginx

1. Убедитесь, что для вашего домена создана ресурсная A-запись, указывающая на публичный IP-адрес созданной виртуальной машины. Если такой ресурсной записи нет, создайте ее.

   Примечание

   Если управление вашим доменом делегировано сервису Yandex Cloud DNS, для создания ресурсной записи воспользуйтесь инструкцией Создать ресурсную запись. Если доменом управляет сторонний провайдер, воспользуйтесь документацией этого провайдера или обратитесь в его службу поддержки.

2. Подключитесь по SSH к созданной виртуальной машине.

3. Установите nginx:

   sudo apt update && sudo apt upgrade -y
   sudo apt install nginx -y
   

4. Создайте файлы тестового приложения:

   1. Сохраните имя вашего домена в переменную окружения:

      export MY_DOMAIN="<имя_домена>"
      

      Где <имя_домена> — имя вашего домена, для которого создана ресурсная запись, указывающая на публичный IP-адрес текущей виртуальной машины. Например: example.com.

   2. Создайте директорию и основную HTML-страницу тестового приложения:

      sudo mkdir /var/www/$MY_DOMAIN
      sudo touch /var/www/$MY_DOMAIN/index.html \
        && echo "<h1>Your Web application that is available to your Identity Hub users only</h1>" | sudo tee -a /var/www/$MY_DOMAIN/index.html
      

5. Создайте самоподписанный SSL-сертификат для вашего домена. Для этого выполните команду и введите значения, следуя инструкциям на экране:

   sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout /etc/ssl/private/my-private.key -out /etc/ssl/certs/my-certificate.crt
   

   В результате будет создан самоподписанный SSL-сертификат, которого достаточно для тестирования предлагаемого решения.

   Совет

   Чтобы при использовании приложения браузер не выдавал предупреждение о проблемах с безопасностью, используйте SSL-сертификат, выданный удостоверяющим центром.

   Например, чтобы создать сертификат от Let's Encrypt и сохранить его и закрытый ключ на свой компьютер, воспользуйтесь инструкциями Добавить сертификат от Let's Encrypt® и Получить содержимое сертификата от Let's Encrypt.

6. Задайте настройки nginx:

   1. С помощью текстового редактора nano откройте файл конфигурации nginx:

      sudo nano /etc/nginx/conf.d/default.conf
      

   2. Замените содержимое открытого файла следующим:

      server {
          listen 80;
          listen [::]:80;
          server_name <имя_домена>;
      
          return 301 https://$server_name$request_uri;
      }
      
      server {
          listen 443 ssl;
          listen [::]:443 ssl;
          server_name <имя_домена>;
      
          location /oauth2/ {
              proxy_pass       http://127.0.0.1:4180;
              proxy_set_header Host                    $host;
              proxy_set_header X-Real-IP               $remote_addr;
              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:4180;
              proxy_set_header Host             $host;
              proxy_set_header X-Real-IP        $remote_addr;
              proxy_set_header X-Forwarded-Uri  $request_uri;
              # nginx auth_request includes headers but not body
              proxy_set_header Content-Length   "";
              proxy_pass_request_body           off;
          }
      
          # Пути к вашим сертификату и ключу
          ssl_certificate /etc/ssl/certs/my-certificate.crt;
          ssl_certificate_key /etc/ssl/private/my-private.key;
      
          # Рекомендуемые настройки безопасности
          ssl_protocols TLSv1.2 TLSv1.3;
          ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384;
          ssl_prefer_server_ciphers on;
      
          access_log /var/log/nginx/$server_name.access.log;
          error_log /var/log/nginx/$server_name.error.log;
      
          location / {
      
              auth_request /oauth2/auth;
              error_page 401 =403 /oauth2/sign_in;
      
              # pass information via X-User and X-Email headers to backend,
              # requires running with --set-xauthrequest flag
              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;
              proxy_set_header X-Email $email;
      
              root /var/www/$server_name/;
              index index.html;
      
              try_files $uri $uri/ =404;
          }
      
      }
      

      Где <имя_домена> — имя вашего домена, для которого создана ресурсная запись, указывающая на публичный IP-адрес текущей виртуальной машины. Например: example.com.

      Важно

      Если вы используете SSL-сертификат, выданный удостоверяющим центром, скопируйте файлы сертификата и закрытого ключа на виртуальную машину и укажите локальные пути к этим файлам соответственно в полях ssl_certificate и ssl_certificate_key файла конфигурации.

7. Примените обновленные настройки nginx:

   sudo nginx -s reload
   

Настройте OAuth2 ProxyНастройте OAuth2 Proxy

1. Подключитесь по SSH к созданной виртуальной машине.

2. Установите актуальную версию утилиты OAuth2 Proxy удобным вам способом.

   В приведенном примере используется установка путем скачивания архива с исполняемым файлом. На момент написания настоящего руководства актуальной являлась версия v7.14.2:

   sudo wget https://github.com/oauth2-proxy/oauth2-proxy/releases/download/v7.14.2/oauth2-proxy-v7.14.2.linux-amd64.tar.gz
   sudo tar -xvf oauth2-proxy-v7.14.2.linux-amd64.tar.gz -C /usr/bin/
   sudo chmod +x /usr/bin/oauth2-proxy-v7.14.2.linux-amd64/oauth2-proxy
   sudo rm oauth2-proxy-v7.14.2.linux-amd64.tar.gz
   

3. Задайте настройки OAuth2 Proxy:

   1. Сгенерируйте секрет cookie, который потребуется при настройке утилиты:

      dd if=/dev/urandom bs=32 count=1 2>/dev/null | base64 | tr -d -- '\n' | tr -- '+/' '-_' ; echo
      

      Сохраните полученное значение — оно понадобится позднее.

   2. С помощью текстового редактора nano откройте файл конфигурации oauth2-proxy.cfg:

      sudo nano /usr/bin/oauth2-proxy-v7.14.2.linux-amd64/oauth2-proxy.cfg
      

   3. Вставьте в файл oauth2-proxy.cfg следующую конфигурацию, подставив в нее необходимые значения:

      provider = "oidc"  # Тип провайдера
      provider_display_name = "Yandex Identity Hub" # Имя провайдера на кнопке
      reverse_proxy = true # Включение режима работы за nginx
      client_id = "<идентификатор_ClientID>" # ClientID OIDC приложения 
      client_secret = "<секрет_OIDC_приложения>" # Секрет OIDC приложения
      oidc_issuer_url = "https://auth.yandex.cloud"
      cookie_name = "_oauth2_proxy" # Имя cookie
      cookie_secret = "<секрет_cookie>"  # Сгенерированный ранее ключ cookie
      email_domains = [ "<домен_1>","<домен_2>",...,"<домен_n>" ]  # Домены, для которых разрешена аутентификация
      upstreams = [ "<адрес_вашего_приложения>" ]  # Адрес бэкенд-приложения
      http_address = "127.0.0.1:4180"  # Адрес и порт, на которых слушает oauth2-proxy
      redirect_url = "<redirect_URI>"  # URL для обратного вызова
      

      Где:

      • client_id — значение ClientID OAuth-клиента, полученное ранее при создании OIDC-приложения.

      • client_secret — значение секрета, сгенерированного в OIDC-приложении.

      • cookie_secret — секрет cookie, сгенерированный и сохраненный ранее.

      • email_domains — список доменов в адресе электронной почты, для которых будет разрешена аутентификация пользователя Identity Hub в тестовом приложении.

        Утилита OAuth2 Proxy проверяет домен электронной почты, указанной в поле Электронная почта настроек пользователя в Identity Hub (атрибут email).

        В поле email_domains укажите домен электронной почты того пользователя, которого вы добавили ранее в ваше OIDC-приложение. Если в OIDC-приложение вы добавляли группу пользователей, укажите домен электронной почты того пользователя группы, от имени которого вы будете тестировать аутентификацию. Вы можете указать несколько доменов через запятую.

        Совет

        Чтобы в тестовом приложении могли аутентифицироваться пользователи с аккаунтом на Яндексе, добавьте в список email_domains значение yandex.ru.

      • upstreams — адрес вашего приложения. Например: https://example.com/.

      • redirect_url — значение Redirect URI, которое вы задали при настройке OIDC-приложения.

4. Запустите OAuth2 Proxy:

   sudo /usr/bin/oauth2-proxy-v7.14.2.linux-amd64/oauth2-proxy \
     --config /usr/bin/oauth2-proxy-v7.14.2.linux-amd64/oauth2-proxy.cfg
   

   Совет

   Вы также можете запустить OAuth2 Proxy в фоновом режиме, например, с помощью утилиты nohup.

Убедитесь в корректной работе аутентификацииУбедитесь в корректной работе аутентификации

Чтобы убедиться в корректной работе аутентификации в тестовом приложении с помощью OIDC-приложения:

1. В браузере введите адрес вашего тестового приложения (например, https://example.com).

   Если все было настроено правильно, в браузере откроется окно аутентификации OAuth2 Proxy.

2. Нажмите кнопку Sign in with Yandex Identity Hub.

3. Пройдите аутентификацию от имени того пользователя, которого вы ранее добавили в OIDC-приложение. Если в OIDC-приложение вы добавляли группу пользователей, пройдите аутентификацию от имени пользователя, который входит в эту группу.

   Если все было настроено правильно, в браузере откроется страница с вашим тестовым приложением.

4. При попытке аутентифицироваться от имени пользователя, не добавленного в OIDC-приложение, или имеющего адрес электронной почты с доменом, отличным от разрешенных в настройках OAuth2 Proxy, ваше приложение выдаст сообщение об ошибке доступа.