Home

openvpn-auth-oauth2 connects OpenVPN Community Server to an OpenID Connect (OIDC) provider. Users authenticate in their browser, and the result is returned to OpenVPN through its management interface.

Important

OpenVPN Access Server is not supported. Before deploying, check the server and client requirements.

Start here

Choose the path that matches what you want to do:

Goal	Start with
Evaluate the login experience locally	Run the Docker Compose demo
Deploy the service for the first time	Getting Started
Upgrade an existing version 1 deployment	Upgrade to version 2
Fix a connection or login problem	Troubleshooting and the FAQ
Understand the authentication design	How OIDC SSO works with OpenVPN

Documentation by task

Install and configure

• Installation covers Linux packages and building from source.
• Configuration is the complete settings reference.
• Providers contains registration and configuration examples for supported identity providers.
• HTTPS Listener explains reverse-proxy and native TLS options.
• OpenVPN Plugin is a stable integration for Linux AMD64, Linux ARM64, and FreeBSD AMD64 that keeps OpenVPN's management interface available for other tools.

Control access and identity

• Client token validation restricts access with token claims and CEL expressions.
• OpenVPN Username controls how OIDC identities appear in OpenVPN.
• Client-specific configuration assigns routes and other OpenVPN settings to identities.
• Non-interactive session refresh reduces repeated browser logins.

Operate and extend

• Security considerations describes threats and recommended mitigations.
• Filesystem Permissions covers package and systemd file access.
• Management interface pass-through lets another management client connect through openvpn-auth-oauth2 when using the direct integration.
• Layout Customization changes the browser result page.

The sidebar contains every documentation page.

Authentication flow

sequenceDiagram
    participant Client as OpenVPN client
    participant Server as OpenVPN server
    participant Auth as openvpn-auth-oauth2
    participant Browser
    participant IdP as OIDC provider

    Client->>Server: Connect
    Server->>Auth: CLIENT:CONNECT
    Auth-->>Server: WEB_AUTH URL
    Server-->>Client: WEB_AUTH URL
    Client->>Browser: Open URL
    Browser->>IdP: Sign in
    IdP-->>Browser: Redirect with authorization code
    Browser->>Auth: OAuth2 callback
    Auth->>IdP: Exchange authorization code
    IdP-->>Auth: ID and access tokens
    Auth->>Server: Accept or deny client
    Server-->>Client: Connection established

    Server->>Auth: CLIENT:REAUTH
    alt Non-interactive reauthentication
        Auth->>IdP: Refresh token
        IdP-->>Auth: New ID and access tokens
        Auth->>Server: Accept or deny client
    else Internal refresh authentication
        Auth->>Auth: Validate stored authentication state
        Auth->>Server: Accept or deny client
    else Interactive reauthentication required
        Auth-->>Server: WEB_AUTH URL
        Server-->>Client: WEB_AUTH URL
        Client->>Browser: Open URL
        Browser->>IdP: Sign in
        IdP-->>Browser: Redirect with authorization code
        Browser->>Auth: OAuth2 callback
        Auth->>IdP: Exchange authorization code
        IdP-->>Auth: ID and access tokens
        Auth->>Server: Accept or deny client
    end

Loading