Discuss with expertTry it for free
© 2026 Direct Cursus Technology L.L.C.

Creating an OIDC app in Yandex Identity Hub for integration with NetBird

Written by
Updated at July 8, 2026
View in Markdown

NetBird is a platform for establishing secure access to network resources. NetBird supports OpenID Connect authentication (OIDC) for the users of your organization to use single sign-on via Yandex Identity Hub.

In this tutorial, you will create an OIDC app and user pool in Yandex Identity Hub, get a Client ID, app secret, and configuration URL, and then configure an external OIDC provider in NetBird Dashboard.

OIDC apps can be managed by users with the organization-manager.oauthApplications.admin role or higher.

To give access to NetBird to the users of your organization:

  1. Get your cloud ready.
  2. Create an OIDC app.
  3. Create a user pool and add users to it.
  4. Set up the integration.
  5. Make sure the application works correctly.

If you no longer need the resources you created, delete them.

Get your cloud ready

Sign up for Yandex Cloud and create a billing account:

  1. Navigate to the management console and log in to Yandex Cloud or create a new account.
  2. On the Yandex Cloud Billing page, make sure you have a billing account linked and it has the ACTIVE or TRIAL_ACTIVE status. If you do not have a billing account, create one and link a cloud to it.

If you have an active billing account, you can create or select a folder for your infrastructure on the cloud page.

Learn more about clouds and folders here.

The cost of infrastructure support includes a fee for using the OIDC app (see Yandex Identity Hub pricing).

Getting started

Make sure that:

  • You have access to Yandex Identity Hub with permissions to create OIDC apps and user pools.
  • Self-hosted NetBird is deployed, with administrator access to NetBird Dashboard.
  • Public URL of NetBird Dashboard is known, e.g., https://netbird.example.com.
  • Users to log in to NetBird have been added to the organization or local accounts have been created for them in the user pool.

Note

The examples below use the following NetBird address: https://netbird.example.com. Replace it with the address of your NetBird instance.

Creating an OIDC app

  1. Log in to Yandex Identity Hub.
  2. In the left-hand panel, select  Apps.
  3. Click Create application and in the window that opens:
    1. Select the OIDC (OpenID Connect) single sign-on (SSO) method.
    2. In the Name field, specify netbird-oidc-app.
    3. In the Folder field, select the folder where you want to create an OAuth client for your app.
    4. Optionally, enter a description in the Description field, e.g., OIDC app for integration with NetBird.
    5. Click Create application.

If you do not have the Yandex Cloud CLI yet, install and initialize it.

The folder used by default is the one specified when creating the CLI profile. To change the default folder, use the yc config set folder-id <folder_ID> command. You can also specify a different folder for any command using --folder-name or --folder-id. If you access a resource by its name, the search will be limited to the default folder. If you access a resource by its ID, the search will be global, i.e., through all folders based on access permissions.

  1. Create an OAuth client:

    yc iam oauth-client create \
  --name netbird-oauth-client

    Where --name is the OAuth client name.

    Result:

    id: aje9rrbpcndp********
name: netbird-oauth-client
folder_id: b1g07hj5r6i4********
status: ACTIVE

    Where id is the new OAuth client ID. Save its value for later to create an OIDC application and secret.

  2. Create a secret for your OAuth client:

    yc iam oauth-client-secret create \
  --oauth-client-id <OAuth_client_ID>

    Result:

    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********

    Where secret_value is the secret for your OAuth client. Save its value for later to configure NetBird.

  3. Create an OIDC app:

    yc organization-manager idp application oauth application create \
  --organization-id <organization_ID> \
  --name netbird-oidc-app \
  --description "OIDC app for integration with NetBird" \
  --client-id <OAuth_client_ID> \
  --group-distribution-type none

    Where:

    • --organization-id: ID of the organization you want to create your OIDC app in.
    • --client-id: OAuth client ID created in the previous step.
    • --group-distribution-type: none because user groups are not transferred in the basic NetBird integration scenario.

    Result:

    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"

    Save the ID of the new OIDC app.

Configure user OIDC attributes

