Создать OIDC-приложение в Yandex Identity Hub для интеграции с NetBird

Статья создана

Улучшена

Обновлена 17 июня 2026 г.

Подготовьте облако к работе
- Необходимые платные ресурсы
- Перед началом работы
Создайте OIDC-приложение
- Настройте OIDC-атрибуты пользователя
Создайте пул пользователей и добавьте в него пользователей
Настройте интеграцию
Убедитесь в корректной работе приложения
Возможные ошибки
Как удалить созданные ресурсы

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

В этом руководстве вы создадите OIDC-приложение и пул пользователей в Yandex Identity Hub, получите Client ID, секрет приложения и URL с конфигурацией, а затем настроите внешний OIDC-провайдер в NetBird Dashboard.

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

Чтобы дать пользователям вашей организации доступ в NetBird:

Если созданные ресурсы вам больше не нужны, удалите их.

Подготовьте облако к работе

Зарегистрируйтесь в Yandex Cloud и создайте платежный аккаунт:

Перейдите в консоль управления, затем войдите в Yandex Cloud или зарегистрируйтесь.
На странице Yandex Cloud Billing убедитесь, что у вас подключен платежный аккаунт, и он находится в статусе ACTIVE или TRIAL_ACTIVE. Если платежного аккаунта нет, создайте его и привяжите к нему облако.

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

Подробнее об облаках и каталогах.

Необходимые платные ресурсы

В стоимость поддержки инфраструктуры входит плата за использование OIDC-приложения (тарифы Yandex Identity Hub).

Перед началом работы

Убедитесь, что:

у вас есть доступ к Yandex Identity Hub с правами на создание OIDC-приложений и пулов пользователей;
развернут self-hosted NetBird, с доступом администратора к NetBird Dashboard;
известен публичный URL NetBird Dashboard, например https://netbird.example.com;
пользователи, которые должны входить в NetBird, добавлены в организацию или для них созданы локальные учетные записи в пуле пользователей.

Примечание

В примерах ниже используется адрес NetBird https://netbird.example.com. Замените его на адрес вашего экземпляра NetBird.

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

Интерфейс Cloud Center

CLI

Войдите в сервис Yandex Identity Hub.
На панели слева выберите Приложения.
Нажмите кнопку Создать приложение и в открывшемся окне:
1. Выберите метод единого входа (SSO) OIDC (OpenID Connect).
2. В поле Имя укажите netbird-oidc-app.
3. В поле Каталог выберите каталог, в котором будет создан OAuth-клиент для приложения.
4. (Опционально) В поле Описание укажите описание, например OIDC-приложение для интеграции с NetBird.
5. Нажмите Создать приложение.

Если у вас еще нет интерфейса командной строки Yandex Cloud (CLI), установите и инициализируйте его.

По умолчанию используется каталог, указанный при создании профиля CLI. Чтобы изменить каталог по умолчанию, используйте команду yc config set folder-id <идентификатор_каталога>. Также для любой команды вы можете указать другой каталог с помощью параметров --folder-name или --folder-id. Если вы обращаетесь к ресурсу по имени, поиск будет выполнен в каталоге по умолчанию. Если вы обращаетесь к ресурсу по идентификатору, поиск будет выполнен глобально — во всех каталогах с учетом прав доступа.

Создайте OAuth-клиент:
```
yc iam oauth-client create \
  --name netbird-oauth-client
```
Где --name — имя OAuth-клиента.

Результат:
```
id: aje9rrbpcndp********
name: netbird-oauth-client
folder_id: b1g07hj5r6i4********
status: ACTIVE
```
Где id — идентификатор созданного OAuth-клиента. Сохраните его значение — оно понадобится для создания OIDC-приложения и секрета.

Создайте секрет для OAuth-клиента:

yc iam oauth-client-secret create \
  --oauth-client-id <идентификатор_OAuth-клиента>

Результат:

oauth_client_secret:
  id: ajeedld61h87********
  oauth_client_id: aje9rrbpcndp********
  masked_secret: yccs__ecf960********
  created_at: "2026-06-11T17:22:20.955Z"
