Creating an OIDC application in Yandex Identity Hub for integration with Open WebUI

Open WebUI is a free open-source platform that provides an easy way to work with large language models and can be deployed in your own infrastructure. Open WebUI supports OpenID Connect (OIDC) authentication to provide secure SSO for your organization's users.

For your organization's users to be able to authenticate to Open WebUI via OpenID Connect SSO, create an OIDC app in Yandex Identity Hub and configure it both in Yandex Identity Hub and Open WebUI.

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

1. Get your cloud ready.
2. Create and configure an OIDC app.
3. Deploy your Open WebUI instance.
4. Set up integration on the Open WebUI side.
5. Add a user.
6. Make sure the application works correctly.

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

Getting startedGetting started

Sign up for Yandex Cloud and create a billing account:

1. Navigate to the management console and log in to Yandex Cloud or create a new account.
2. On the Yandex Cloud Billing page, make sure you have a billing account linked and it has the ACTIVE or TRIAL_ACTIVE status. If you do not have a billing account, create one and link a cloud to it.

If you have an active billing account, you can create or select a folder for your infrastructure on the cloud page.

Learn more about clouds and folders here.

Set up your environmentSet up your environment

1. Create a cloud network with a subnet in the same availability zone where you want to deploy your Open WebUI instance.

2. Reserve a static public IP address in the availability zone where you will deploy your Open WebUI instance.

3. In your cloud network, create a security group that allows the following traffic:

   Traffic direction	Port range	Protocol	Source / Destination name	IPv4 CIDR	Description
   Inbound	80	TCP	Address range	0.0.0.0/0	http
   Inbound	8080	TCP	Address range	0.0.0.0/0	8080
   Inbound	443	TCP	Address range	0.0.0.0/0	https
   Inbound	22	TCP	Address range	0.0.0.0/0	ssh
   Outbound	All	Any	Address range	0.0.0.0/0	any

4. Create a VM from the Ubuntu 24.04 LTS public image.

   Note

   When creating the VM instance, select the availability zone where your subnet resides, and assign the previously reserved public IP address and security group you created.

   We recommend using a VM configuration with at least 8 GB of RAM.

Required paid resourcesRequired paid resources

The cost of supporting the infrastructure created in the guide includes:

• Fee for a continuously running VM (see Yandex Compute Cloud pricing).
• Fee for using a static public IP address (see Yandex Virtual Private Cloud pricing).

Create an appCreate an app

Get the application’s credentialsGet the application’s credentials

Configure the redirect URIConfigure the redirect URI

Deploy your Open WebUI instanceDeploy your Open WebUI instance

In this tutorial, you will deploy your Open WebUI instance on a Compute Cloud VM instance using a Docker container.

To deploy Open WebUI:

1. Connect to the VM instance you created earlier. Depending on your VM settings, you can connect to it via SSH or OS Login.

2. Install and configure Docker:

   sudo apt update && sudo apt install docker.io docker-compose
   

3. Add the current local user to the docker group and start a new shell process with the updated user group membership:

   sudo usermod -aG docker $USER
   newgrp docker
   

4. Create a directory for your Open WebUI project:

   mkdir -p ~/projects/open-webui/certs
   cd ~/projects/open-webui/certs
   

5. Create a self-signed TLS certificate for your Open WebUI instance:

   Note

   A TLS certificate is required to enable https access to Open WebUI. When configuring OIDC app settings in Yandex Identity Hub, you must use the https:// schema in the Redirect URI.

   1. Generate a private key:

      openssl genrsa -out server.key 2048
      

   2. Create a self-signed certificate valid for one year:

      openssl req \
        -new \
        -x509 \
        -key server.key \
        -out server.crt \
        -days 365
      

      Fill out the form that appears. In the Common Name (e.g. server FQDN or YOUR name) field, specify the previously reserved static public IP address you assigned to the VM instance.

6. For convenience, rename the files you got:

   mv server.crt nginx-cert.crt
   mv server.key nginx-cert.key
   

7. Go to the Open WebUI project directory and create its configuration files:

   cd ~/projects/open-webui
   touch nginx.conf
   touch docker-compose.yml
   

