Discuss with expertTry it for free
© 2026 Direct Cursus Technology L.L.C.

Configuring authentication in OpenVPN Community Edition via Yandex Identity Hub over the OIDC protocol

Written by
Updated at July 1, 2026
View in Markdown

OpenVPN Community Edition is a free, open-source version of OpenVPN for establishing secure VPN connections. Starting with version 2.6.2, OpenVPN Community Edition supports authentication through external providers via the OpenID Connect (OIDC) protocol with the help of the openvpn-auth-oauth2 plugin.

For the users of your organization to be able to authenticate to OpenVPN Community Edition via OpenID Connect SSO, create an OIDC app and configure it both in Yandex Identity Hub and OpenVPN.

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

To set up authentication to OpenVPN Community Edition via Yandex Identity Hub for the users of your organization:

  1. Get your cloud ready.
  2. Create the infrastructure.
  3. Install OpenVPN.
  4. Create a certificate authority.
  5. Configure an OpenVPN server.
  6. Create an OIDC app in Yandex Identity Hub.
  7. Install and configure openvpn-auth-oauth2.
  8. Test the integration.

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

Get your cloud ready

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.

The infrastructure support cost includes:

Create the infrastructure

  1. Create a VM on Ubuntu 24.04 with a public IP address. This VM will act as an OpenVPN server.

  2. Connect to the VM over SSH:

    ssh <username>@<VM_public_IP_address>

  3. Make sure you have the following:

    • Domain name pointing to the VM's public IP address. You will need it to configure the openvpn-auth-oauth2 plugin.
    • TLS certificate for this domain name. You can use a certificate from Yandex Certificate Manager.

Install OpenVPN

Note

The openvpn-auth-oauth2 plugin is supported starting from OpenVPN 2.6.2.

  1. Update your package list and install OpenVPN and Easy-RSA:

    sudo apt update && sudo apt install openvpn easy-rsa

  2. Check the OpenVPN version:

    openvpn --version

    Result:

    OpenVPN 2.6.19 x86_64-pc-linux-gnu [SSL (OpenSSL)] [LZO] [LZ4] [EPOLL] [PKCS11] [MH/PKTINFO] [AEAD] [DCO]
library versions: OpenSSL 3.0.13 30 Jan 2024, LZO 2.10
...

    Make sure the version is not lower than 2.6.2.

Create a certificate authority

  1. Create a folder for Easy-RSA and copy the required files into it:

    mkdir -p ~/openvpn-ca