NetBird typically uses standard attributes (scopes):

Minimum required set: openid, email, profile.

Possible attributes:

  • openid: User ID. Required attribute.
  • profile: Additional user information: first name, last name, avatar.
  • email: User email address.
  • address: User home address.
  • phone: User phone number.
  • groups: User groups in the organization.
  1. Log in to Yandex Identity Hub.
  2. In the left-hand panel, navigate to Apps and select netbird-oidc-app.
  3. At the top right, click Edit.
  4. In the User attributes field, specify the recommended set of scopes: openid, profile, email.
  5. Click Save.

If you do not have the Yandex Cloud CLI yet, install and initialize it.

The folder used by default is the one specified when creating the CLI profile. To change the default folder, use the yc config set folder-id <folder_ID> command. You can also specify a different folder for any command using --folder-name or --folder-id. If you access a resource by its name, the search will be limited to the default folder. If you access a resource by its ID, the search will be global, i.e., through all folders based on access permissions.

  1. Update your OAuth client to specify the recommended set of scopes:

    yc iam oauth-client update \
  --id <OAuth_client_ID> \
  --scopes openid,profile,email

    Where:

    • --id: ID of the OAuth client you created earlier.
    • --scopes: User attributes available to NetBird: This example shows the recommended set of attributes:
      • openid: User ID. Required attribute.
      • profile: Additional user information: first name, last name, avatar.
      • email: User email address.

  2. Update the OIDC app with the same attributes:

    yc organization-manager idp application oauth application update \
  --id <app_ID> \
  --authorized-scopes openid,profile,email

    Where:

    • --id: ID of the OIDC app you created earlier.
    • --authorized-scopes: Attributes that were specified when updating the OAuth client.

Create a user pool and add users to it

A Yandex Identity Hub user pool is what determines who can authenticate to the application. This guide uses local users. If a suitable pool already exists, use it and proceed to the next section.

Create a user pool

  1. Log in to Yandex Identity Hub.

  2. In the left-hand panel, select  User pools.

  3. In the top-right corner of the page, click Create user pool.

  4. Specify a name for the pool, e.g., netbird-users, and provide an optional description. The name must be unique within the organization and follow these naming requirements:

    • It must be from 1 to 63 characters long.
    • It may contain lowercase Latin letters, numbers, and hyphens.
    • It must start with a letter and cannot end with a hyphen.

  5. In the Default domain field, specify the default domain for the users of the pool. This domain will be used if no other domains are linked to the pool.

  6. Optionally, add labels to organize your resources:

    • Click Add.
    • Enter a label in <key>: <value> format.
    • Press Enter.

  7. Optionally, in the Data available for editing field, select the user settings available for editing on the My account portal. By default, password management is allowed.

  8. In the Lifetime session field, specify a time period for user sessions to remain active before requiring reauthentication in Yandex Identity Hub.

  9. Click Create userpool.

If you do not have the Yandex Cloud CLI yet, install and initialize it.

The folder used by default is the one specified when creating the CLI profile. To change the default folder, use the yc config set folder-id <folder_ID> command. You can also specify a different folder for any command using --folder-name or --folder-id. If you access a resource by its name, the search will be limited to the default folder. If you access a resource by its ID, the search will be global, i.e., through all folders based on access permissions.

Create a user pool:

yc organization-manager idp userpool create \
  --organization-id <organization_ID> \
  --userpool-name netbird-users \
  --description "User pool for logging into NetBird" \
  --default-subdomain <default_domain>

Where --default-subdomain is the domain that will be used for user logins if no other domains are linked to the pool.

Save the ID of the new user pool.

Add users to the pool

Add to the pool all users who need access to NetBird. The pool supports two types of users:

  • Yandex Identity Hub local users. These users are created and managed within Yandex Identity Hub. Suitable for employees and service accounts not requiring an external IdP. You can add such users manually, via an invitation, or from the organization user list.
  • Users with a Yandex account. These users log in using Yandex ID. Suitable if the organization relies on Yandex accounts for access.

Add users or groups to the OIDC app

To allow the pool users to log in to NetBird via the new OIDC app, explicitly add particular users or user groups to it.