8. Configure the Docker container environment for the initial launch of Open WebUI:

   Note

   You must perform the initial launch with SSO authentication disabled. This is required to create the project administrator account.

   1. In a text editor, open the docker-compose.yml file:

      nano docker-compose.yml
      

   2. Add the following configuration to the docker-compose.yml file:

      version: '3.8'
      
      services:
        open-webui:
          image: ghcr.io/open-webui/open-webui:main
          container_name: open-webui
          environment:
            - WEBUI_BASE_URL=http://<VM_IP_address>
          ports:
            - "8080:8080"
          volumes:
            - open-webui-data:/app/backend/data
          restart: unless-stopped
      
      volumes:
        open-webui-data:
      

      Where WEBUI_BASE_URL is the static public IP address of your VM instance with the http:// schema.

9. In the ~/projects/open-webui directory, run this command:

   docker-compose up -d
   

   Wait for all components and dependencies to download, unpack, and for the container to start:

   Creating network "open-webui_default" with the default driver
   Creating volume "open-webui_open-webui-data" with default driver
   Pulling open-webui (ghcr.io/open-webui/open-webui:main)...
   main: Pulling from open-webui/open-webui
   4f4f********: Pull complete
   a8ac********: Pull complete
   ...
   Digest: sha256:5c0d8f6d58ea276204b927205e43850689799f25420a67079cb988df********
   Status: Downloaded newer image for ghcr.io/open-webui/open-webui:main
   Creating open-webui ... done
   

10. Make sure the container is running:

    docker ps
    

    If everything is configured correctly, the command output should show the open-webui container with the Up (healthy) status.

    Note

    Depending on your VM instance configuration, starting the container may take a few minutes.

11. Create an Open WebUI administrator account:

    1. In your browser, open the address of your Open WebUI instance:

       http://<VM_IP_address>:8080
       

    2. On the Open WebUI page that opens, click Get started →.

    3. In the form that appears, enter the administrator’s full name, email address (login), and password.

    4. Click Create Admin Account.

    5. Close the browser window.

12. In the VM terminal, stop the Open WebUI container:

    docker-compose down
    

13. Set up your nginx configuration that will run inside the container:

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

       nano nginx.conf
       

    2. Add the following configuration to the nginx.conf file:

       server {
           listen 80;
           server_name <server_address>;
           return 301 https://$host$request_uri;
       }
       
       server {
           listen 443 ssl;
           server_name <server_address>;
       
           ssl_certificate     /etc/nginx/ssl/cert.crt;
           ssl_certificate_key /etc/nginx/ssl/key.key;
       
           location / {
               proxy_pass http://open-webui:8080;
               proxy_set_header Host $host;
               proxy_set_header X-Real-IP $remote_addr;
               proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
               proxy_set_header X-Forwarded-Proto $scheme;
               proxy_set_header X-Forwarded-Port $server_port;
       
               proxy_http_version 1.1;
               proxy_set_header Upgrade $http_upgrade;
               proxy_set_header Connection "upgrade";
               proxy_buffering off;
           }
       }
       

       Where server_name (in both sections) is the static public IP address of your VM instance. If there is a domain name reserved for the Open WebUI instance, use this domain name as the server address.

