Using an OIDC app and OAuth2 Proxy to set up single sign-on for applications that do not support SSO

Some applications have no built-in support for single sign-on (SSO). However, you may sometimes need to configure user authentication in such applications using Yandex Identity Hub.

In this guide, you will use the OAuth2 Proxy utility combined with a reverse proxy to integrate a simple application with Yandex Identity Hub and restrict access to it exclusively to specified Identity Hub users via OpenID Connect (OIDC)-based single sign-on.

This guide uses nginx as the proxy server and a static HTML page as the test application. To enable your Identity Hub users to access the test application, you will create and configure an OIDC app. Additionally, you will need a Yandex Compute Cloud VM instance to run nginx and OAuth2 Proxy and host your test application. Furthermore, to implement secure access to the test application, you will need a domain name and an SSL certificate issued for it.

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

To configure application access for your Identity Hub users, do the following:

1. Create and configure an OIDC app in Identity Hub.
2. Configure the test application VM.
3. Set up the integration.
4. Make sure your integration works correctly.

Creating and configuring an OIDC app in Identity HubCreating and configuring an OIDC app in Identity Hub

Creating an OIDC appCreating an OIDC app

Configure the redirect URIConfigure the redirect URI

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

  id: ajeiu3otac08********
  name: website-oauth-client
  redirect_uris:
    - https://example.com/oauth2/callback
  scopes:
    - email
    - openid
    - profile
  folder_id: b1gkd6dks6i1********
  status: ACTIVE

Add a userAdd a user

For your Identity Hub users to be able to authenticate in the test application over the OIDC protocol, you need to explicitly add these users and/or user groups to this OIDC application.

Add a user to the application:

Configure the test application VMConfigure the test application VM

In this guide, you will deploy the test application and configure nginx and OAuth2 Proxy on a VM instance running Ubuntu 24.04.

Set up your Yandex Cloud environmentSet up your Yandex Cloud environment

Before creating the VM, ensure that your folder contains a cloud network and a subnet. If needed, follow the guides below to create them:

• Creating a cloud network
• Creating a subnet

Also, in your cloud network, create a security group that allows inbound TCP traffic on ports 22, 80, and 443 as well as any outbound traffic.

Create a VMCreate a VM

  yc compute instance create \
    --name my-nginx-vm \
    --zone <VM_availability_zone> \
    --create-boot-disk image-folder-id=standard-images,image-family=ubuntu-2404-lts,auto-delete=true \
    --ssh-key <path_to_public_SSH_key> \
    --network-interface subnet-name=<subnet_name>,nat-ip-version=ipv4,security-group-ids=<security_group_ID>

done (29s)
id: epdvqa1rtvjj********
folder_id: b1gt6g8ht345********
created_at: "2026-01-22T12:03:52Z"
name: my-nginx-vm
zone_id: ru-central1-b
platform_id: standard-v2
resources:
  memory: "2147483648"
  cores: "2"
  core_fraction: "100"
status: RUNNING
metadata_options:
  gce_http_endpoint: ENABLED
  aws_v1_http_endpoint: ENABLED
  gce_http_token: ENABLED
  aws_v1_http_token: DISABLED
boot_disk:
  mode: READ_WRITE
  device_name: epdbi403v2or********
  auto_delete: true
  disk_id: epdbi403v2or********
network_interfaces:
  - index: "0"
    mac_address: d0:0d:1f:d2:83:be
    subnet_id: e2lqsms4cdl3********
    primary_v4_address:
      address: 192.168.2.31
      one_to_one_nat:
        address: 89.169.***.***
        ip_version: IPV4
    security_group_ids:
      - enp378h7n0cm********
serial_port_settings:
  ssh_authorization: OS_LOGIN
gpu_settings: {}
fqdn: epdvqa1rtvjj********.auto.internal
scheduling_policy: {}
network_settings:
  type: STANDARD
placement_policy: {}
hardware_generation:
  legacy_features:
    pci_topology: PCI_TOPOLOGY_V2
application: {}

Set up the integrationSet up the integration

Creating a test app and configuring nginxCreating a test app and configuring nginx