Note

Users and groups added to an OIDC application can be managed by any user with the organization-manager.oauthApplications.userAdmin role or higher.

  1. Log in to Yandex Identity Hub.
  2. In the left-hand panel, navigate to Apps and select netbird-oidc-app.
  3. Navigate to the Users and groups tab.
  4. Click Add users.
  5. In the window that opens, select users or user groups, e.g., the new netbird-users pool or Yandex ID users.
  6. Click Add.

If you do not have the Yandex Cloud CLI yet, install and initialize it.

The folder used by default is the one specified when creating the CLI profile. To change the default folder, use the yc config set folder-id <folder_ID> command. You can also specify a different folder for any command using --folder-name or --folder-id. If you access a resource by its name, the search will be limited to the default folder. If you access a resource by its ID, the search will be global, i.e., through all folders based on access permissions.

  1. Get the user ID or user group ID.

  2. Add a user or group to the application:

    yc organization-manager idp application oauth application add-assignments \
  --id <app_ID> \
  --subject-id <user_or_group_ID>

Tip

If you want to fine-tune user authentication in your applications, including authentication only from specific IP addresses, use authentication policies.

Authentication policies are a Yandex Identity Hub tool that allows you to flexibly configure access to applications by denying or allowing authentication for specific users in specific applications and/or from specific IP addresses. For more information, see Authentication policies in Yandex Identity Hub.

Set up the integration

To configure NetBird integration with the new OIDC app, perform the setup both in Yandex Identity Hub and NetBird.

Get the OIDC app connection credentials

  1. Log in to Yandex Identity Hub.

  2. In the left-hand panel, navigate to Apps and select netbird-oidc-app.

  3. Under Overview on the Identity provider (IdP) configuration tab, expand the Additional attributes section and save the following:

    • ClientID: Client ID.
    • OpenID Configuration: URL OpenID Connect Discovery.

  4. Under App secrets, click Add secret, and in the window that opens:

    1. Optionally, add a description for the new secret.
    2. Click Create.

    The window will display the generated application secret. Save this value.

    Warning

    If you refresh or close the application information page, you will not be able to view the secret again.

    If you closed or refreshed the page before saving the secret, click Add secret to create a new one.

    To delete a secret, in the list of secrets on the OIDC app page, click in the secret row and select Delete.

If you do not have the Yandex Cloud CLI yet, install and initialize it.

The folder used by default is the one specified when creating the CLI profile. To change the default folder, use the yc config set folder-id <folder_ID> command. You can also specify a different folder for any command using --folder-name or --folder-id. If you access a resource by its name, the search will be limited to the default folder. If you access a resource by its ID, the search will be global, i.e., through all folders based on access permissions.

  1. Get the app info:

    yc organization-manager idp application oauth application get <app_ID>

    Save the client_id value from the client_grant section.

  2. Get an issuer URL:

    yc organization-manager idp application oauth application get <app_ID> \
  --format json | jq -r '.client_grant.issuer_uri'

    Save this value. NetBird normally uses an issuer URL and gets the necessary endpoints automatically through discovery. If your NetBird version expects a discovery URL, use the value from the OpenID Configuration field in the Cloud Center interface.

    For Yandex Identity Hub, the issuer URL is https://auth.yandex.cloud. The discovery endpoint is available at https://auth.yandex.cloud/.well-known/openid-configuration.

  3. If no secret was saved earlier, create a new one:

    yc iam oauth-client-secret create \
  --oauth-client-id <OAuth_client_ID>

    Save secret_value.

Configure a redirect URI

NetBird uses a callback URL to complete OIDC authentication. Its typical format is:

https://<NetBird_domain>/oauth2/callback

For example:

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

Specify this address in the OAuth client settings. If NetBird shows a callback URL in the provider's setup interface, use exactly this value.

  1. Log in to Yandex Identity Hub.

  2. In the left-hand panel, navigate to Apps and select netbird-oidc-app.

  3. At the top right, click Edit.

  4. In the Redirect URI field, specify:

    https://<NetBird_domain>/oauth2/callback

  5. Click Save.