14. Update the Docker container configuration:

    1. In a text editor, open the docker-compose.yml file:

       nano docker-compose.yml
       

    2. Replace the docker-compose.yml contents with the following configuration, specifying your Yandex Identity Hub OIDC application settings:

       version: '3.8'
       
       services:
         open-webui:
           image: ghcr.io/open-webui/open-webui:main
           container_name: open-webui
           environment:
             - WEBUI_BASE_URL=https://<server_address>
             - ENABLE_OAUTH_SIGNUP=true
             - ENABLE_LOGIN_FORM=true
             - ENABLE_PERSISTENT_CONFIG=true
             - ENABLE_OAUTH_PERSISTENT_CONFIG=true
             - OPENID_REDIRECT_URI=https://<server_address>/oauth/oidc/callback
             - OAUTH_CLIENT_ID=<client_ID_value>
             - OAUTH_CLIENT_SECRET=<client_secret_value>
             - OPENID_PROVIDER_URL=<OpenID_Configuration_value>
             - OAUTH_PROVIDER_NAME=Yandex Identity Hub
             - OAUTH_SCOPES=openid email profile
       
           ports:
             - "8080:8080"
           volumes:
             - open-webui-data:/app/backend/data
           networks:
             - webui-net
           restart: unless-stopped
       
         nginx:
           image: nginx:alpine
           container_name: nginx-webui
           volumes:
             - ./certs/nginx-cert.crt:/etc/nginx/ssl/cert.crt:ro
             - ./certs/nginx-cert.key:/etc/nginx/ssl/key.key:ro
             - ./nginx.conf:/etc/nginx/conf.d/default.conf:ro
           ports:
             - "443:443"
             - "80:80"
           depends_on:
             - open-webui
           networks:
             - webui-net
           restart: unless-stopped
       
       volumes:
         open-webui-data:
       
       networks:
         webui-net:
           driver: bridge
       

       Where:

       • WEBUI_BASE_URL: Static public IP address of your VM instance with the https:// schema.

         If there is a domain name reserved for the Open WebUI instance, use this domain name as the server address.

       • OPENID_REDIRECT_URI: Redirect URI for your Open WebUI instance. It also includes the static public IP address of your VM instance or the domain name, if one is reserved for the Open WebUI instance.

       • OAUTH_CLIENT_ID: ClientID of your Yandex Identity Hub OIDC application.

       • OAUTH_CLIENT_SECRET: Yandex Identity Hub OIDC app secret.

       • OPENID_PROVIDER_URL: OpenID Configuration of your Yandex Identity Hub OIDC application.

15. In the ~/projects/open-webui directory, restart the configuration:

    docker-compose up -d
    

    Wait for all components and dependencies to download, unpack, and for the containers to start.

16. Make sure the containers are running:

    docker ps
    

    If everything is configured correctly, the command output should show both the nginx and open-webui containers with an Up or Healthy status.

    Note

    Depending on your VM instance configuration, starting the containers may take a few minutes.

Set up the integration on the Open WebUI side .Set up the integration on the Open WebUI side .

Complete the Open WebUI setup in the user interface:

1. In a browser window, open the address of your Open WebUI instance:

   https://<server_address>
   

2. On the login page, enter the administrator's email address and password, then click Sign in.

3. In the bottom-left corner, click your profile icon, select Settings, and navigate to Authentication.

4. In the Default User Role field, select user.

5. Make sure the OAuth / OIDC option is enabled and the following fields contain the correct data:

   • Provider Name: Yandex Identity Hub.
   • Provider URL: OpenID Configuration value from your Yandex Identity Hub OIDC application.
   • Client ID: ClientID value from your Yandex Identity Hub OIDC application.
   • Client Secret: Yandex Identity Hub OIDC app secret.
   • Redirect URI: Redirect URI value from your Open WebUI instance.

   If needed, populate these fields with the values you previously specified for the environment variables in docker-compose.yml.

6. Configure the additional fields as follows:

   • Scopes: openid email profile.
   • Email Claim: email.
   • Username Claim: preferred_username.
   • Sub Claim: sub.

7. Enable the OAuth Signup and Merge Accounts by Email options.

8. Leave all other settings unchanged and click Save.

Add a userAdd a user

For your organization's users to be able to authenticate in Open WebUI with Yandex Identity Hub's OIDC app, you need to explicitly add these users and/or user groups to the OIDC application.

Add a user to the application:

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.

Make sure your application works correctlyMake sure your application works correctly

To make sure both your OIDC app and Open WebUI integration work correctly, authenticate to Open WebUI as one of the users you added to the app.

Follow these steps:

1. In your browser, navigate to your Open WebUI instance address:

   https://<server_address>
   

2. If you were logged in to Open WebUI, log out.

3. On the Open WebUI login page, click Continue with Yandex Identity Hub.

4. On the Yandex Cloud authentication page, enter the Yandex Identity Hub user's email and password. The user or group they belong to must be added to the application.

5. Make sure you have successfully authenticated in Open WebUI.

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

To stop paying for the resources you created:

1. Delete the VM.

2. Delete the static public IP address.

3. If required, delete your other Virtual Private Cloud resources:

   1. Security group.
   2. Subnet.
   3. Cloud network.

An availability zone is an infrastructure within a data center that hosts Yandex Cloud. For more information, see Availability zones.