[Yandex Cloud documentation](../../../index.md) > [Yandex Identity Hub](../../index.md) > [Tutorials](../index.md) > [Setting up single sign-on (SSO) for apps](index.md) > Open WebUI # Creating an OIDC application in Yandex Identity Hub for integration with Open WebUI [Open WebUI](https://openwebui.com/) 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](https://en.wikipedia.org/wiki/OpenID#OpenID_Connect_(OIDC)) (OIDC) authentication to provide secure SSO for your organization's users. For your [organization's](../../concepts/organization.md) users to be able to authenticate to Open WebUI via OpenID Connect SSO, create an [OIDC app](../../concepts/applications/oidc.md) 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](../../security/index.md#organization-manager-oauthApplications-admin) or higher. {% note info %} This guide deploys Open WebUI on a Yandex Compute Cloud [VM instance](../../../compute/concepts/vm.md) as an example scenario to demonstrate the integration. {% endnote %} To provide your organization's users with access to Open WebUI: 1. [Get your cloud ready](#before-you-begin). 1. [Create and configure an OIDC app](#create-app). 1. [Deploy your Open WebUI instance](#deploy-open-webui). 1. [Set up integration on the Open WebUI side](#setup-integration). 1. [Add a user](#add-user). 1. [Make sure the application works correctly](#validate). If you no longer need the resources you created, [delete them](#clear-out). ## Getting started {#before-you-begin} Sign up for Yandex Cloud and create a [billing account](../../../billing/concepts/billing-account.md): 1. Navigate to the [management console](https://console.yandex.cloud) and log in to Yandex Cloud or create a new account. 1. On the **[Yandex Cloud Billing](https://center.yandex.cloud/billing/accounts)** page, make sure you have a billing account linked and it has the `ACTIVE` or `TRIAL_ACTIVE` [status](../../../billing/concepts/billing-account-statuses.md). If you do not have a billing account, [create one](../../../billing/quickstart/index.md) and [link](../../../billing/operations/pin-cloud.md) a cloud to it. If you have an active billing account, you can create or select a [folder](../../../resource-manager/concepts/resources-hierarchy.md#folder) for your infrastructure on the [cloud page](https://console.yandex.cloud/cloud). [Learn more about clouds and folders here](../../../resource-manager/concepts/resources-hierarchy.md). ### Set up your environment {#prepare} 1. [Create](../../../vpc/operations/network-create.md) a cloud network with a [subnet](../../../vpc/operations/subnet-create.md) in the same [availability zone](*availability_zone) where you want to deploy your Open WebUI instance. 1. [Reserve](../../../vpc/operations/get-static-ip.md) a static public IP address in the availability zone where you will deploy your Open WebUI instance. 1. 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` | 1. [Create](../../../compute/operations/vm-create/create-linux-vm.md) a VM from the [Ubuntu 24.04 LTS](https://yandex.cloud/en/marketplace/products/yc/ubuntu-2404-lts-oslogin) public image. {% note info %} 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. {% endnote %} ### Required paid resources {#paid-resources} The cost of supporting the infrastructure created in the guide includes: * Fee for a continuously running VM (see [Yandex Compute Cloud pricing](../../../compute/pricing.md)). * Fee for using a static public IP address (see [Yandex Virtual Private Cloud pricing](../../../vpc/pricing.md)). ## Create an app {#create-app} {% list tabs group=instructions %} - Cloud Center UI {#cloud-center} 1. Go 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. In the top-right corner, 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 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 a name for your new app: `open-webui-oidc-app`. 1. In the **Folder** field, select the folder where you want to create an OAuth client for your app. 1. Optionally, in the **Description** field, enter a description for the new app. 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 application**. {% endlist %} ### Get the application’s 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, select ![shapes-4](../../../_assets/console-icons/shapes-4.svg) **Apps** and select the OIDC app. 1. On the **Overview** tab, under **Identity provider (IdP) configuration**, copy the parameter values you need to specify in Open WebUI: * `ClientID`: Unique application ID. * `OpenID Configuration`: URL with the configuration of all parameters required to set up the integration. 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**. {% endlist %} ### Configure the redirect URI {#setup-redirect} {% 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 `open-webui-oidc-app`. 1. At the top right, click ![pencil](../../../_assets/console-icons/pencil.svg) **Edit** and in the window that opens: 1. In the **Redirect URI** field, specify the authentication endpoint for your Open WebUI instance: ```text https:///oauth/oidc/callback ``` Where `` is your previously reserved static public IP address. {% note info %} If there is a domain name reserved for the Open WebUI instance, use this domain name as the server address. {% endnote %} 1. Under **OAuth/OIDC security**, disable the **Require PKCE** option so that Yandex Identity Hub does not require the external application to use the [PKCE](*pkce_info) security extension when exchanging data. [*pkce_info]: PKCE is a security extension used in OAuth 2.0 to minimize the risk of authentication data interception. For more information, see [PKCE](../../concepts/applications/oidc.md#pkce). 1. Click **Save**. {% endlist %} ## Deploy your Open WebUI instance {#deploy-open-webui} In this tutorial, you will deploy your Open WebUI instance on a Compute Cloud VM instance using a [Docker](https://www.docker.com/) container. To deploy Open WebUI: 1. Connect to the VM instance you [created earlier](#prepare). Depending on your VM settings, you can connect to it via [SSH](../../../compute/operations/vm-connect/ssh.md) or [OS Login](../../../compute/operations/vm-connect/os-login.md). 1. Install and configure Docker: ```bash sudo apt update && sudo apt install docker.io docker-compose ``` 1. Add the current local user to the `docker` group and start a new shell process with the updated user group membership: ```bash sudo usermod -aG docker $USER newgrp docker ``` 1. Create a directory for your Open WebUI project: ```bash mkdir -p ~/projects/open-webui/certs cd ~/projects/open-webui/certs ``` 1. Create a self-signed TLS certificate for your Open WebUI instance: {% note info %} 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`. {% endnote %} 1. Generate a private key: ```bash openssl genrsa -out server.key 2048 ``` 1. Create a self-signed certificate valid for one year: ```bash 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](#prepare) static public IP address you assigned to the VM instance. 1. For convenience, rename the files you got: ```bash mv server.crt nginx-cert.crt mv server.key nginx-cert.key ``` 1. Go to the Open WebUI project directory and create its configuration files: ```bash cd ~/projects/open-webui touch nginx.conf touch docker-compose.yml ``` 1. Configure the Docker container environment for the initial launch of Open WebUI: {% note info %} You must perform the initial launch with SSO authentication disabled. This is required to create the project administrator account. {% endnote %} 1. In a text editor, open the `docker-compose.yml` file: ```bash nano docker-compose.yml ``` 1. Add the following configuration to the `docker-compose.yml` file: ```yml version: '3.8' services: open-webui: image: ghcr.io/open-webui/open-webui:main container_name: open-webui environment: - WEBUI_BASE_URL=http:// 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. 1. In the `~/projects/open-webui` directory, run this command: ```bash docker-compose up -d ``` Wait for all components and dependencies to download, unpack, and for the container to start: ```text 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 ``` 1. Make sure the container is running: ```bash docker ps ``` If everything is configured correctly, the command output should show the `open-webui` container with the `Up (healthy)` status. {% note info %} Depending on your VM instance configuration, starting the container may take a few minutes. {% endnote %} 1. Create an Open WebUI administrator account: 1. In your browser, open the address of your Open WebUI instance: ```text http://:8080 ``` 1. On the Open WebUI page that opens, click **Get started →**. 1. In the form that appears, enter the administrator’s full name, email address (login), and password. 1. Click **Create Admin Account**. 1. Close the browser window. 1. In the VM terminal, stop the Open WebUI container: ```bash docker-compose down ``` 1. Set up your [nginx](https://nginx.org) configuration that will run inside the container: 1. In a text editor, open the `nginx.conf` configuration file: ```bash nano nginx.conf ``` 1. Add the following configuration to the `nginx.conf` file: ```json server { listen 80; server_name ; return 301 https://$host$request_uri; } server { listen 443 ssl; server_name ; 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. 1. Update the Docker container configuration: 1. In a text editor, open the `docker-compose.yml` file: ```bash nano docker-compose.yml ``` 1. Replace the `docker-compose.yml` contents with the following configuration, specifying your Yandex Identity Hub OIDC application settings: ```yml version: '3.8' services: open-webui: image: ghcr.io/open-webui/open-webui:main container_name: open-webui environment: - WEBUI_BASE_URL=https:// - ENABLE_OAUTH_SIGNUP=true - ENABLE_LOGIN_FORM=true - ENABLE_PERSISTENT_CONFIG=true - ENABLE_OAUTH_PERSISTENT_CONFIG=true - OPENID_REDIRECT_URI=https:///oauth/oidc/callback - OAUTH_CLIENT_ID= - OAUTH_CLIENT_SECRET= - OPENID_PROVIDER_URL= - 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. 1. In the `~/projects/open-webui` directory, restart the configuration: ```bash docker-compose up -d ``` Wait for all components and dependencies to download, unpack, and for the containers to start. 1. Make sure the containers are running: ```bash 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 info %} Depending on your VM instance configuration, starting the containers may take a few minutes. {% endnote %} ## Set up the integration on the Open WebUI side {#setup-integration}. Complete the Open WebUI setup in the user interface: 1. In a browser window, open the address of your Open WebUI instance: ```text https:// ``` 1. On the login page, enter the administrator's email address and password, then click **Sign in**. 1. In the bottom-left corner, click your profile icon, select **Settings**, and navigate to **Authentication**. 1. In the **Default User Role** field, select `user`. 1. 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`. 1. Configure the additional fields as follows: * **Scopes**: `openid email profile`. * **Email Claim**: `email`. * **Username Claim**: `preferred_username`. * **Sub Claim**: `sub`. 1. Enable the **OAuth Signup** and **Merge Accounts by Email** options. 1. Leave all other settings unchanged and click **Save**. ## Add a user {#add-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](../../concepts/groups.md) to the OIDC application. {% note info %} Users and groups added to an OIDC application can be managed by any user with the `organization-manager.oidcApplications.userAdmin` [role](../../security/index.md#organization-manager-oidcApplications-userAdmin) or higher. {% endnote %} Add a user to the application: {% 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** and select the required 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 required user or user group. 1. Click **Add**. {% 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). ## Make sure your application works correctly {#validate} 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: ```text https:// ``` 1. If you were logged in to Open WebUI, log out. 1. On the Open WebUI login page, click **Continue with Yandex Identity Hub**. 1. 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. 1. Make sure you have successfully authenticated in Open WebUI. ## How to delete the resources you created {#clear-out} To stop paying for the resources you created: 1. [Delete](../../../compute/operations/vm-control/vm-delete.md) the VM. 1. [Delete](../../../vpc/operations/address-delete.md) the static public IP address. 1. If required, delete your other Virtual Private Cloud resources: 1. [Security group](../../../vpc/operations/security-group-delete.md). 1. [Subnet](../../../vpc/operations/subnet-delete.md). 1. [Cloud network](../../../vpc/operations/network-delete.md). [*availability_zone]: An availability zone is an infrastructure within a data center that hosts Yandex Cloud. For more information, see [Availability zones](../../../overview/concepts/geo-scope.md).