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

Written by

Yandex Cloud

Improved by

ilya

Updated at October 29, 2026

View in Markdown

Creating an OIDC app
Create a user group and add users to it
Set up the integration
Make sure your application works correctly
How to delete the resources you created

Warpgate is an open-source bastion host for secure access to internal services over SSH, HTTP, MySQL, PostgreSQL, Kubernetes, RDP, and VNC. Warpgate supports OpenID Connect (OIDC) user authentication via external identity providers.

To enable your organization’s users to authenticate in Warpgate via OIDC, create an OIDC application and set up Warpgate integration. In this tutorial, you will also configure user group provisioning to Warpgate and map the groups to access roles.

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

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

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

Creating an OIDC app

Cloud Center UI

CLI

Log in to Yandex Identity Hub.
In the left-hand panel, select Apps.
Click Create application and in the window that opens:
1. Select the OIDC (OpenID Connect) single sign-on (SSO) method.
2. In the Application type field, select Web Application.
  
  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.
3. In the Name field, specify warpgate-oidc-app.
4. In the Folder field, select the folder where you want to create an OAuth client for your app.
5. Optionally, enter a description in the Description** field, e.g., OIDC app for integration with Warpgate.
6. Click Create application.
In the new app, click Edit at the top right.
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.
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.

Create an OAuth client:
```
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 in the organization. You will need groups for mapping to Warpgate access roles.
- --profile-id: OAuth client (OIDC application) type. This tutorial creates an OAuth client of the Web Application type.
Result:
```
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.

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: "2026-09-12T10:14:17.861652377Z"
secret_value: yccs__939233b8ac********

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

Create an OIDC app:

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

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.

Create a user group and add users to it

Organize users who need the same Warpgate access level into an organization group. Then map the group name to a Warpgate access role.

Create a group

Create a group named warpgate-users.

To create a group, you need at least the organization-manager.groups.editor role for the organization.

Cloud Center UI

CLI

Terraform

API

Log in to Yandex Identity Hub.
In the left-hand panel, select Groups.
In the top-right corner of the page, click Create group.
Enter a name and description for the group.

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.
Optionally, add labels:
1. Click Add label.
2. Add a label in key: value format.
3. Press Enter.
Click Create group.

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

See the description of the command for creating a Yandex Identity Hub user group:
```
yc organization-manager group create --help
```
To create a user group in Yandex Identity Hub, run this command:
```
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. This is an optional setting.
- --description: Text description of the user group. This is an optional setting.
- --labels: List of labels in <key>=<value> format. You can specify one or multiple labels separated by commas. This is an optional setting.

With Terraform, 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. The Yandex Cloud provider for Terraform is distributed under the MPL-2.0 license.

For more information about the provider resources, see the guides on the Terraform website or its mirror.

If you do not have Terraform yet, install it and configure the Yandex Cloud provider.

To manage infrastructure using Terraform under a service account or user accounts (a Yandex account, a federated account, or a local user), authenticate using the appropriate method.

In the configuration file, describe the group parameters:
```
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 of the organization to add the group to.
Create the resources:
1. In the terminal, navigate to the configuration file directory.
2. Make sure the configuration is correct using this command:
```
terraform validate
```
  If the configuration is valid, you will get this message:
```
Success! The configuration is valid.
```
3. Run this command:
```
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.
4. Apply the configuration changes:
```
terraform apply
```
5. 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 or using this CLI command:
```
yc organization-manager group list \
  --organization-id <organization_ID>
```

Use the Group.create REST API method for the Group resource or the GroupService/Create gRPC API call.

Add users to the group

Follow this guide to add all users who need the same Warpgate access level into the warpgate-users group.

Add the group to the OIDC 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

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

Cloud Center UI

CLI

Log in to Yandex Identity Hub.
In the left-hand panel, navigate to Apps and select warpgate-oidc-app.
Navigate to the Users and groups tab.
Click Add users.
In the window that opens, select the warpgate-users group.
Click Add.

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

Get the ID of the warpgate-users group.

Add the group to the app:

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.

Tip

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

Set up the 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

Cloud Center UI

CLI

Log in to Yandex Identity Hub.
In the left-hand panel, navigate to Apps and select warpgate-oidc-app.
Under Identity provider (IdP) configuration on the Overview tab, expand the Additional attributes section and save the Client ID value (ClientID).
Create an app secret (only available for applications of the Web Application type).

To do this, 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.

Get the new OIDC app info:
```
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.
Use the OAuth client secret you saved when creating the app. If you have not saved the secret, create a new one:
```
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.

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

Configure a redirect URI

Warpgate uses the following address format: https://<warpgate_domain>/_warpgate/api/sso/return, where <warpgate_domain> is the external domain 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:

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

Note

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.

Specify the resulting address in the OAuth client settings:

Cloud Center UI

CLI

Log in to Yandex Identity Hub.
In the left-hand panel, navigate to Apps and select warpgate-oidc-app.
At the top right, click Edit.

In the Redirect URI field, specify:

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

Click Save.

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

Update your OAuth client by providing the redirect URI:

yc iam oauth-client update \
  --id <OAuth_client_ID> \
  --redirect-uris "https://<warpgate_domain>/_warpgate/api/sso/return"

Warning

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

Create an access role in Warpgate

On the Warpgate side, create an access role that will be assigned to users successfully authenticated through Yandex Identity Hub:

Log in to Warpgate using an administrator account.
In the menu, go Config → Access roles.
Click Add a role.
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

Note

For more information about setting up SSO for Warpgate, see this official Warpgate guide.

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

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

Log out of Warpgate if already logged in.
Open the Warpgate login page at your instance URL, e.g., https://warpgate.example.com.
Click the login button of the same name as the label parameter value.
On the Yandex Cloud authentication page, log in as a user belonging to the warpgate-users group.
Make sure that after successful authentication the browser returns to Warpgate, and the user gets access to the interface with the user role.
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

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

Delete the new warpgate-users group too if you need to.

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

Creating an OIDC appCreating an OIDC app

Create a user group and add users to itCreate a user group and add users to it

Create a groupCreate a group

Add users to the groupAdd users to the group

Add the group to the OIDC appAdd the group to the OIDC app

Set up the integrationSet up the integration

Get the OIDC app connection credentialsGet the OIDC app connection credentials

Configure a redirect URIConfigure a redirect URI

Create an access role in WarpgateCreate an access role in Warpgate

Configure an SSO provider in the Warpgate configuration fileConfigure an SSO provider in the Warpgate configuration file

Make sure your application works correctlyMake sure your application works correctly

How to delete the resources you createdHow to delete the resources you created

Was the article helpful?

Creating an OIDC app

Create a user group and add users to it

Create a group

Add users to the group

Add the group to the OIDC app

Set up the integration

Get the OIDC app connection credentials

Configure a redirect URI

Create an access role in Warpgate

Configure an SSO provider in the Warpgate configuration file

Make sure your application works correctly

How to delete the resources you created