[Yandex Cloud documentation](../../../index.md) > [Yandex Identity Hub](../../index.md) > [Tutorials](../index.md) > [Setting up single sign-on (SSO) for apps](index.md) > Warpgate

# Creating an OIDC application in Yandex Identity Hub for integration with Warpgate


[Warpgate](https://warpgate.null.page/) is an open-source [bastion host](*bastion-host) for secure access to internal services over SSH, HTTP, MySQL, PostgreSQL, Kubernetes, RDP, and VNC. Warpgate supports [OpenID Connect](https://en.wikipedia.org/wiki/OpenID#OpenID_Connect_(OIDC)) (OIDC) user authentication via external identity providers.

To enable your [organization’s](*organization) users to authenticate in Warpgate via OIDC, create an [OIDC application](../../concepts/applications/oidc.md) and set up Warpgate integration. In this tutorial, you will also configure [user group](*users-groups) provisioning to Warpgate and map the groups to access roles.

OIDC apps can be managed by users with the `organization-manager.oauthApplications.admin` [role](../../security/index.md#organization-manager-oauthApplications-admin) or higher.

To provide your organization’s users with access to Warpgate:

1. [Create an OIDC app](#create-app).
1. [Create a user group and add users to it](#create-group).
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).

## 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 **Application type** field, select [Web Application](*web_app_type).
         
         [*web_app_type]: OIDC apps of the `Web Application` type are optimized for user authentication to external web apps with a server end (backend), where the application secret can be safely stored. For more information about OIDC application types, see [Types of OIDC apps in Yandex Identity Hub](../../concepts/applications/oidc.md#oidc-application-types).
      1. In the **Name** field, specify `warpgate-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 Warpgate`.
      1. Click **Create application**.
  1. In the new app, click ![pencil](../../../_assets/console-icons/pencil.svg) **Edit** at the top right.
  1. In the **Scopes** field, select the `groups (user's groups in the organization)` attribute and set it to `Assigned groups only`. In new OIDC apps, this attribute is off by default.
  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 <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 warpgate-oauth-client \
       --scopes openid,email,profile,groups \
       --profile-id web
     ```

     Where:

     * `--name`: OAuth client name.
     * `--scopes`: User attributes available to Warpgate. The specified attributes are:
       * `openid`: User ID. Required attribute.
       * `email`: User email address.
       * `profile`: Additional user details, such as first name, last name, and avatar.
       * `groups`: [User groups](../../concepts/groups.md) in the organization. You will need groups for mapping to Warpgate access roles.
     * `--profile-id`: OAuth client (OIDC application) [type](../../concepts/applications/oidc.md#oidc-application-types). This tutorial creates an OAuth client of the `Web Application` type.

     Result:

     ```text
     id: ajeqqip130i1********
     name: warpgate-oauth-client
     folder_id: b1g500m2195v********
     authentication_methods:
       - client_secret_basic
       - client_secret_post
     status: ACTIVE
     profile_id: web
     pkce_required: true
     ```

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

  1. Create a secret for your OAuth client:

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

     Result:

     ```text
     oauth_client_secret:
       id: ajeq9jfrmc5t********
       oauth_client_id: ajeqqip130i1********
       masked_secret: yccs__939233b8ac****
       created_at: "2026-09-12T10:14:17.861652377Z"
     secret_value: yccs__939233b8ac********
     ```

     Save the `secret_value` field value: you will need it to configure Warpgate.

  1. Create an OIDC app:

     ```bash
     yc organization-manager idp application oauth application create \
       --organization-id <organization_ID> \
       --name warpgate-oidc-app \
       --description "OIDC app for integration with Warpgate" \
       --client-id <OAuth_client_ID> \
       --authorized-scopes openid,email,profile,groups \
       --group-distribution-type assigned-groups
     ```

     Where:

     * `--organization-id`: [ID of the organization](../../operations/organization-get-id.md) you want to create your OIDC app in. This is a required setting.
     * `--name`: OIDC app name. This is a required setting.
     * `--description`: OIDC app description. This is an optional setting.
     * `--client-id`: OAuth client ID you got in the previous step. This is a required setting.
     * `--authorized-scopes`: Specify the same attributes as when creating the OAuth client.
     * `--group-distribution-type`: Specify `assigned-groups` to provide to Warpgate only the groups added to the application.

     Result:

     ```text
     id: ek0o663g4rs2********
     name: warpgate-oidc-app
     organization_id: bpf2c65rqcl8********
     group_claims_settings:
       group_distribution_type: ASSIGNED_GROUPS
     client_grant:
       client_id: ajeqqip130i1********
       authorized_scopes:
         - openid
         - email
         - profile
         - groups
     status: ACTIVE
     created_at: "2026-09-12T10:51:28.790866Z"
     updated_at: "2026-09-12T12:37:19.274522Z"
     ```

     Save the ID of the new OIDC app.

{% endlist %}

## Create a user group and add users to it {#create-group}

Organize users who need the same Warpgate access level into an organization [group](../../concepts/groups.md). Then map the group name to a Warpgate access role.

### Create a group {#create-group-step}

Create a group named `warpgate-users`.

To create a [group](../../concepts/groups.md), you need _at least_ the `organization-manager.groups.editor` [role](../../security/index.md#organization-manager-editor) for the [organization](../../concepts/organization.md).

{% 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 ![groups](../../../_assets/console-icons/persons.svg) **Groups**.

  1. In the top-right corner of the page, click ![Circles3Plus](../../../_assets/console-icons/circles-3-plus.svg) **Create group**.

  1. Enter a name and description for the [group](../../concepts/groups.md).

      The name must be unique within the organization and satisfy the relevant 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. Optionally, add [labels](../../../resource-manager/concepts/labels.md):

     1. Click **Add label**.
     1. Add a label in `key: value` format.
     1. Press **Enter**.

  1. Click **Create group**.

- 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 <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. See the description of the command for creating a Yandex Identity Hub user group:

      ```bash
      yc organization-manager group create --help
      ```
  
  1. To create a user group in Yandex Identity Hub, run this command:

      ```bash
      yc organization-manager group create \
        --name <group_name> \
        --organization-id <organization_ID> \
        --description <group_description> \
        --labels <key>=<value>
      ```

      Where:

      * `--name`: User group name. This is a required setting. The name must be unique within the organization and satisfy the relevant 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.

      * `--organization-id`: [Organization ID](../../operations/organization-get-id.md). This is an optional setting.
      * `--description`: Text description of the user group. This is an optional setting.
      * `--labels`: List of [labels](../../../resource-manager/concepts/labels.md) in `<key>=<value>` format. You can specify one or multiple labels separated by commas. This is an optional setting.

- Terraform {#tf}

  With [Terraform](https://www.terraform.io/), you can quickly create a cloud infrastructure in Yandex Cloud and manage it using configuration files. These files store the infrastructure description written in HashiCorp Configuration Language (HCL). If you change the configuration files, Terraform automatically detects which part of your configuration is already deployed, and what should be added or removed.
  
  Terraform is distributed under the [Business Source License](https://github.com/hashicorp/terraform/blob/main/LICENSE). The [Yandex Cloud provider for Terraform](https://github.com/yandex-cloud/terraform-provider-yandex) is distributed under the [MPL-2.0](https://www.mozilla.org/en-US/MPL/2.0/) license.
  
  For more information about the provider resources, see the guides on the [Terraform](https://www.terraform.io/docs/providers/yandex/index.html) website or [its mirror](../../../terraform/index.md).

  If you do not have Terraform yet, [install it and configure the Yandex Cloud provider](../../../tutorials/infrastructure-management/terraform-quickstart.md#install-terraform).
  
  
  To manage infrastructure using Terraform under a service account or user accounts (a Yandex account, a federated account, or a local user), [authenticate](../../../terraform/authentication.md) using the appropriate method.

  1. In the configuration file, describe the [group](../../concepts/groups.md) parameters:

     ```hcl
     resource "yandex_organizationmanager_group" "my-group" {
       name            = "<group_name>"
       description     = "<group_description>"
       organization_id = "<organization_ID>"
     }
     ```

     Where:

     * `name`: Group name. The name must be unique within the organization and satisfy the relevant 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`: Group description. This is an optional setting.
     * `organization_id`: [ID](../../operations/organization-get-id.md) of the organization to add the group to.

  1. Create the resources:

     1. In the terminal, navigate to the configuration file directory.
     1. Make sure the configuration is correct using this command:
     
        ```bash
        terraform validate
        ```
     
        If the configuration is valid, you will get this message:
     
        ```bash
        Success! The configuration is valid.
        ```
     
     1. Run this command:
     
        ```bash
        terraform plan
        ```
     
        You will see a list of resources and their properties. No changes will be made at this step. Terraform will show any errors in the configuration.
     1. Apply the configuration changes:
     
        ```bash
        terraform apply
        ```
     
     1. Type `yes` and press **Enter** to confirm the changes.

     Terraform will create all the required resources. You can check the new resources and their settings in the [Cloud Center UI](https://center.yandex.cloud/organization) or using this [CLI](../../../cli/index.md) command:

     ```bash
     yc organization-manager group list \
       --organization-id <organization_ID>
     ```

- API {#api}

    Use the [Group.create](../../api-ref/Group/create.md) REST API method for the [Group](../../api-ref/Group/index.md) resource or the [GroupService/Create](../../api-ref/grpc/Group/create.md) gRPC API call.

{% endlist %}

### Add users to the group {#add-users-to-group}

Follow [this guide](../../operations/add-member-group.md) to add all users who need the same Warpgate access level into the `warpgate-users` group.

### Add the group to the OIDC app {#add-group-to-app}

For the `warpgate-users` group users to be able to sign in to Warpgate through your new OIDC application, and to provide the group in the `groups` attribute, explicitly add the group to the application.

{% note info %}

Users and groups added to an OIDC application can be managed by any user with the `organization-manager.oauthApplications.userAdmin` [role](../../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 `warpgate-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 the `warpgate-users` group.
  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 <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 ID](../../operations/group-get-id.md) of the `warpgate-users` group.
  1. Add the group to the app:

     ```bash
     yc organization-manager idp application oauth application add-assignments \
       --id <app_ID> \
       --subject-id <group_ID>
     ```

     Where:

     * `--id`: OIDC app ID.
     * `--subject-id`: `warpgate-users` group 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](../../concepts/authentication-policy.md).

## Set up the integration {#setup-integration}

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

### 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 `warpgate-oidc-app`.
  1. Under **Identity provider (IdP) configuration** on the **Overview** tab, expand the **Additional attributes** section and save the Client ID value (**ClientID**).
  1. Create an app secret (only available for applications of the `Web Application` [type](../../concepts/applications/oidc.md#oidc-application-types)).
     
     To do this, 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](../../concepts/applications/oidc.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 <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 new OIDC app info:

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

     Save the `client_id` value from the `client_grant` section: this is the Client ID you will need to configure Warpgate.

  1. Use the OAuth client secret you saved when creating the app. If you have not saved the secret, create a new one:

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

     Save the `secret_value` value: this is the Client Secret you will need to configure Warpgate.

{% endlist %}

For Yandex Identity Hub, the issuer URL is `https://auth.yandex.cloud`. You will need it to configure Warpgate.

### Configure a redirect URI {#setup-redirect}

Warpgate uses the following address format: `https://<warpgate_domain>/_warpgate/api/sso/return`, where `<warpgate_domain>` is the [external domain](https://warpgate.null.page/sso/#external-host) of your Warpgate instance specified in the `external_host` parameter of the configuration file.

For example, if `external_host: warpgate.example.com`, the redirect URI will look like this:

```text
https://warpgate.example.com/_warpgate/api/sso/return
```

{% note info %}

By default, Warpgate generates a redirect URI with `@` (`/@warpgate/api/sso/return`). Yandex Identity Hub does not support this symbol. For Warpgate to replace the `@warpgate` prefix with `_warpgate`, specify `return_url_prefix: _` in the Warpgate SSO provider configuration.

{% endnote %}

Specify the resulting address in the OAuth client settings:

{% 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 `warpgate-oidc-app`.
  1. At the top right, click ![pencil](../../../_assets/console-icons/pencil.svg) **Edit**.
  1. In the **Redirect URI** field, specify:

     ```text
     https://<warpgate_domain>/_warpgate/api/sso/return
     ```

  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 <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 <OAuth_client_ID> \
    --redirect-uris "https://<warpgate_domain>/_warpgate/api/sso/return"
  ```

{% endlist %}

{% note warning %}

The redirect URI in Yandex Identity Hub and that in Warpgate must fully match, including the scheme, domain, and path.

{% endnote %}

### Create an access role in Warpgate {#setup-warpgate-role}

On the Warpgate side, create an [access role](https://warpgate.null.page/roles/#access-roles) that will be assigned to users successfully authenticated through Yandex Identity Hub:

1. Log in to Warpgate using an administrator account.
1. In the menu, go **Config** → **Access roles**.
1. Click **Add a role**.
1. Enter a name for the role, e.g., `user`, and save the changes.

In the next step, specify this role in the `role_mappings` parameter of the Warpgate configuration file.

### Configure an SSO provider in the Warpgate configuration file {#setup-warpgate-sso}

{% note info %}

For more information about setting up SSO for Warpgate, see [this official Warpgate guide](https://warpgate.null.page/sso/).

{% endnote %}

Open the Warpgate configuration file (`warpgate.yaml`) and add a `custom` type SSO provider to it:

```yaml
sso_providers:
- name: idh
  auto_create_users: true
  return_url_prefix: _
  return_url_domain: external_host
  label: SSO with Identity Hub
  provider:
    type: custom
    client_id: <OIDC_app_client_id>
    client_secret: <OIDC_app_secret>
    issuer_url: https://auth.yandex.cloud
    scopes: ["openid", "profile", "email", "groups"]
    roles_claim: groups
    role_mappings:
      'warpgate-users': 'user'
external_host: <warpgate_domain>
```

Where:

* `name`: Provider ID.
* `auto_create_users: true`: Warpgate automatically creates accounts for users who authenticate through Yandex Identity Hub for the first time. The username is taken from the `preferred_username` attribute, or from the `email` attribute if there is no `preferred_username`.
* `return_url_prefix: _`: Replaces `@` with `_` in the redirect URI because Yandex Identity Hub does not support `@` in this address.
* `return_url_domain: external_host`: Warpgate generates the redirect URI based on the domain from `external_host`.
* `label`: Login button label on the Warpgate authentication page.
* `provider`: OIDC provider settings:
  * `type: custom`: Integration type for a custom OIDC-compliant identity provider; in this case, Yandex Identity Hub.
  * `client_id` and `client_secret`: Client ID and OIDC app secret you got [earlier](#get-credentials).
  * `issuer_url`: Yandex Identity Hub issuer URL, `https://auth.yandex.cloud`.
  * `scopes`: User attributes Warpgate requests from Yandex Identity Hub. These must match the attributes specified when configuring the OIDC application.
  * `roles_claim: groups`: ID token attribute with the user’s groups. The `groups` value matches the standard Yandex Identity Hub group attribute.
  * `role_mappings`: Mapping between Yandex Identity Hub groups and Warpgate access roles. In our example, the `warpgate-users` group is mapped to the `user` role [created earlier](#setup-warpgate-role). Warpgate syncs only the roles specified in this parameter without touching the user’s other roles.
* `external_host`: External domain of the Warpgate instance, e.g., `warpgate.example.com`. It must match the domain specified in the Redirect URI field of the OIDC application.

Save the configuration file and restart Warpgate to apply the changes.

## Make sure your application works correctly {#validate}

1. Log out of Warpgate if already logged in.
1. Open the Warpgate login page at your instance URL, e.g., `https://warpgate.example.com`.
1. Click the login button of the same name as the `label` parameter value.
1. On the Yandex Cloud authentication page, log in as a user belonging to the `warpgate-users` group.
1. Make sure that after successful authentication the browser returns to Warpgate, and the user gets access to the interface with the `user` role.
1. You can look up the **Users** section in Warpgate to make sure the new user got the expected role.

## How to delete the resources you created {#clear-out}

To stop paying for the Yandex Identity Hub resources you created, [delete](../../operations/applications/oidc-deactivate-remove.md#delete) the OIDC app.

[Delete](../../operations/delete-group.md) the new `warpgate-users` group too if you need to.

[*bastion-host]: A _bastion host_ is a separate VM with a public IP address in a protected infrastructure. It enables secure connections to other resources within the same infrastructure, which do not have public IP addresses. For more on configuring a bastion host, see [Creating a bastion host](../../../tutorials/routing/bastion.md).

[*organization]: An _organization_ is the highest resource in the Yandex Cloud resource model hierarchy that consolidates the resources of all other services. It is also used for user management as well as authentication and authorization management. For more information, see [Organization](../../concepts/organization.md).

[*users-groups]: You can group Yandex Identity Hub users to simplify access management in Yandex Cloud. For more information, see [User groups](../../concepts/groups.md).