Contact UsGet started
© 2025 Direct Cursus Technology L.L.C.

Creating an OIDC application in Yandex Identity Hub

Written by
Updated at November 12, 2025

Note

This feature is at the Preview stage.

To authenticate your organization’s users in external apps using OpenID Connect (OIDC) single sign-on, create an OIDC application in Identity Hub and configure it appropriately both in Identity Hub and on your service provider’s side.

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

Create an app

  1. Log in to Yandex Identity Hub.
  2. In the left-hand panel, select Apps.
  3. In the top-right corner, click Create application and in the window that opens:

    1. Select the OIDC (OpenID Connect) single sign-on method.

    2. In the Name field, specify a name for your new app. The name must be unique within the organization and follow the 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.

    3. In the Folder field, select the folder where you want to create an OAuth client for your app.

      Every OIDC application requires an OAuth client, which is created and removed along with the app and is inherently linked to it.

    4. Optionally, in the Description field, enter a description for the new app.

    5. Optionally, add labels:

      1. Click Add label.
      2. Enter a label in key: value format.
      3. Press Enter.

    6. Click Create application.

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

By default, the CLI uses the folder specified when creating the profile. To change the default folder, use the yc config set folder-id <folder_ID> command. You can also set a different folder for any specific command using the --folder-name or --folder-id parameter.

  1. See the description of the CLI command for creating an OIDC app:

    yc organization-manager idp application oauth application create --help

  2. Create an OAuth client:

    yc iam oauth-client create \
  --name <OAuth_client_name> \
  --scopes <attribute>[,<attribute>]

    Where:

    • --name: OAuth client name.
    • --scopes: User attributes that will be available to the service provider. Specify one or more attributes, comma-separated, in <attribute1>,<attribute2> format. Possible attributes:
      • openid: User ID. Required attribute.
      • profile: Additional user details, such as first name, last name, and avatar.
      • email: User email address.
      • address: User home address.
      • phone: User phone number.
      • groups: User groups in the organization.

    Result:

    id: ajeqqip130i1********
name: test-oauth-client
folder_id: b1g500m2195v********
status: ACTIVE

    Save the id field value: you will need it to create and configure your app.

  3. Create a secret for your OAuth client:

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

    Result:

    oauth_client_secret:
  id: ajeq9jfrmc5t********
  oauth_client_id: ajeqqip130i1********
  masked_secret: yccs__939233b8ac****
  created_at: "2025-10-21T10:14:17.861652377Z"
secret_value: yccs__939233b8ac********

    Save the secret_value field value: you will need it to configure your app on the service provider side.

  4. Create an OIDC app:

    yc iam organization-manager idp application oauth application create \
  --organization-id <organization_ID> \
  --name <application_name> \
  --description <application_description> \
  --client-id <OAuth_client_ID> \
  --authorized-scopes <attribute>[,<attribute>] \
  --group-distribution-type all-groups \
  --labels <key>=<value>[,<key>=<value>]

    Where:

    • --organization-id: ID of the organization you want to create your OIDC app in. This is a required parameter.

    • --name: OIDC app name. This is a required parameter. The name must be unique within the organization and follow the 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.

    • --description: OIDC app description. This is an optional parameter.

    • --client-id: OAuth client ID you got in Step 2. This is a required parameter.

    • --authorized-scopes: Specify the same attributes as when creating the OAuth client.

    • --group-distribution-type: If you provided the groups attribute when creating the OAuth client, specify which user groups you want to go to the service provider. The possible values are:

      • all-groups: Service provider will get all groups the user belongs to.

        The maximum number of groups to change hands is 1,000. If the user belongs to more groups than this, only the first thousand will go to the service provider.

      • assigned-groups: Of all the user's groups, the service provider will only get the ones explicitly specified.

      • none: Service provider will not get any of the groups the user belongs to.

    • --labels: List of labels. This is an optional parameter. You can specify one or more labels separated by commas in <key1>=<value1>,<key2>=<value2> format.

    Result:

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

Set up your application

To integrate an external application with the OIDC application you created in Identity Hub, complete the setup both on the service provider side and in Identity Hub.

Set up integration on the service provider side

You can look up the values of integration settings to use on the service provider side on the app info page in the Cloud Center interface.