cd ~/openvpn-ca
sudo mkdir /etc/openvpn/easy-rsa
sudo cp -r /usr/share/easy-rsa/* /etc/openvpn/easy-rsa/
cd /etc/openvpn/easy-rsa/

  2. Initialize the public key infrastructure (PKI):

    sudo ./easyrsa init-pki

  3. Create a root certificate authority (CA). This command will ask for a password (at least four characters) and a common name: any CA name, e.g., YC-OpenVPN-CA:

    sudo ./easyrsa build-ca

  4. Generate a certificate and a server key:

    sudo ./easyrsa gen-req server nopass
sudo ./easyrsa sign-req server server

    When signing the certificate, enter yes to confirm.

  5. Generate the Diffie-Hellman parameters:

    sudo ./easyrsa gen-dh

Configure an OpenVPN server

Copy the certificates and keys

Copy the necessary files to the OpenVPN working folder:

sudo cp pki/ca.crt pki/private/server.key pki/issued/server.crt /etc/openvpn/
sudo cp /etc/openvpn/easy-rsa/pki/dh.pem /etc/openvpn/

Create a server configuration file

  1. Create a file named /etc/openvpn/server.conf:

    sudo nano /etc/openvpn/server.conf

  2. Add the following content to the file:

    port 1194
proto udp
dev tun
ca ca.crt
cert server.crt
key server.key
dh dh.pem
auth SHA256
server 10.8.0.0 255.255.255.0
ifconfig-pool-persist ipp.txt
push "redirect-gateway def1 bypass-dhcp"
push "dhcp-option DNS 8.8.8.8"
push "dhcp-option DNS 8.8.4.4"
keepalive 10 120
cipher AES-256-GCM
user nobody
group nogroup
persist-key
persist-tun
status openvpn-status.log
log-append /var/log/openvpn.log
verb 3

Configure your network

  1. Enable IP forwarding:

    echo 'net.ipv4.ip_forward=1' | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

  2. Open a port for OpenVPN in your firewall:

    sudo ufw allow 1194/udp
sudo ufw allow OpenSSH

  3. Configure NAT masquerading for the VPN subnet:

    sudo iptables -t nat -A POSTROUTING -s 10.8.0.0/24 -o eth0 -j MASQUERADE
sudo iptables-save | sudo tee /etc/iptables/rules.v4

Start the OpenVPN server

  1. Start the OpenVPN server:

    sudo systemctl start openvpn@server
sudo systemctl enable openvpn@server

  2. Check the OpenVPN server status:

    systemctl status openvpn@server

Create a client certificate

  1. Go to the Easy-RSA folder and generate a client certificate:

    cd /etc/openvpn/easy-rsa/
sudo ./easyrsa gen-req client1 nopass
sudo ./easyrsa sign-req client client1

  2. Create a client configuration file named ~/client1.ovpn:

    nano ~/client1.ovpn

  3. Add the following content to the file by specifying the certificates and keys:

    client
dev tun
proto udp
remote <public_IP_address_or_server_domain> 1194
resolv-retry infinite
nobind
persist-key
persist-tun
remote-cert-tls server
auth SHA256
cipher AES-256-GCM
verb 3
<ca>
-----BEGIN CERTIFICATE-----
# Paste the contents of /etc/openvpn/ca.crt
-----END CERTIFICATE-----
</ca>
<cert>
-----BEGIN CERTIFICATE-----
# Paste the contents of /etc/openvpn/easy-rsa/pki/issued/client1.crt
-----END CERTIFICATE-----
</cert>
<key>
-----BEGIN PRIVATE KEY-----
# Paste the contents of /etc/openvpn/easy-rsa/pki/private/client1.key
-----END PRIVATE KEY-----
</key>
key-direction 1

Create an OIDC app in Yandex Identity Hub

  1. Log in to Yandex Identity Hub.

  2. In the left-hand panel, select  Apps.

  3. In the center of the page, click Create application and in the window that opens:

    1. Select the OIDC (OpenID Connect) single sign-on method.
    2. In the Name field, specify a name for the new app, e.g., openvpn-oidc-app.
    3. In the Folder field, select the folder where you want to create an OAuth client for your app.
    4. Optionally, in the Description field, enter a description for the new app.
    5. Click Create application.

  4. Click Edit at the top right of the new app's page and in the window that opens:

    1. In the Redirect URI field, enter the Redirect URI in the following format:

      https://<domain_name>:9000/oauth2/callback

    2. In the Scopes field, mark the email and profile attributes.

    3. Click Save.

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

    Save the secret value for later to configure the openvpn-auth-oauth2 plugin.

  6. Under Identity provider (IdP) configuration, copy the ClientID field value for later to configure the plugin.

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.

  1. Create an OAuth client:

    yc iam oauth-client create \
  --name openvpn-oauth-client \
  --scopes openid,email,profile \
  --redirect-uris "https://<domain_name>:9000/oauth2/callback"

    Where:

    • --name: OAuth client name.
    • --scopes: User attributes available to OpenVPN:
      • openid: User ID. Required attribute.
      • email: User email address.
      • profile: Additional user details.
    • --redirect-uris: Redirect URI after authentication.

    Result:

    id: ajeqqip130i1********
name: openvpn-oauth-client
folder_id: b1g500m2195v********
status: ACTIVE

    Save the id field value; you will need it later to create the app.

  2. 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: "2025-10-21T10:14:17.861652377Z"
secret_value: yccs__939233b8ac********

    Save the secret_value; you will need it later to configure the openvpn-auth-oauth2 plugin.

  3. Create an OIDC app:

    yc organization-manager idp application oauth application create \
  --organization-id <organization_ID> \
  --name openvpn-oidc-app \
  --description "OIDC application for integration with OpenVPN Community Edition" \
  --client-id <OAuth_client_ID> \
  --authorized-scopes openid,email,profile

    Where:

    • --organization-id: Organization ID.
    • --name: OIDC app name.
    • --description: Application description. This is an optional setting.
    • --client-id: OAuth client ID you got in the previous step.
    • --authorized-scopes: Same attributes as when creating the OAuth client.

    Result:

    id: ek0o663g4rs2********
name: openvpn-oidc-app
organization_id: bpf2c65rqcl8********
client_grant:
  client_id: ajeqqip130i1********
  authorized_scopes:
    - openid
    - email
    - profile
status: ACTIVE
created_at: "2025-10-21T10:51:28.790866Z"

Add users to the application

For the users of your organization to be able to authenticate to OpenVPN through the Yandex Identity Hub OIDC app, add the users and/or user groups to the app.

Note

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

  1. Log in to Yandex Identity Hub.
  2. In the left-hand panel, select Apps and select the new app.
  3. Navigate to the Users and groups tab.
  4. Click Add users.
  5. In the window that opens, select the required user or user group.
  6. Click Add.

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.

  1. Get the user ID or user group ID.

  2. Add a user or group to the application:

    yc organization-manager idp application oauth application add-assignments \
  --id <app_ID> \
  --subject-id <user_or_group_ID>

    Where:

    • --id: OIDC app ID.
    • --subject-id: User or user group ID.

    Result:

    assignment_deltas:
  - action: ADD
    assignment:
      subject_id: ajetvnq2mil8********

Install and configure openvpn-auth-oauth2

Install the plugin

On the VM with OpenVPN, run the following commands:

curl -L https://raw.githubusercontent.com/jkroepke/openvpn-auth-oauth2/refs/heads/main/packaging/apt/openvpn-auth-oauth2.sources | sudo tee /etc/apt/sources.list.d/openvpn-auth-oauth2.sources
sudo apt update
sudo apt install openvpn-auth-oauth2

Prepare a TLS certificate

The openvpn-auth-oauth2 plugin requires a TLS certificate to protect the connection on port 9000.

Tip

The plugin developers recommend not to terminate TLS connections directly in openvpn-auth-oauth2. Use a separate reverse proxy server instead. You can implement this approach using Yandex Application Load Balancer.

  1. If you have a certificate in Yandex Certificate Manager, export it using the Yandex Cloud CLI:

    yc certificate-manager certificates content \
  --id <certificate_ID> \
  --chain tls.crt \
  --key tls.key

  2. Create a folder for the plugin files and move the certificate and key into it:

    sudo mkdir -p /etc/openvpn-auth-oauth2
sudo mv tls.crt tls.key /etc/openvpn-auth-oauth2/
sudo chown root:openvpn-auth-oauth2 /etc/openvpn-auth-oauth2/tls.key
sudo chown root:openvpn-auth-oauth2 /etc/openvpn-auth-oauth2/tls.crt

Create a plugin configuration file

  1. Create a file named /etc/openvpn-auth-oauth2/config.yaml:

    sudo nano /etc/openvpn-auth-oauth2/config.yaml

  2. Add the following content to the file:

    http:
  listen: :9000
  baseurl: https://<domain_name>:9000
  tls: true
  key: /etc/openvpn-auth-oauth2/tls.key
  cert: /etc/openvpn-auth-oauth2/tls.crt
  secret: <any_16_character_long_string>
openvpn:
  addr: unix:///run/openvpn/server.sock
  password: <management_interface_password>
oauth2:
  issuer: https://auth.yandex.cloud
  client:
    id: <OAuth_client_ID>
    secret: <application_secret_value>
  endpoint:
    discovery: https://auth.yandex.cloud/.well-known/openid-configuration
  scopes:
    - openid
    - profile
    - email

    Where:

    • http.baseurl: Plugin's public URL in https://<domain_name>:9000 format.
    • http.secret: Any string of at least 16 characters for protection of sessions.
    • openvpn.password: Password for connecting the plugin to the OpenVPN management interface. Save this value; it must match the contents of the file named /etc/openvpn/password.txt.
    • oauth2.client.id: OAuth client ID you got when creating the OIDC app.
    • oauth2.client.secret: Application secret value saved when creating the OIDC app.

    For more on setup, see this openvpn-auth-oauth2 guide.

Configure the OpenVPN management interface

  1. Create a file with the management interface password:

    echo '<management_interface_password>' | sudo tee /etc/openvpn/password.txt
sudo chmod 600 /etc/openvpn/password.txt

    Warning

    The password value in the /etc/openvpn/password.txt file must match the value of the openvpn.password parameter in the /etc/openvpn-auth-oauth2/config.yaml file.

  2. Open the /etc/openvpn/server.conf file and add the following lines to the end:

    management /run/openvpn/server.sock unix /etc/openvpn/password.txt
management-hold
management-client-auth

  3. Restart OpenVPN:

    sudo systemctl restart openvpn@server
sudo systemctl status openvpn@server

  4. Open port 9000 in the firewall:

    sudo ufw allow 9000/tcp

Run the plugin as a system service

  1. Create a systemd unit file:

    sudo nano /etc/systemd/system/openvpn-auth-oauth2.service

    Add the following content to the file:

    [Unit]
Description=openvpn-auth-oauth2
Requires=openvpn@server.service
After=openvpn@server.service

[Service]
ExecStart=openvpn-auth-oauth2 --config /etc/openvpn-auth-oauth2/config.yaml
Restart=on-failure
User=root

[Install]
WantedBy=multi-user.target

  2. Restart the systemd configuration, enable and start the service:

    sudo systemctl daemon-reload
sudo systemctl enable openvpn-auth-oauth2.service
sudo systemctl start openvpn-auth-oauth2.service
sudo systemctl status openvpn-auth-oauth2.service

Test the integration

  1. Install the OpenVPN client on the client device.

  2. Import the client1.ovpn configuration file into the OpenVPN client.

  3. Initiate a connection to the VPN server. The OpenVPN client will open your browser and redirect you to the Yandex Cloud authentication page.

  4. Enter the credentials of the user added to the OIDC app.

  5. After successful authentication, the VPN connection will be established.

  6. Check your connection to the VPN server:

    ping 10.8.0.1

    The expected result is a successful zero packet loss ping.

How to delete the resources you created

To stop paying for the resources you created:

  1. Delete the VM.
  2. Delete the OIDC app.
Previous
OpenVPN Access Server
Next
SAML