If you do not have the Yandex Cloud CLI yet, install and initialize it.

The folder used by default is the one specified when creating the CLI profile. To change the default folder, use the yc config set folder-id <folder_ID> command. You can also specify a different folder for any command using --folder-name or --folder-id. If you access a resource by its name, the search will be limited to the default folder. If you access a resource by its ID, the search will be global, i.e., through all folders based on access permissions.

Update your OAuth client by providing the redirect URI:

yc iam oauth-client update \
  --id <OAuth_client_ID> \
  --redirect-uris "https://<NetBird_domain>/oauth2/callback"

Warning

The redirect URI in Yandex Identity Hub must exactly match the callback URL used by NetBird: they must have the same scheme, domain, path, and trailing slash (/) if any.

Configure an external OIDC provider in NetBird Dashboard

Note

For more information on setting up external identity providers in NetBird, see this official NetBird guide.

  1. Open NetBird Dashboard at your instance's address, e.g., https://netbird.example.com, and log in under an administrator account.

  2. Navigate to Settings → Identity Providers.

  3. Click Add Identity Provider or a similar button in your NetBird version.

  4. Select provider type, OpenID Connect or Generic OIDC.

  5. Specify the connection parameters:

    • Name: For example, Yandex Cloud Identity Hub.
    • Client ID: client_id value issued by Yandex Identity Hub.
    • Client Secret: OIDC app secret.
    • Issuer URL or Authority: Issuer URL issued by Yandex Identity Hub.

  6. If NetBird displays a callback URL, make sure it matches the value specified in the OIDC app's redirect URI.

  7. Save the settings.

  8. If you have several providers configured in NetBird, make the new provider the default one if needed.

  9. Restart NetBird services for the changes to take effect. For example, for Docker Compose:

    docker compose down
docker compose up -d

Note

Depending on your NetBird version, the names of sections and fields may slightly differ. If your interface does not allow you to specify individual endpoints, it is enough to specify the issuer URL: NetBird will get authorization_endpoint, token_endpoint, userinfo_endpoint, and jwks_uri automatically.

Make sure your application works correctly

  1. Log out of NetBird Dashboard if already logged in.

  2. Open the NetBird login page.

  3. Click the sign in button via the configured OIDC provider, e.g., Continue with Yandex Cloud.

  4. On the Yandex Cloud authentication page, log in as a user who:

    • Has been added to the user pool.
    • Has been added to the OIDC app either directly or via a group.

  5. Make sure that after successful authentication the browser returns to NetBird, and the user gets access to the Dashboard.

  6. If NetBird displays the user profile, check that you are logged in under the account you expected and that the email address is correct.

Possible errors

redirect_uri mismatch

Cause: NetBird's callback URL does not match the OAuth client's redirect URI.

What to check:

  • NetBird and Yandex Identity Hub use the same URL.
  • https scheme, domain, /oauth2/callback path, and trailing /, if any, are the same.

invalid_client

Cause: Incorrect Client ID or Client Secret specified in NetBird.

What to check:

  • NetBird uses the correct client_id of the new OIDC app.
  • The secret was saved correctly and was not replaced with a new one without updating the NetBird settings.

invalid_scope

Cause: NetBird is requesting scopes the application is not allowed to use.

What to check:

  • openid, email, profile are allowed in OAuth client and OIDC app.
  • NetBird does not specify additional scopes that are not configured in Yandex Identity Hub.

If the error persists, start with a minimum set of scopes, openid profile email, and then add more as needed.

User cannot log in

What to check:

  • The user is added to the user pool.
  • The user is activated.
  • The user or the user's group is added to the OIDC app.
  • If NetBird uses the email claim, the user's email address is provided.

NetBird does not accept the token

What to check:

  • The token's issuer value matches the issuer URL specified in NetBird.
  • The aud value matches the app's client ID.
  • NetBird's management service can access the provider's JWKS endpoint.
  • NetBird uses the correct user claim: sub.

How to delete the resources you created

To stop paying for the resources you created, delete the OIDC app.

Previous
MWS
Next
OpenSearch