secret_value: yccs__ecf9609df********

Где secret_value — секрет для OAuth-клиента. Сохраните его значение — оно понадобится для настройки NetBird.

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

yc organization-manager idp application oauth application create \
  --organization-id <идентификатор_организации> \
  --name netbird-oidc-app \
  --description "OIDC-приложение для интеграции с NetBird" \
  --client-id <идентификатор_OAuth-клиента> \
  --group-distribution-type none

Где:

--organization-id — идентификатор организации, в которой нужно создать OIDC-приложение.
--client-id — идентификатор OAuth-клиента, созданного на предыдущем шаге.
--group-distribution-type — значение none, так как в базовом сценарии интеграции NetBird группы пользователей не передаются.

Результат:

id: ek0o663g4rs2********
name: netbird-oidc-app
organization_id: bpf2c65rqcl8********
group_claims_settings:
  group_distribution_type: NONE
client_grant:
  client_id: ajeqqip130i1********
status: ACTIVE
created_at: "2025-10-21T10:51:28.790866Z"
updated_at: "2025-10-21T12:37:19.274522Z"

Сохраните идентификатор созданного OIDC-приложения.

Настройте OIDC-атрибуты пользователя

Для NetBird обычно используются стандартные атрибуты (scopes):

Минимально необходимый набор: openid, email, profile.

Возможные атрибуты:

openid — идентификатор пользователя. Обязательный атрибут.
profile — дополнительная информация о пользователе: имя, фамилия, аватар.
email — адрес электронной почты пользователя.
address — место жительства пользователя.
phone — номер телефона пользователя.
groups — группы пользователей в организации.

Интерфейс Cloud Center

CLI

Войдите в сервис Yandex Identity Hub.
На панели слева выберите Приложения и выберите приложение netbird-oidc-app.
Справа сверху нажмите Редактировать.
В поле Атрибуты пользователей укажите рекомендуемый набор scopes: openid, profile, email.
Нажмите Сохранить.

Если у вас еще нет интерфейса командной строки Yandex Cloud (CLI), установите и инициализируйте его.

Обновите OAuth-клиент, указав рекомендуемый набор scopes:
```
yc iam oauth-client update \
  --id <идентификатор_OAuth-клиента> \
  --scopes openid,profile,email
```
Где:
- --id — идентификатор OAuth-клиента, созданного ранее.
- --scopes — набор атрибутов пользователей, которые будут доступны NetBird. В примере указан рекомендуемый набор:
  - openid — идентификатор пользователя. Обязательный атрибут;
  - profile — дополнительная информация о пользователе: имя, фамилия, аватар;
  - email — адрес электронной почты пользователя.
Обновите OIDC-приложение, указав те же атрибуты:
```
yc organization-manager idp application oauth application update \
  --id <идентификатор_приложения> \
  --authorized-scopes openid,profile,email
```
Где:
- --id — идентификатор OIDC-приложения, созданного ранее.
- --authorized-scopes — атрибуты, которые были указаны при обновлении OAuth-клиента.

Создайте пул пользователей и добавьте в него пользователей

Пул пользователей в Yandex Identity Hub определяет, кто может аутентифицироваться в приложении. В этом руководстве используются локальные пользователи. Если подходящий пул уже существует, используйте его и переходите к следующему разделу.

Создайте пул пользователей

Интерфейс Cloud Center

CLI

