feat: Allow custom claim for OpenVPN username (#751)

Author: jkroepke

.idea/go.imports.xml

@@ -100,6 +100,7 @@ func TestFull(t *testing.T) {
 					"--http.listen=" + httpListener.Addr().String(),
 					"--http.assets-path=../../internal/ui/assets",
 					"--openvpn.addr=tcp://" + managementInterface.Addr().String(),
+					"--oauth2.openvpn-username-claim", "sub",
 					"--oauth2.issuer", resourceServer.URL,
 					"--oauth2.client.id", clientCredentials.ID,
 					"--oauth2.client.secret", clientCredentials.Secret.String(),

.idea/inspectionProfiles/Project_Default.xml

@@ -57,6 +57,7 @@ func TestReload(t *testing.T) {
 			"--http.listen=" + httpListener.Addr().String(),
 			"--http.assets-path=../../internal/ui/assets",
 			"--openvpn.addr=tcp://" + managementInterface.Addr().String(),
+			"--oauth2.openvpn-username-claim=sub",
 			"--oauth2.issuer", resourceServer.URL,
 			"--oauth2.client.id", clientCredentials.ID,
 			"--oauth2.client.secret", clientCredentials.Secret.String(),

cmd/openvpn-auth-oauth2/full_test.go

@@ -78,6 +78,10 @@ Usage of openvpn-auth-oauth2:
     	oauth2 issuer (env: CONFIG_OAUTH2_ISSUER)
   --oauth2.nonce
     	If true, a nonce will be defined on the auth URL which is expected inside the token. (env: CONFIG_OAUTH2_NONCE) (default true)
+  --oauth2.openvpn-username-cel string
+    	CEL expression to extract the username from the token. The expression must evaluate to a string value. Example: oauth2TokenClaims.sub Note: oauth2.openvpn-username-claim and oauth2.openvpn-username-cel cannot be set at the same time. (env: CONFIG_OAUTH2_OPENVPN__USERNAME__CEL)
+  --oauth2.openvpn-username-claim string
+    	The claim name in the ID Token which should be used as username in OpenVPN. If empty, the common name is used. (env: CONFIG_OAUTH2_OPENVPN__USERNAME__CLAIM) (default "preferred_username")
   --oauth2.pkce
     	If true, Proof Key for Code Exchange (PKCE) RFC 7636 is used for token exchange. (env: CONFIG_OAUTH2_PKCE) (default true)
   --oauth2.provider string
@@ -100,18 +104,18 @@ Usage of openvpn-auth-oauth2:
     	If true, openvpn-auth-oauth2 uses the OIDC UserInfo endpoint to fetch additional information about the user (e.g. groups). (env: CONFIG_OAUTH2_USER__INFO)
   --oauth2.validate.acr value
     	oauth2 required acr values. Comma separated list. Example: phr,phrh (env: CONFIG_OAUTH2_VALIDATE_ACR)
+  --oauth2.validate.cel string
+    	CEL expression for custom token validation. The expression must evaluate to a boolean value. Example: openVPNUserCommonName == oauth2TokenClaims.preferred_username (env: CONFIG_OAUTH2_VALIDATE_CEL)
   --oauth2.validate.common-name string
     	validate common_name from OpenVPN with ID Token claim. For example: preferred_username or sub (env: CONFIG_OAUTH2_VALIDATE_COMMON__NAME)
   --oauth2.validate.common-name-case-sensitive
     	If true, openvpn-auth-oauth2 will validate the common case in sensitive mode (env: CONFIG_OAUTH2_VALIDATE_COMMON__NAME__CASE__SENSITIVE)
   --oauth2.validate.groups value
     	oauth2 required user groups. If multiple groups are configured, the user needs to be least in one group. Comma separated list. Example: group1,group2,group3 (env: CONFIG_OAUTH2_VALIDATE_GROUPS)
-  --oauth2.validate.cel string
-    	CEL expression for custom token validation. The expression must evaluate to a boolean value.
   --oauth2.validate.ipaddr
-    	validate client ipaddr between VPN and oidc token (env: CONFIG_OAUTH2_VALIDATE_IPADDR)
+    	validate client ipaddr between VPN and OIDC token (env: CONFIG_OAUTH2_VALIDATE_IPADDR)
   --oauth2.validate.issuer
-    	validate issuer from oidc discovery (env: CONFIG_OAUTH2_VALIDATE_ISSUER) (default true)
+    	validate issuer from OIDC discovery (env: CONFIG_OAUTH2_VALIDATE_ISSUER) (default true)
   --oauth2.validate.roles value
     	oauth2 required user roles. If multiple role are configured, the user needs to be least in one role. Comma separated list. Example: role1,role2,role3 (env: CONFIG_OAUTH2_VALIDATE_ROLES)
   --openvpn.addr value
@@ -271,3 +275,7 @@ See [Non-interactive session refresh](Non-interactive%20session%20refresh) for m
 ## Client specific configuration
 
 See [Client specific configuration](Client%20specific%20configuration) for more information.
+
+## OpenVPN username handling
+
+See [OpenVPN Username](OpenVPN%20Username) for more information.

cmd/openvpn-auth-oauth2/reload_test.go

@@ -16,50 +16,7 @@ A: Read the following documentation to understand the re-authentication behavior
 For the Google Provider,
 expand the page [Providers](Providers) and look for Google consent screen always asking for permission grant.
 
-## Q: Note Regarding Passing Usernames from OAuth2 Provider to OpenVPN
 
-A: It's important to note that currently,
-there is no mechanism to pass the username from the OAuth2 provider back to OpenVPN.
-OpenVPN does not offer such an interface at present.
-This limitation applies to scenarios where the IP persistence file or statistics may contain empty usernames.
-
-For future enhancements in this area,
-we encourage users to up-vote the relevant feature requests on the OpenVPN GitHub repository.
-You can find and support these requests at the following link:
-[Feature Request on GitHub](https://github.com/OpenVPN/openvpn/issues/299)
-
-## Q: `mismatch: OpenVPNclient is empty` / `username-as-common-name`
-
-A: When setting up `username-as-common-name` on the OpenVPN server, it's crucial to also configure `openvpn.common-name.environment-variable-name` to `username`.
-
-This configuration is indispensable because `username-as-common-name` functions post-authentication. Aligning the environment variable name with `username` guarantees smooth operation.
-
-On authentication, it's expected that common-name is not the values of the username. That may mis-leading, because after authentication, the common name has the correct value at OpenVPN logs.
-
-**Upstream Issue:** [`OpenVPN/openvpn` #498](https://github.com/OpenVPN/openvpn/issues/498#issuecomment-1939194149)
-
-## Q: Options error: No client-side authentication method is specified.
-
-A: Although openvpn-auth-oauth2 theoretically doesn't require client-side authentication, the OpenVPN client expects it.
-
-**Upstream Issue:** [`OpenVPN/openvpn` #501](https://github.com/OpenVPN/openvpn/issues/501) (Please react with :+1: if you're affected.)
-
-**Potential Workarounds:**
-
-1. **Configure Client Certificates**
-    Implement client certificates to enable client-side authentication.
-
-2. **Use Inline auth-user-pass**
-    OpenVPN accepts `auth-user-pass` for client-side authentication. You can define the username and password inline to prevent the OpenVPN GUI from requesting a password.
-
-    ```
-    <auth-user-pass>
-    username
-    password
-    </auth-user-pass>
-    ```
-
-    Note: The username/password can be any dummy value as they won't be validated by openvpn-auth-oauth2 or OpenVPN itself.
 
 ## Q: `Provider did not return a id_token. Validation of user data is not possible.` is logged, but my provider is returning an id_token.
 

docs/Configuration.md

@@ -0,0 +1,130 @@
+# OpenVPN Username
+
+## Overview
+
+This document covers various aspects of username handling in openvpn-auth-oauth2, including how to pass usernames from OAuth2 providers to OpenVPN, client-side authentication requirements, and configuration options.
+
+## Client-Side Requirements
+
+### Mandatory `auth-user-pass` Configuration
+
+To use username functionality with openvpn-auth-oauth2, the OpenVPN client **must** have `auth-user-pass` configured. This is a mandatory requirement for the authentication flow to work properly.
+
+**Important:** Although openvpn-auth-oauth2 theoretically doesn't require client-side authentication, the OpenVPN client expects it.
+
+You have two options:
+
+1. **Interactive Mode**: Use `auth-user-pass` without credentials, prompting the user for input:
+   ```
+   auth-user-pass
+   ```
+
+2. **Inline Mode**: Define dummy credentials inline to prevent prompting (recommended for SSO-only authentication):
+   ```
+   <auth-user-pass>
+   username
+   password
+   </auth-user-pass>
+   ```
+
+   Note: The username/password can be any dummy value as they won't be validated by openvpn-auth-oauth2 or OpenVPN itself during the OAuth2 flow.
+
+**Upstream Issue:** [`OpenVPN/openvpn` #501](https://github.com/OpenVPN/openvpn/issues/501) (Please react with :+1: if you're affected.)
+
+### Error: "No client-side authentication method is specified"
+
+If you encounter this error, ensure that `auth-user-pass` is configured in your client configuration as described above.
+
+## Using `username-as-common-name` on OpenVPN Server
+
+When setting up `username-as-common-name` on the OpenVPN server, you **must** also configure `openvpn.common-name.environment-variable-name` to `username`:
+
+```bash
+--openvpn.common-name.environment-variable-name=username
+```
+
+Or via environment variable:
+
+```dotenv
+CONFIG_OPENVPN_COMMON__NAME_ENVIRONMENT__VARIABLE__NAME=username
+```
+
+### Why This Configuration Is Required
+
+This configuration is essential because `username-as-common-name` functions **post-authentication**. By aligning the environment variable name with `username`, you ensure smooth operation.
+
+**Important Note:** During authentication, it's expected that the common-name is not the value of the username. This may be misleading because after authentication, the common name has the correct value in OpenVPN logs.
+
+**Upstream Issue:** [`OpenVPN/openvpn` #498](https://github.com/OpenVPN/openvpn/issues/498#issuecomment-1939194149)
+
+## Passing Usernames from OAuth2 Provider to OpenVPN
+
+### Default Behavior
+
+By default, openvpn-auth-oauth2 does not pass the username from the OAuth2 provider to OpenVPN. This limitation is due to OpenVPN's authentication interface design, which does not provide a native mechanism to set the username post-authentication.
+
+**Limitation:** The IP persistence file or statistics in OpenVPN may contain empty usernames when using the default configuration.
+
+**Upstream Issue:** For native OpenVPN support, please up-vote the feature request on GitHub: [`OpenVPN/openvpn` #299](https://github.com/OpenVPN/openvpn/issues/299)
+
+### Using `openvpn.override-username` (Recommended)
+
+**Requires OpenVPN Server 2.7+**
+
+The `openvpn.override-username` configuration option enables passing the username from OAuth2 token claims to OpenVPN using the `override-username` command. This allows real usernames to appear in OpenVPN statistics and logs.
+
+#### Configuration
+
+Enable this feature using:
+
+```bash
+--openvpn.override-username
+```
+
+Or via environment variable:
+
+```bash
+CONFIG_OPENVPN_OVERRIDE__USERNAME=true
+```
+
+#### Username Source
+
+The username is extracted from the OAuth2 ID token using one of these configurations (in order of precedence):
+
+1. **`oauth2.openvpn-username-claim`** - Extract username from a specific token claim (default: `preferred_username`)
+2. **`oauth2.openvpn-username-cel`** - Use a CEL expression to extract or transform the username from token claims
+
+Example configurations:
+
+```bash
+# Use a specific claim
+--oauth2.openvpn-username-claim=email
+
+# Use CEL expression for complex transformations
+--oauth2.openvpn-username-cel='oauth2TokenClaims.email.split("@")[0]'
+```
+
+For more details on CEL expressions, see the [Client token values](Client%20token%20validation.md#cel-language-features) documentation.
+
+#### Important Limitations
+
+⚠️ **OpenVPN Client-Config-Dir Compatibility:**
+
+When `openvpn.override-username` is enabled, OpenVPN's native `client-config-dir` functionality **will not work** because the username is set **after** client configs are read.
+
+**Workaround:** Use openvpn-auth-oauth2's built-in [Client specific configuration](Client%20specific%20configuration.md) feature instead, which:
+- Works seamlessly with `openvpn.override-username`
+- Uses token claims to lookup configuration files
+- Provides additional features like profile selection UI
+
+For more details, see the OpenVPN man page regarding `override-username` limitations.
+
+### Alternative: `openvpn.auth-token-user`
+
+If you're using OpenVPN Server < 2.7 or cannot use `override-username`, the `openvpn.auth-token-user` option provides limited username support:
+
+```bash
+--openvpn.auth-token-user
+```
+
+This option uses the `auth-token-user` push command to send a base64-encoded username, but only when the client username is empty. This has more limitations compared to `override-username`.

docs/FAQ.md

@@ -12,6 +12,7 @@
 #### Working
 
 - OpenVPN 2.6.6 on Linux
+- OpenVPN 2.7.0 on Linux
 
 #### Non-Working
 
@@ -35,3 +36,7 @@
 
 - [network-manager-openvpn-gnome](https://gitlab.gnome.org/GNOME/NetworkManager-openvpn) -
   See https://gitlab.gnome.org/GNOME/NetworkManager-openvpn/-/issues/124
+
+## OpenVPN username handling
+
+See [OpenVPN Username](OpenVPN%20Username) for more information.

docs/OpenVPN Username.md

@@ -126,6 +126,7 @@ CONFIG_OAUTH2_PROVIDER=google
 CONFIG_OAUTH2_ISSUER=https://accounts.google.com
 CONFIG_OAUTH2_CLIENT_ID=162738495-xxxxx.apps.googleusercontent.com
 CONFIG_OAUTH2_CLIENT_SECRET=GOCSPX-xxxxxxxx
+CONFIG_OAUTH2_OPENVPN_USERNAME_CLAIM=email
 
 # The scopes openid profile email are required, but configured by default.
 # https://www.googleapis.com/auth/cloud-identity.groups.readonly is mandatory for group validation.
@@ -144,6 +145,7 @@ oauth2:
   client:
     id: "162738495-xxxxx.apps.googleusercontent.com"
     secret: "GOCSPX-xxxxxxxx"
+  openvpn-username-claim: "email"
   # The scopes openid profile email are required, but configured by default.
   # https://www.googleapis.com/auth/cloud-identity.groups.readonly is mandatory for group validation.
   # Enabled by default, if scopes aren't set in the config.
@@ -517,3 +519,15 @@ oauth2:
 </table>
 
 </details>
+
+## Okta
+
+Contributions for Okta are welcome. Please open an issue, or a pull request if you want to add documentation for Okta.
+
+## Ping Identity
+
+Contributions for Ping Identity are welcome. Please open an issue, or a pull request if you want to add documentation for Ping Identity.
+
+## OneLogin
+
+Contributions for OneLogin are welcome. Please open an issue, or a pull request if you want to add documentation for OneLogin.

docs/OpenVPN.md

@@ -2,9 +2,38 @@
 
 ## Potential Risks Caused by State Reuse
 
-There is a potential risk that an attacker could forge state parameters and hijack an OpenVPN session through phishing attacks. To do this, the attacker would need to know both the state encryption key and the OpenVPN session ID. While the encryption key is a static value, the session ID is a randomly generated incrementing number that changes with each new session.
+There is a potential risk that an attacker could forge state parameters and hijack an OpenVPN session through phishing attacks. To do this, the attacker would need to know both the state encryption key, and the OpenVPN session ID. While the encryption key is a static value, the session ID is a randomly generated incrementing number that changes with each new session.
 
 To mitigate this risk, we recommend the following:
 * **Hardening OpenVPN itself**, for example, by introducing `tls-auth`. This requires the attacker to obtain an additional TLS key.
 * **Enabling `--http.check.ipaddr`**, which verifies that the IP address of the VPN connection matches that of the HTTP connection.
 * **Forcing re-authentication at the SSO provider**, if supported, by setting `--oauth2.authorize-params=prompt=login`. This ensures users must log in again before proceeding.
+
+## Social Engineering Attacks via OIDC Login Links
+
+An attacker could initiate a VPN connection on their own device and then send the generated OIDC login link to an unsuspecting employee via phishing (e.g., email, instant messaging, or SMS). If the employee clicks the link and completes the authentication, the attacker’s VPN session would be authenticated using the employee’s credentials, granting unauthorized access to the network.
+
+### Attack Scenario
+
+1. The attacker initiates an OpenVPN connection from their device
+2. openvpn-auth-oauth2 generates an authentication URL for this connection attempt
+3. The attacker sends this URL to a target employee (via phishing email, SMS, etc.)
+4. The employee clicks the link and authenticates with their credentials
+5. The attackers VPN session is now authenticated as the employee, gaining access to the network.
+
+### Mitigations
+
+To protect against this type of social engineering attack, consider implementing the following measures:
+
+* **Enable IP address validation with `--http.check.ipaddr`**: This ensures that the IP address initiating the VPN connection matches the IP address completing the OIDC authentication flow. This is the most effective technical control, as it prevents the attack even if the employee clicks the link, since the authentication will be rejected due to the IP mismatch.
+  > [!NOTE]
+  > While `--http.check.ipaddr` provides strong technical protection against this attack vector, it may not be suitable for all environments (e.g., users behind NAT, mobile users with changing IPs, or organizations using forward proxies). In such cases, compensating controls like user education and enhanced monitoring become even more critical.
+
+
+* **Implement additional authentication context verification**: Consider using OIDC features that provide additional context:
+  * Use `--oauth2.authorize-params` to request additional claims that can be validated
+  * Require multifactor authentication (MFA) at the OIDC provider level
+
+* **Session binding improvements**:
+  * Use short authentication timeouts (`--openvpn.auth-pending-timeout`) to reduce the window of opportunity for attacker’s
+  * Consider implementing additional session binding mechanisms beyond IP addresses, if your environment supports it.