1. Ensure your domain has a resource A record pointing to the public IP address of your new VM. If no such record exists, create one.

   Note

   If management of your domain is delegated to Yandex Cloud DNS, follow this guide to create the resource record. If your domain is managed by a third-party provider, refer to their documentation or contact their support team.

2. Connect over SSH to the new VM.

3. Install nginx:

   sudo apt update && sudo apt upgrade -y
   sudo apt install nginx -y
   

4. Create the test application files:

   1. Save your domain name to an environment variable:

      export MY_DOMAIN="<domain_name>"
      

      Where <domain_name> is your domain name with a resource record pointing to the public IP address of the current VM, e.g., example.com.

   2. Create a directory and the main HTML page for your test application:

      sudo mkdir /var/www/$MY_DOMAIN
      sudo touch /var/www/$MY_DOMAIN/index.html \
        && echo "<h1>Your Web application that is available to your Identity Hub users only</h1>" | sudo tee -a /var/www/$MY_DOMAIN/index.html
      

5. Generate a self-signed SSL certificate for your domain. To do this, run the command and enter values as prompted:

   sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout /etc/ssl/private/my-private.key -out /etc/ssl/certs/my-certificate.crt
   

   This will create a self-signed SSL certificate sufficient for testing the proposed solution.

   Tip

   To avoid browser security warnings when using the application, use an SSL certificate issued by a trusted certificate authority.

   For example, to obtain a certificate from Let's Encrypt and save both the certificate and private key to your computer, follow these guides: Adding a Let's Encrypt® certificate and Get the contents of the Let's Encrypt certificate.

6. Configure the nginx settings:

   1. In the nano text editor, open the nginx configuration file:

      sudo nano /etc/nginx/conf.d/default.conf
      

   2. Replace the opened file contents with this text:

      server {
          listen 80;
          listen [::]:80;
          server_name <domain_name>;
      
          return 301 https://$server_name$request_uri;
      }
      
      server {
          listen 443 ssl;
          listen [::]:443 ssl;
          server_name <domain_name>;
      
          location /oauth2/ {
              proxy_pass       http://127.0.0.1:4180;
              proxy_set_header Host                    $host;
              proxy_set_header X-Real-IP               $remote_addr;
              proxy_set_header X-Auth-Request-Redirect $request_uri;
              # or, if you are handling multiple domains:
              # proxy_set_header X-Auth-Request-Redirect $scheme://$host$request_uri;
          }
        
          location = /oauth2/auth {
              proxy_pass       http://127.0.0.1:4180;
              proxy_set_header Host             $host;
              proxy_set_header X-Real-IP        $remote_addr;
              proxy_set_header X-Forwarded-Uri  $request_uri;
              # nginx auth_request includes headers but not body
              proxy_set_header Content-Length   "";
              proxy_pass_request_body           off;
          }
      
          # Paths to your certificate and key
          ssl_certificate /etc/ssl/certs/my-certificate.crt;
          ssl_certificate_key /etc/ssl/private/my-private.key;
      
          # Recommended security settings
          ssl_protocols TLSv1.2 TLSv1.3;
          ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384;
          ssl_prefer_server_ciphers on;
      
          access_log /var/log/nginx/$server_name.access.log;
          error_log /var/log/nginx/$server_name.error.log;
      
          location / {
      
              auth_request /oauth2/auth;
              error_page 401 =403 /oauth2/sign_in;
      
              # pass information via X-User and X-Email headers to backend,
              # requires running with --set-xauthrequest flag
              auth_request_set $user   $upstream_http_x_auth_request_user;
              auth_request_set $email  $upstream_http_x_auth_request_email;
              proxy_set_header X-User  $user;
              proxy_set_header X-Email $email;
      
              root /var/www/$server_name/;
              index index.html;
      
              try_files $uri $uri/ =404;
          }
      
      }
      

      Where <domain_name> is your domain name with a resource record pointing to the public IP address of the current VM, e.g., example.com.

      Warning

      If you are using a certificate issued by a certificate authority, copy the certificate and private key files to the VM and specify their local paths in the ssl_certificate and ssl_certificate_key fields of the configuration file, respectively.

7. Apply the updated nginx settings:

   sudo nginx -s reload
   

Configuring OAuth2 ProxyConfiguring OAuth2 Proxy