Войдите в сервис Yandex Identity Hub.
На панели слева выберите Пулы пользователей.
В правом верхнем углу страницы нажмите Создать пул пользователей.
Задайте имя пула, например netbird-users, и при необходимости описание. Имя должно быть уникальным в рамках организации и соответствовать требованиям:
- длина — от 1 до 63 символов;
- может содержать строчные буквы латинского алфавита, цифры и дефисы;
- первый символ — буква, последний — не дефис.
В поле Домен по умолчанию укажите домен по умолчанию для пользователей пула. Этот домен будет использоваться, если к пулу не привязаны другие домены.
(Опционально) Добавьте метки для организации ресурсов:
- Нажмите Добавить.
- Введите метку в формате <ключ>: <значение>.
- Нажмите Enter.
(Опционально) В поле Данные, доступные для редактирования выберите пользовательские настройки, доступные для изменения на портале Мой аккаунт. По умолчанию разрешено управление паролем.
В поле Срок жизни сессии задайте период времени, в течение которого будут действительны сессии пользователя и не будет требоваться повторная аутентификация в Yandex Identity Hub.
Нажмите Создать пул пользователей.

Если у вас еще нет интерфейса командной строки Yandex Cloud (CLI), установите и инициализируйте его.

Создайте пул пользователей:

yc organization-manager idp userpool create \
  --organization-id <идентификатор_организации> \
  --userpool-name netbird-users \
  --description "Пул пользователей для входа в NetBird" \
  --default-subdomain <домен_по_умолчанию>

Где --default-subdomain — домен, который будет использоваться для логинов пользователей, если к пулу не привязаны другие домены.

Сохраните идентификатор созданного пула пользователей.

Добавьте пользователей в пул

Добавьте в пул всех пользователей, которым нужен доступ в NetBird. Пул поддерживает два типа пользователей:

Локальные пользователи Yandex Identity Hub — создаются и управляются внутри Yandex Identity Hub. Подходят для сотрудников и сервисных учетных записей, которым не требуется внешний IdP. Добавить таких пользователей можно вручную, через приглашение или из списка пользователей организации.
Пользователи с аккаунтом на Яндексе — входят с помощью Яндекс ID. Подходят, если организация использует учетные записи Яндекса для доступа.

Добавьте пользователей или группы в OIDC-приложение

Чтобы пользователи из пула могли входить в NetBird через созданное OIDC-приложение, явно добавьте в него нужных пользователей или группы пользователей.

Примечание

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

Интерфейс Cloud Center

CLI

Войдите в сервис Yandex Identity Hub.
На панели слева выберите Приложения и выберите приложение netbird-oidc-app.
Перейдите на вкладку Пользователи и группы.
Нажмите Добавить пользователей.
В открывшемся окне выберите нужных пользователей или группы пользователей, например, созданный пул netbird-users или пользователей Яндекс ID.
Нажмите Добавить.

Если у вас еще нет интерфейса командной строки Yandex Cloud (CLI), установите и инициализируйте его.

Получите идентификатор пользователя или группы пользователей.

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

yc organization-manager idp application oauth application add-assignments \
  --id <идентификатор_приложения> \
  --subject-id <идентификатор_пользователя_или_группы>

Совет

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

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

Чтобы настроить интеграцию NetBird с созданным OIDC-приложением, выполните настройки на стороне Yandex Identity Hub и на стороне NetBird.

Получите параметры подключения OIDC-приложения

Интерфейс Cloud Center

CLI

Войдите в сервис Yandex Identity Hub.
На панели слева выберите Приложения и выберите приложение netbird-oidc-app.
На вкладке Обзор в блоке Конфигурация поставщика удостоверений (IdP) разверните секцию Дополнительные атрибуты и сохраните:
- ClientID — Client ID.
- OpenID Configuration — URL OpenID Connect Discovery.
В блоке Секреты приложения нажмите кнопку Добавить секрет и в открывшемся окне:
1. (Опционально) Добавьте произвольное описание создаваемого секрета.
2. Нажмите Создать.
В окне отобразится сгенерированный секрет приложения. Сохраните полученное значение.

Важно

После обновления или закрытия страницы с информацией о приложении посмотреть секрет будет невозможно.

Если вы закрыли или обновили страницу, не сохранив сгенерированный секрет, используйте кнопку Добавить секрет, чтобы создать новый.

Чтобы удалить секрет, в списке секретов на странице OIDC-приложения в строке с нужным секретом нажмите значок и выберите Удалить.

