[Yandex Cloud documentation](../../../index.md) > [Tutorials](../../index.md) > [Security](../index.md) > Setting up single sign-on (SSO) for apps > NetBird # Creating an OIDC app in Yandex Identity Hub for integration with NetBird [NetBird](https://netbird.io/) is a platform for establishing secure access to network resources. NetBird supports [OpenID Connect](https://en.wikipedia.org/wiki/OpenID#OpenID_Connect_(OIDC)) 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](../../../organization/concepts/user-pools.md) in Yandex Identity Hub, get a `Client ID`, app secret, and [configuration URL](../../../organization/concepts/applications.md#oidc-sp-setup), and then configure an external OIDC provider in NetBird Dashboard. OIDC apps can be managed by users with the `organization-manager.oauthApplications.admin` [role](../../../organization/security/index.md#organization-manager-oauthApplications-admin) or higher. To give access to NetBird to the users of your organization: 1. [Get your cloud ready](#before-begin). 1. [Create an OIDC app](#create-app). 1. [Create a user pool and add users to it](#create-userpool). 1. [Set up the integration](#setup-integration). 1. [Make sure the application works correctly](#validate). If you no longer need the resources you created, [delete them](#clear-out). ## Get your cloud ready {#before-begin} Sign up for Yandex Cloud and create a [billing account](../../../billing/concepts/billing-account.md): 1. Navigate to the [management console](https://console.yandex.cloud) and log in to Yandex Cloud or create a new account. 1. On the **[Yandex Cloud Billing](https://center.yandex.cloud/billing/accounts)** page, make sure you have a billing account linked and it has the `ACTIVE` or `TRIAL_ACTIVE` [status](../../../billing/concepts/billing-account-statuses.md). If you do not have a billing account, [create one](../../../billing/quickstart/index.md) and [link](../../../billing/operations/pin-cloud.md) a cloud to it. If you have an active billing account, you can create or select a [folder](../../../resource-manager/concepts/resources-hierarchy.md#folder) for your infrastructure on the [cloud page](https://console.yandex.cloud/cloud). [Learn more about clouds and folders here](../../../resource-manager/concepts/resources-hierarchy.md). ### Required paid resources {#paid-resources} The cost of infrastructure support includes a fee for using the [OIDC app](../../../organization/concepts/applications.md#oidc) (see [Yandex Identity Hub pricing](../../../organization/pricing.md)). ### Getting started {#check-to-begin} Make sure that: * You have access to [Yandex Identity Hub](https://center.yandex.cloud/organization) 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](../../../organization/operations/add-account.md#local-users) for them in the user pool. {% note info %} The examples below use the following NetBird address: `https://netbird.example.com`. Replace it with the address of your NetBird instance. {% endnote %} ## Creating an OIDC app {#create-app} {% list tabs group=instructions %} - Cloud Center UI {#cloud-center} 1. Log in to [Yandex Identity Hub](https://center.yandex.cloud/organization). 1. In the left-hand panel, select ![shapes-4](../../../_assets/console-icons/shapes-4.svg) **Apps**. 1. Click ![Circles3Plus](../../../_assets/console-icons/circles-3-plus.svg) **Create application** and in the window that opens: 1. Select the **OIDC (OpenID Connect)** single sign-on (SSO) method. 1. In the **Name** field, specify `netbird-oidc-app`. 1. In the **Folder** field, select the folder where you want to create an OAuth client for your app. 1. Optionally, enter a description in the **Description** field, e.g., `OIDC app for integration with NetBird`. 1. Click **Create application**. - CLI {#cli} If you do not have the Yandex Cloud CLI yet, [install and initialize it](../../../cli/quickstart.md#install). The folder used by default is the one specified when [creating](../../../cli/operations/profile/profile-create.md) the CLI profile. To change the default folder, use the `yc config set 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: ```bash yc iam oauth-client create \ --name netbird-oauth-client ``` Where `--name` is the OAuth client name. Result: ```text 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. 1. Create a secret for your OAuth client: ```bash yc iam oauth-client-secret create \ --oauth-client-id ``` Result: ```text 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. 1. Create an OIDC app: ```bash yc organization-manager idp application oauth application create \ --organization-id \ --name netbird-oidc-app \ --description "OIDC app for integration with NetBird" \ --client-id \ --group-distribution-type none ``` Where: * `--organization-id`: [ID of the organization](../../../organization/operations/organization-get-id.md) 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: ```text 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. {% endlist %} ### Configure user OIDC attributes {#setup-scopes} NetBird typically uses standard [attributes](../../../organization/concepts/applications.md#oidc-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](../../../organization/concepts/groups.md) in the organization. {% list tabs group=instructions %} - Cloud Center UI {#cloud-center} 1. Log in to [Yandex Identity Hub](https://center.yandex.cloud/organization). 1. In the left-hand panel, navigate to ![shapes-4](../../../_assets/console-icons/shapes-4.svg) **Apps** and select `netbird-oidc-app`. 1. At the top right, click ![pencil](../../../_assets/console-icons/pencil.svg) **Edit**. 1. In the **User attributes** field, specify the recommended set of scopes: `openid, profile, email`. 1. Click **Save**. - CLI {#cli} If you do not have the Yandex Cloud CLI yet, [install and initialize it](../../../cli/quickstart.md#install). The folder used by default is the one specified when [creating](../../../cli/operations/profile/profile-create.md) the CLI profile. To change the default folder, use the `yc config set 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: ```bash yc iam oauth-client update \ --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. 1. Update the OIDC app with the same attributes: ```bash yc organization-manager idp application oauth application update \ --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. {% endlist %} ## Create a user pool and add users to it {#create-userpool} A Yandex Identity Hub [user pool](../../../organization/concepts/user-pools.md) 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 {#create-userpool-step} {% list tabs group=instructions %} - Cloud Center UI {#cloud-center} 1. Log in to [Yandex Identity Hub](https://center.yandex.cloud/organization). 1. In the left-hand panel, select ![userpool](../../../_assets/organization/userpool.svg) **User pools**. 1. In the top-right corner of the page, click ![Circles3Plus](../../../_assets/console-icons/circles-3-plus.svg) **Create user pool**. 1. 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. 1. In the **Default domain** field, specify the default [domain](../../../organization/concepts/domains.md) for the users of the pool. This domain will be used if no other domains are linked to the pool. 1. Optionally, add labels to organize your resources: * Click **Add**. * Enter a label in `: ` format. * Press **Enter**. 1. Optionally, in the **Data available for editing** field, select the user settings available for editing on the [My account](../../../organization/concepts/my-account.md) portal. By default, password management is allowed. 1. In the **Lifetime session** field, specify a time period for user [sessions](../../../organization/concepts/sessions.md) to remain active before requiring reauthentication in Yandex Identity Hub. 1. Click **Create userpool**. - CLI {#cli} If you do not have the Yandex Cloud CLI yet, [install and initialize it](../../../cli/quickstart.md#install). The folder used by default is the one specified when [creating](../../../cli/operations/profile/profile-create.md) the CLI profile. To change the default folder, use the `yc config set 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: ```bash yc organization-manager idp userpool create \ --organization-id \ --userpool-name netbird-users \ --description "User pool for logging into NetBird" \ --default-subdomain ``` 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. {% endlist %} ### Add users to the pool {#add-users-to-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](../../../organization/operations/add-account.md#local-users) 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](../../../iam/concepts/users/accounts.md#passport)*. 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 {#add-users-to-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 info %} Users and groups added to an OIDC application can be managed by any user with the `organization-manager.oauthApplications.userAdmin` [role](../../../organization/security/index.md#organization-manager-oauthApplications-userAdmin) or higher. {% endnote %} {% list tabs group=instructions %} - Cloud Center UI {#cloud-center} 1. Log in to [Yandex Identity Hub](https://center.yandex.cloud/organization). 1. In the left-hand panel, navigate to ![shapes-4](../../../_assets/console-icons/shapes-4.svg) **Apps** and select `netbird-oidc-app`. 1. Navigate to the **Users and groups** tab. 1. Click ![person-plus](../../../_assets/console-icons/person-plus.svg) **Add users**. 1. In the window that opens, select users or user groups, e.g., the new `netbird-users` pool or Yandex ID users. 1. Click **Add**. - CLI {#cli} If you do not have the Yandex Cloud CLI yet, [install and initialize it](../../../cli/quickstart.md#install). The folder used by default is the one specified when [creating](../../../cli/operations/profile/profile-create.md) the CLI profile. To change the default folder, use the `yc config set 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](../../../organization/operations/users-get.md) or [user group ID](../../../organization/operations/group-get-id.md). 1. Add a user or group to the application: ```bash yc organization-manager idp application oauth application add-assignments \ --id \ --subject-id ``` {% endlist %} {% note tip %} If you want to fine-tune user authentication in your applications, including authentication only from specific IP addresses, use [authentication policies](*authentication_policies). {% endnote %} [*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](../../../organization/concepts/authentication-policy.md). ## Set up the integration {#setup-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 {#get-credentials} {% list tabs group=instructions %} - Cloud Center UI {#cloud-center} 1. Log in to [Yandex Identity Hub](https://center.yandex.cloud/organization). 1. In the left-hand panel, navigate to ![shapes-4](../../../_assets/console-icons/shapes-4.svg) **Apps** and select `netbird-oidc-app`. 1. 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. 1. Under **App secrets**, click **Add secret**, and in the window that opens: 1. Optionally, add a description for the new secret. 1. Click **Create**. The window will display the generated [application secret](../../../organization/concepts/applications.md#oidc-secret). Save this value. {% note warning %} If you refresh or close the application information page, you will not be able to view the secret again. {% endnote %} 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 ![ellipsis](../../../_assets/console-icons/ellipsis.svg) in the secret row and select ![trash-bin](../../../_assets/console-icons/trash-bin.svg) **Delete**. - CLI {#cli} If you do not have the Yandex Cloud CLI yet, [install and initialize it](../../../cli/quickstart.md#install). The folder used by default is the one specified when [creating](../../../cli/operations/profile/profile-create.md) the CLI profile. To change the default folder, use the `yc config set 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: ```bash yc organization-manager idp application oauth application get ``` Save the `client_id` value from the `client_grant` section. 1. Get an issuer URL: ```bash yc organization-manager idp application oauth application get \ --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`. 1. If no secret was saved earlier, create a new one: ```bash yc iam oauth-client-secret create \ --oauth-client-id ``` Save `secret_value`. {% endlist %} ### Configure a redirect URI {#setup-redirect} NetBird uses a callback URL to complete OIDC authentication. Its typical format is: ```text https:///oauth2/callback ``` For example: ```text 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. {% list tabs group=instructions %} - Cloud Center UI {#cloud-center} 1. Log in to [Yandex Identity Hub](https://center.yandex.cloud/organization). 1. In the left-hand panel, navigate to ![shapes-4](../../../_assets/console-icons/shapes-4.svg) **Apps** and select `netbird-oidc-app`. 1. At the top right, click ![pencil](../../../_assets/console-icons/pencil.svg) **Edit**. 1. In the **Redirect URI** field, specify: ```text https:///oauth2/callback ``` 1. Click **Save**. - CLI {#cli} If you do not have the Yandex Cloud CLI yet, [install and initialize it](../../../cli/quickstart.md#install). The folder used by default is the one specified when [creating](../../../cli/operations/profile/profile-create.md) the CLI profile. To change the default folder, use the `yc config set 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: ```bash yc iam oauth-client update \ --id \ --redirect-uris "https:///oauth2/callback" ``` {% endlist %} {% note 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. {% endnote %} ### Configure an external OIDC provider in NetBird Dashboard {#setup-netbird} {% note info %} For more information on setting up external identity providers in NetBird, see [this official NetBird guide](https://docs.netbird.io/selfhosted/identity-providers/generic-oidc). {% endnote %} 1. Open NetBird Dashboard at your instance's address, e.g., `https://netbird.example.com`, and log in under an administrator account. 1. Navigate to **Settings** → **Identity Providers**. 1. Click **Add Identity Provider** or a similar button in your NetBird version. 1. Select provider type, **OpenID Connect** or **Generic OIDC**. 1. 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. 1. If NetBird displays a callback URL, make sure it matches the value specified in the OIDC app's redirect URI. 1. Save the settings. 1. If you have several providers configured in NetBird, make the new provider the default one if needed. 1. Restart NetBird services for the changes to take effect. For example, for Docker Compose: ```bash docker compose down docker compose up -d ``` {% note info %} 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. {% endnote %} ## Make sure your application works correctly {#validate} 1. Log out of NetBird Dashboard if already logged in. 1. Open the NetBird login page. 1. Click the sign in button via the configured OIDC provider, e.g., **Continue with Yandex Cloud**. 1. 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. 1. Make sure that after successful authentication the browser returns to NetBird, and the user gets access to the Dashboard. 1. 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 {#troubleshooting} ### `redirect_uri mismatch` {#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` {#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` {#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 {#user-cannot-login} 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 {#token-rejected} 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 {#clear-out} To stop paying for the resources you created, [delete](../../../organization/operations/applications/oidc-deactivate-remove.md#delete) the OIDC app.