1. Connect over SSH to the new VM.

2. Install the latest version of OAuth2 Proxy in any way you prefer.

   In the example below, we download an archive containing the executable. At the time of writing this guide, the latest version was v7.14.2.

   sudo wget https://github.com/oauth2-proxy/oauth2-proxy/releases/download/v7.14.2/oauth2-proxy-v7.14.2.linux-amd64.tar.gz
   sudo tar -xvf oauth2-proxy-v7.14.2.linux-amd64.tar.gz -C /usr/bin/
   sudo chmod +x /usr/bin/oauth2-proxy-v7.14.2.linux-amd64/oauth2-proxy
   sudo rm oauth2-proxy-v7.14.2.linux-amd64.tar.gz
   

3. Configure the OAuth2 Proxy settings:

   1. Generate a cookie secret required for configuring the utility:

      dd if=/dev/urandom bs=32 count=1 2>/dev/null | base64 | tr -d -- '\n' | tr -- '+/' '-_' ; echo
      

      Save the generated value, as you will need it later.

   2. In the nano text editor, open the oauth2-proxy.cfg configuration file:

      sudo nano /usr/bin/oauth2-proxy-v7.14.2.linux-amd64/oauth2-proxy.cfg
      

   3. Paste the following configuration into oauth2-proxy.cfg, substituting its values as required:

      provider = "oidc"  # Provider type
      provider_display_name = "Yandex Identity Hub" # Provider name to use as button text
      reverse_proxy = true # Enable operation behind nginx
      client_id = "<ClientID_ID>" # OIDC app ClientID 
      client_secret = "<ClientID_app_secret>" # OIDC app secret
      oidc_issuer_url = "https://auth.yandex.cloud"
      cookie_name = "_oauth2_proxy" # Cookie name
      cookie_secret = "<cookie_secret>"  # Cookie key generated previously
      email_domains = [ "<domain_1>","<domain_2>",...,"<domain_n>" ]  # Domains for which authentication is allowed
      upstreams = [ "<your_application_address>" ]  # Backend application address
      http_address = "127.0.0.1:4180"  # Address and port on which oauth2-proxy listens
      redirect_url = "<redirect_URI>"  # Callback URL
      

      Where:

      • client_id: ClientID value of the OAuth client obtained earlier when creating the OIDC app.

      • client_secret: Secret value you generated in the OIDC app.

      • cookie_secret: Cookie secret you generated and saved earlier.

      • email_domains: List of email domains for which Identity Hub user authentication in the test app is allowed.

        OAuth2 Proxy checks the email domain specified in the Email field of the user's settings in Identity Hub (the email attribute).

        In the email_domains field, specify the email domain of the user you previously added to your OIDC app. If you added a user group to the OIDC app, specify the email domain of a group user on whose behalf you will test authentication. You can specify multiple domains, comma-separated.

        Tip

        To allow users with Yandex accounts to authenticate in your test application, add yandex.ru to the email_domains list.

      • upstreams: Your application's address, e.g., https://example.com/.

      • redirect_url: Redirect URI value you specified when configuring the OIDC app.

4. Run OAuth2 Proxy:

   sudo /usr/bin/oauth2-proxy-v7.14.2.linux-amd64/oauth2-proxy \
     --config /usr/bin/oauth2-proxy-v7.14.2.linux-amd64/oauth2-proxy.cfg
   

   Tip

   You can also run OAuth2 Proxy in the background, e.g., using nohup.

Making sure authentication works correctlyMaking sure authentication works correctly

To check that OIDC app-based authentication works correctly in your test application, follow these steps:

1. In your browser, enter the address of your test application (e.g., https://example.com).

   If everything is configured correctly, you will see the OAuth2 Proxy authentication window in the browser.

2. Click Sign in with Yandex Identity Hub.

3. Authenticate as the user you previously added to the OIDC app. If you added a user group to the OIDC app, authenticate as a user belonging to that group.

   If everything is configured correctly, your test application page will open in the browser.

4. When attempting to authenticate as a user not added to the OIDC app, or as a user whose email domain is not included in the allowed email domains list configured in OAuth2 Proxy, your application will display an access error message.