Если у вас еще нет интерфейса командной строки Yandex Cloud (CLI), установите и инициализируйте его.

Получите информацию о приложении:
```
yc organization-manager idp application oauth application get <идентификатор_приложения>
```
Сохраните значение client_id из блока client_grant.
Получите URL issuer:
```
yc organization-manager idp application oauth application get <идентификатор_приложения> \
  --format json | jq -r '.client_grant.issuer_uri'
```
Сохраните полученное значение. NetBird обычно использует именно issuer URL, а необходимые endpoints получает автоматически через discovery. Если ваша версия NetBird ожидает discovery URL, используйте значение из поля OpenID Configuration в интерфейсе Cloud Center.

Для Yandex Identity Hub issuer URL имеет вид https://auth.yandex.cloud. Discovery endpoint доступен по адресу https://auth.yandex.cloud/.well-known/openid-configuration.
Если секрет не был сохранен ранее, создайте новый:
```
yc iam oauth-client-secret create \
  --oauth-client-id <идентификатор_OAuth-клиента>
```
Сохраните значение secret_value.

Настройте Redirect URI

NetBird использует callback URL для завершения OIDC-аутентификации. Обычно он имеет вид:

https://<домен_NetBird>/oauth2/callback

Например:

https://netbird.example.com/oauth2/callback

Укажите этот адрес в настройках OAuth-клиента. Если NetBird показывает callback URL в интерфейсе настройки провайдера, используйте именно это значение.

Интерфейс Cloud Center

CLI

Войдите в сервис Yandex Identity Hub.
На панели слева выберите Приложения и выберите приложение netbird-oidc-app.
Справа сверху нажмите Редактировать.

В поле Redirect URI укажите:

https://<домен_NetBird>/oauth2/callback

Нажмите Сохранить.

Если у вас еще нет интерфейса командной строки Yandex Cloud (CLI), установите и инициализируйте его.

Обновите OAuth-клиент, указав Redirect URI:

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

Важно

Redirect URI в Yandex Identity Hub должен полностью совпадать с callback URL, который использует NetBird: схема, домен, путь и наличие или отсутствие завершающего / должны быть одинаковыми.

Настройте внешний OIDC-провайдер в NetBird Dashboard

Примечание

Подробнее о настройке внешних Identity Provider в NetBird читайте в официальной документации NetBird.

Откройте NetBird Dashboard по адресу вашего экземпляра, например https://netbird.example.com, и войдите под учетной записью администратора.
Перейдите в раздел Settings → Identity Providers.
Нажмите Add Identity Provider или аналогичную кнопку в вашей версии NetBird.
Выберите тип провайдера OpenID Connect или Generic OIDC.
Заполните параметры подключения:
- Name — например Yandex Cloud Identity Hub.
- Client ID — значение client_id, полученное в Yandex Identity Hub.
- Client Secret — секрет OIDC-приложения.
- Issuer URL или Authority — issuer URL, полученный в Yandex Identity Hub.
Если NetBird показывает callback URL, убедитесь, что он совпадает со значением, указанным в Redirect URI OIDC-приложения.
Сохраните настройки.
Если в NetBird настроено несколько провайдеров, при необходимости назначьте созданный провайдер провайдером по умолчанию.
Перезапустите сервисы NetBird, чтобы изменения вступили в силу. Например, для Docker Compose:
```
docker compose down
docker compose up -d
```

Примечание

В зависимости от версии NetBird названия разделов и полей могут незначительно отличаться. Если интерфейс вашей версии не позволяет указать отдельные endpoints, достаточно задать issuer URL: NetBird получит authorization_endpoint, token_endpoint, userinfo_endpoint и jwks_uri автоматически.

Убедитесь в корректной работе приложения