Depending on the options supported by your service provider, you can configure the required settings manually or automatically by specifying a configuration URL:

  1. Log in to Yandex Identity Hub.

  2. In the left-hand panel, select Apps and then, your OIDC app.

  3. On the Overview tab, under Identity provider (IdP) configuration, expand the Additional attributes section and copy the parameter values to use on the service provider side:

    • ClientID: Unique application ID.
    • Authorization endpoint: Address in Yandex Cloud to which the service provider will redirect the user for authentication.
    • Token endpoint: Address to which the external application sends a request to obtain an ID token and access token.
    • Userinfo endpoint: Address the external application can use to obtain user attributes.

  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.

  5. On the service provider side, set up integration with your Identity Hub OIDC application by specifying the parameters you copied and the generated secret. If you need help, refer to your service provider's documentation or support team.

  1. Log in to Yandex Identity Hub.

  2. In the left-hand panel, select Apps and select the OIDC app.

  3. On the Overview tab, under Identity provider (IdP) configuration, copy the OpenID Configuration field value.

    This URL exposes all configuration values required on the service provider side (except for the secret).

  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.

  5. If your service provider supports using a configuration URL to configure the application, set up integration with your Identity Hub OIDC application on the service provider side by specifying the copied link and secret. If you need help, refer to your service provider's documentation or support team.

Configure your OIDC application in Identity Hub

Before configuring your OIDC application in Identity Hub, get the redirect URI from your service provider. Then, navigate to the OIDC application settings in Identity Hub:

  1. Log in to Yandex Identity Hub.
  2. In the left-hand panel, select Apps and then, the OIDC app.

  3. On the top right, click Edit and in the window that opens:

    1. Specify the address you got from the service provider in the Redirect URI field.

      Click Add URI to specify multiple redirect URIs at once.

    2. In the Scopes field, select user attributes that will be available to the service provider.

      • openid (user ID): User ID. This is a required parameter.

      • email address: User email address.

      • profile (full name, first name, last name, avatar, etc.): Additional user details.

      • groups (user's groups in the organization): User groups in the organization whose member the user getting authenticated is. The possible values are:

        • All grous : Security provider will get all groups the user belongs to.

          The maximum number of sent groups: 1,000. If the user belongs to more groups, only the first thousand of them will be communicated to the service provider.

        • Assigned groups only: Of all groups the user belongs to, the service provider will only get the ones explicitly specified on the Users and groups tab of the OIDC app.

    3. Click Save.

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

By default, the CLI uses the folder specified when creating the profile. To change the default folder, use the yc config set folder-id <folder_ID> command. You can also set a different folder for any specific command using the --folder-name or --folder-id parameter.

  1. See the description of the CLI command for setting up the OAuth client:

    yc iam oauth-client update --help

  2. Run this command:

    yc iam oauth-client update \
  --id <OAuth_client_ID> \
  --redirect-uris <address>[,<address>]

    Where:

    • --id: OAuth client ID.
    • --redirect-uris: Specify the address or addresses you got from the service provider in <address1>,<address2> format.

    Result:

    id: ajeqqip130i1********
name: test-oauth-client
redirect_uris:
  - https://example.com
  - https://example.ru
folder_id: b1g500m2195v********
status: ACTIVE

Configure users and groups

For your organization's users to be able to authenticate in an external app with a Identity Hub OIDC application, you need to explicitly add these users and/or user groups to this OIDC application:

Note

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

  1. Log in to Yandex Identity Hub.

  2. In the left-hand panel, select Apps and then, the OIDC app.

  3. Navigate to the Users and groups tab.

  4. To add a user or user group to the app:

    1. Click Add users.
    2. In the window that opens, select the required user or user group.
    3. Click Add.

  5. To delete a user or user group from the app:

    1. In the list of users and groups, click and select Delete next to the user or user group.
    2. Confirm the deletion.

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

By default, the CLI uses the folder specified when creating the profile. To change the default folder, use the yc config set folder-id <folder_ID> command. You can also set a different folder for any specific command using the --folder-name or --folder-id parameter.

  1. Get the user ID or user group ID.

  2. To add a user or user group to the app:

    1. See the description of the CLI command for adding users to an app:

      yc organization-manager idp application oauth application add-assignments --help

    2. Run this command:

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

      Where:

      • --id: App ID.
      • --subject-id: User or user group ID.

      Result:

      assignment_deltas:
  - action: ADD
    assignment:
      subject_id: ajetvnq2mil8********

  3. To delete a user or user group from the app:

    1. See the description of the CLI command for removing users from an app:

      yc organization-manager idp application oauth application remove-assignments --help

    2. Run this command:

      yc organization-manager idp application oauth application remove-assignments \
  --id <app_ID> \
  --subject-id <user_ID>

      Where:

      • --id: OIDC app ID.
      • --subject-id: User or user group ID.

      Result:

      assignment_deltas:
  - action: REMOVE
    assignment:
      subject_id: ajetvnq2mil8********

Make sure your application works correctly

To make sure both your OIDC application and service provider integration work correctly, get authenticated in the external app as one of the users you added to the application.

See also

Previous
Deactivating and deleting an app
Next
Updating an app