wiretastix

Configure OIDC Identity Provider

How to set up OIDC/SSO authentication for Wiretastix with any OpenID Connect Identity Provider.

Integrating Wiretastix with an OpenID Connect (OIDC) Identity Provider (IdP) enables single sign-on (SSO), centralized user authentication, and dynamic access control based on OIDC claims and groups. This guide will walk you through the necessary configuration steps.

Prerequisites

Before you begin, ensure you have:

  • An operational OIDC Identity Provider (e.g., Keycloak, Auth0, Google Identity Platform).
  • A client application registered with your OIDC IdP, obtaining a Client ID and Client Secret.
  • A Redirect URI configured in your OIDC IdP that points to your Wiretastix instance (e.g., https://your-wiretastix-host/wiretastix/auth/callback).

1. Configure wiretastix.yaml for OIDC

Edit your wiretastix.yaml configuration file (default: /etc/wiretastix/wiretastix.yaml) and add or modify the oidc section with your IdP details:

# OIDC (OpenID Connect) configuration
oidc:
  name: "MyOIDCProvider" # A descriptive name for your IdP
  client-id: "YOUR_OIDC_CLIENT_ID" # Client ID from your OIDC IdP
  client-secret: "YOUR_OIDC_CLIENT_SECRET" # Client Secret from your OIDC IdP
  redirect-url: "https://your-wiretastix-host:8090/wiretastix/auth/callback" # Must match the Redirect URI in your IdP
  config-issuer: "https://your-oidc-idp-domain/realms/your-realm" # The OIDC issuer URL
  verbose: false # Set to true for detailed OIDC logging
  cookie-secret: "A_LONG_RANDOM_STRING_FOR_COOKIES" # Generate a strong, random string
  force-approval: false # Set to true to force user consent for scopes
  refresh-min-interval-sec: 300 # Minimum interval to refresh OIDC tokens (in seconds)
  scopes:
    - "openid"
    - "profile"
    - "email"
    - "groups" # Request group claims if your IdP supports it
  constraints: # Optional: Define constraints based on OIDC claims for user authorization
    groups:
      - "wiretastix-users"
      - "vpn-access"

Key parameters to configure:

  • name: A friendly name for your OIDC provider.
  • client-id: The client ID issued by your OIDC IdP.
  • client-secret: The client secret issued by your OIDC IdP.
  • redirect-url: The full URL where your OIDC IdP will redirect users after authentication. This must match the URI registered with your IdP.
  • config-issuer: The base URL of your OIDC IdP’s issuer endpoint. Wiretastix will use this to discover the IdP’s configuration.
  • cookie-secret: A strong, randomly generated string used to encrypt session cookies. Generate a unique one for your deployment.
  • scopes: A list of OIDC scopes to request. openid, profile, and email are common. Include groups if you intend to use OIDC group claims for access control.
  • constraints: (Optional) This section allows you to define rules based on OIDC claims. For example, groups: ["wiretastix-users"] means only users belonging to the wiretastix-users group in your OIDC IdP will be authorized to use Wiretastix.

2. Restart the Wiretastix Daemon

After modifying wiretastix.yaml, restart the Wiretastix daemon to apply the new OIDC configuration:

sudo systemctl restart wiretastix # If using systemd
# Or if running directly:
sudo pkill wiretastix-daemon
sudo wiretastix-daemon -c /etc/wiretastix/wiretastix.yaml

3. Access the Web Interface

Once the daemon has restarted with OIDC configured, navigate to the Wiretastix web interface in your browser (e.g., https://your-wiretastix-host:8090/wiretastix/). You should now be redirected to your OIDC Identity Provider’s login page for authentication.

Upon successful login, you will be redirected back to the Wiretastix web interface, where you can self-provision WireGuard tunnels and manage your VPN access.

Next Steps

With OIDC configured, users can now self-provision their peers. You might want to further refine access control by defining Network Rules based on OIDC groups.