Выйдите из NetBird Dashboard, если вы уже авторизованы.
Откройте страницу входа в NetBird.
Нажмите кнопку входа через настроенный OIDC-провайдер, например Continue with Yandex Cloud.
На странице аутентификации Yandex Cloud войдите под пользователем, который:
- добавлен в нужный пул пользователей;
- добавлен в OIDC-приложение напрямую или через группу.
Убедитесь, что после успешной аутентификации браузер возвращается в NetBird, а пользователь получает доступ к Dashboard.
Если в NetBird отображается профиль пользователя, проверьте, что вход выполнен под ожидаемой учетной записью и корректно передается адрес электронной почты.

Возможные ошибки

`redirect_uri mismatch`

Причина: callback URL в NetBird не совпадает со значением Redirect URI в OAuth-клиенте.

Что проверить:

используется один и тот же URL в NetBird и в Yandex Identity Hub;
совпадают схема https, домен, путь /oauth2/callback и завершающий /, если он есть.

`invalid_client`

Причина: в NetBird указан неверный Client ID или Client Secret.

Что проверить:

в NetBird указан актуальный client_id созданного OIDC-приложения;
секрет был сохранен корректно и не был заменен новым без обновления настроек NetBird.

`invalid_scope`

Причина: NetBird запрашивает scopes, которые не разрешены для приложения.

Что проверить:

в OAuth-клиенте и OIDC-приложении разрешены openid, email, profile;
в NetBird не указаны дополнительные scopes, которые не настроены в Yandex Identity Hub.

Если ошибка сохраняется, начните с минимального набора scopes: openid profile email, а затем добавляйте остальные по необходимости.

Что проверить:

пользователь добавлен в пул пользователей;
пользователь активирован;
пользователь или его группа добавлены в OIDC-приложение;
у пользователя заполнен адрес электронной почты, если NetBird использует claim email.

NetBird не принимает токен

Что проверить:

значение issuer в токене совпадает с issuer URL, указанным в NetBird;
значение aud соответствует Client ID приложения;
NetBird Management service может обращаться к JWKS endpoint провайдера;
NetBird использует правильный claim пользователя: sub.

Как удалить созданные ресурсы

Чтобы перестать платить за созданные ресурсы удалите OIDC-приложение.

Создать OIDC-приложение в Yandex Identity Hub для интеграции с NetBird

Подготовьте облако к работеПодготовьте облако к работе

Необходимые платные ресурсыНеобходимые платные ресурсы

Перед началом работыПеред началом работы

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

Настройте OIDC-атрибуты пользователяНастройте OIDC-атрибуты пользователя

Создайте пул пользователей и добавьте в него пользователейСоздайте пул пользователей и добавьте в него пользователей

Создайте пул пользователейСоздайте пул пользователей

Добавьте пользователей в пулДобавьте пользователей в пул

Добавьте пользователей или группы в OIDC-приложениеДобавьте пользователей или группы в OIDC-приложение

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

Получите параметры подключения OIDC-приложенияПолучите параметры подключения OIDC-приложения

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

Настройте внешний OIDC-провайдер в NetBird DashboardНастройте внешний OIDC-провайдер в NetBird Dashboard

Убедитесь в корректной работе приложенияУбедитесь в корректной работе приложения

Возможные ошибкиВозможные ошибки

redirect_uri mismatchredirect_uri mismatch

invalid_clientinvalid_client

invalid_scopeinvalid_scope

Пользователь не может войтиПользователь не может войти

NetBird не принимает токенNetBird не принимает токен

Как удалить созданные ресурсыКак удалить созданные ресурсы

Была ли статья полезна?

Подготовьте облако к работе

Необходимые платные ресурсы

Перед началом работы

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

Настройте OIDC-атрибуты пользователя

Создайте пул пользователей и добавьте в него пользователей

Создайте пул пользователей

Добавьте пользователей в пул

Добавьте пользователей или группы в OIDC-приложение

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

Получите параметры подключения OIDC-приложения

Настройте Redirect URI

Настройте внешний OIDC-провайдер в NetBird Dashboard

Убедитесь в корректной работе приложения

Возможные ошибки

`redirect_uri mismatch`

`invalid_client`

`invalid_scope`

Пользователь не может войти

NetBird не принимает токен

Как удалить созданные ресурсы