Problem Statement

Summary

Add native support for array token-claims (e.g. groups) in openvpn.client-config.token-claim and optionally provide a UI option that allows users to choose between multiple matching client-specific configurations when they belong to multiple groups.

What problem does this feature solve?

Identity providers such as Keycloak, Azure AD, Okta, Auth0, etc. commonly deliver group membership as an array, for example:

"groups": ["vpn-users", "finance", "devops"]

The current implementation of openvpn.client-config.token-claim only supports string claims.
This prevents direct usage of group membership for selecting client-specific configurations.

Administrators must flatten the array into a single string using custom token mappers or scripts on the IdP side. This is inconvenient and limits flexibility, especially in multi-group environments.

Additionally, users belonging to multiple groups may have multiple valid .conf files. Currently, there is no way for the user to choose which configuration they want to use for a particular VPN session.

Proposed Solution

1. Add native support for array token-claims

If the configured claim contains an array:

• Iterate through array values
• For each element, check if .conf exists in the client-config directory
• Apply the first matching config
• If none match, fall back to:
  • Common Name, or
  • A default profile (if configured)

This provides clean, natural group-based authorization without requiring IdP-side hacks.

2. (Optional) If multiple configs match, allow the user to choose via the web UI

When a user belongs to multiple groups which all match existing configuration files, display a simple selection page in the login flow:

You belong to multiple VPN roles.
Select your VPN profile for this session:

[ vpn-users ]
[ vpn-admin ]

Flow:

• User authenticates
• Token is decoded
• Multiple matching configs found
• UI page allows selection
• Selected value is stored (session or temporary claim)
• Client-specific config is applied normally

Optional configuration flag:

openvpn:
  client-config:
    select-when-multiple: true

Additional information

This feature significantly improves integration with enterprise IAM systems like Keycloak, making group-based VPN authorization straightforward and user-friendly.

It would eliminate the need for administrators to maintain custom mappers and allow greater flexibility for users who require different VPN profiles depending on their tasks.

Acceptance Criteria

• token-claim accepts arrays in addition to strings.
• The application iterates array items and applies the first matching .conf.
• Optional: UI selection is displayed when multiple configs match.
• The selected config is used for the session without requiring IdP-side token rewriting.
• Backwards compatible with string-only behavior.
• No breaking changes for existing deployments.

Preflight Checklist

• I could not find a solution in the documentation,
  the FAQ, the existing issues or discussions.