Configure Keycloak OIDC SSO for WireGuard

How to configure Keycloak as your OIDC/SSO identity provider for Wiretastix WireGuard VPN access.

This guide will walk you through configuring Keycloak as your OpenID Connect (OIDC) Identity Provider for Wiretastix, enabling single sign-on (SSO). Keycloak is an excellent choice for enterprise deployments, offering robust identity management with comprehensive group and role support.

Prerequisites

Before you begin, ensure you have:

• A running Keycloak instance (version 18.0 or newer recommended)
• Administrative access to the Keycloak admin console
• Your Wiretastix instance URL (e.g., https://vpn.example.com)
• Administrative access to your Wiretastix configuration

Why Keycloak Works Well with Wiretastix

Keycloak is particularly well-suited for Wiretastix because:

• Enterprise-grade: Production-ready identity and access management
• Full OIDC compliance: Complete OpenID Connect 1.0 support
• Group management: Rich group and role hierarchy
• Federation: Can integrate with LDAP, Active Directory, and other IdPs
• Mature ecosystem: Widely used, well-documented
• Self-hosted or cloud: Flexible deployment options

Step 1: Select or Create a Realm

Keycloak organizes users into realms. You can use an existing realm or create a new one:

Using an Existing Realm

1. Log into your Keycloak admin console (typically at https://keycloak.example.com/admin/)
2. Select your desired realm from the dropdown in the top-left corner
3. Note the realm name - you’ll need this for the issuer URL

Creating a New Realm

1. Log into your Keycloak admin console
2. Hover over the realm dropdown in the top-left corner
3. Click Create Realm
4. Enter a Realm name: wiretastix (or your preferred name)
5. Enabled: On
6. Click Create

Step 2: Create a Client for Wiretastix

1. In your selected realm, navigate to Clients in the left sidebar
2. Click Create client (or Create button)
3. Fill in the General Settings:
   • Client type: OpenID Connect
   • Client ID: wiretastix (note this value)
   • Name: Wiretastix VPN (optional, friendly name)
   • Description: VPN access via WireGuard (optional)
4. Click Next

Capability Config

5. Configure Capability config:
   • Client authentication: On (for confidential client)
   • Authorization: Off (not needed)
   • Authentication flow: Enable at least:
     • Standard flow (authorization code flow)
     • Direct access grants (optional, for service accounts)
6. Click Next

Login Settings

7. Configure Login settings:
   • Root URL: https://vpn.example.com
   • Home URL: https://vpn.example.com
   • Valid redirect URIs: https://vpn.example.com/callback
   • Valid post logout redirect URIs: https://vpn.example.com (optional)
   • Web origins: https://vpn.example.com (for CORS)
8. Click Save

Step 3: Retrieve Client Credentials

1. After creating the client, go to the Credentials tab
2. Copy the Client secret - you’ll need this for Wiretastix configuration
3. Note your Client ID from Step 2

Step 4: Configure Client Scopes (Ensure Groups are Included)

Keycloak needs to include group information in tokens:

Add Groups to Token Claims

1. Still in your client settings, go to the Client scopes tab
2. Click on the dedicated scope (e.g., wiretastix-dedicated)
3. Click Add mapper → By configuration
4. Select Group Membership
5. Configure the mapper:
   • Name: groups
   • Token Claim Name: groups
   • Full group path: Off (use simple group names) or On (use full paths like /parent/child)
   • Add to ID token: On
   • Add to access token: On
   • Add to userinfo: On
6. Click Save

Verify Default Scopes

7. Go back to Client scopes tab of your client
8. Ensure the following default scopes are assigned:
   • email
   • profile
   • roles
   • Your dedicated scope with groups mapper

Step 5: Create Groups in Keycloak

To leverage group-based access control:

1. Navigate to Groups in the left sidebar
2. Click Create group
3. Enter Name: vpn-users (or your preferred group name)
4. Click Create
5. Repeat to create additional groups:
   • vpn-admins
   • vpn-developers
   • vpn-contractors

Assign Users to Groups

6. Navigate to Users in the left sidebar
7. Click on a user
8. Go to the Groups tab
9. Click Join Group
10. Select the appropriate group(s) and click Join

Step 6: Configure Group Hierarchy (Optional)

For complex organizational structures:

1. In Groups, click on a parent group
2. Click Create child group
3. Enter a name for the child group
4. Users in child groups will inherit parent group memberships if “Full group path” is enabled

Step 7: Retrieve Keycloak Configuration Details

You’ll need the following information:

1. Realm name: The realm you created/selected (e.g., wiretastix)
2. Client ID: wiretastix (from Step 2)
3. Client Secret: From Step 3
4. Issuer URL: Constructed as:

   https://keycloak.example.com/realms/{realm-name}/.well-known/openid-configuration
   

   For example:

   https://keycloak.example.com/realms/wiretastix/.well-known/openid-configuration
   

Step 8: Configure Wiretastix

Edit your /etc/wiretastix/wiretastix.yaml file:

oidc:
    name: Keycloak
    client-id: wiretastix
    client-secret: YOUR_KEYCLOAK_CLIENT_SECRET
    redirect-url: https://vpn.example.com/callback
    config-issuer: https://keycloak.example.com/realms/wiretastix/.well-known/openid-configuration
    cookie-secret: GENERATE_A_RANDOM_STRING_HERE
    force-approval: false
    verbose: false
    refresh-min-interval-sec: 300
    scopes:
        - openid
        - email
        - profile
        - offline_access
    constraints:
        groups:
            - vpn-users
            - vpn-admins

Configuration Parameters Explained

• name: A friendly name for the provider (displayed in logs)
• client-id: The Client ID from Step 2 (e.g., wiretastix)
• client-secret: The Client Secret from Step 3
• redirect-url: Must match exactly what you configured in Keycloak
• config-issuer: Keycloak’s OpenID Connect discovery URL for your realm
• cookie-secret: A random string for session encryption (generate with: openssl rand -base64 32)
• force-approval: Set to true to force consent screen on every login
• verbose: Enable detailed OIDC logging for troubleshooting
• refresh-min-interval-sec: Minimum seconds between token refresh attempts
• scopes: Required OAuth scopes (Keycloak supports all standard scopes)
• constraints: Access control rules

Understanding Constraints with Keycloak

Keycloak provides excellent group support:

Group Constraints (Recommended)

Control access based on Keycloak group membership:

constraints:
    groups:
        - vpn-users
        - vpn-developers

Users must be a member of at least one of these groups.

Using Full Group Paths

If you enabled “Full group path” in the mapper:

constraints:
    groups:
        - /organization/vpn-users
        - /organization/vpn-admins

Email Constraints

You can also restrict by email:

constraints:
    email:
        - alice@example.com
        - bob@example.com
    groups:
        - vpn-users

Role-Based Constraints

Keycloak roles can also be mapped to groups if configured appropriately.

Step 9: Generate a Cookie Secret

Generate a secure random string:

openssl rand -base64 32

Copy the output and paste it into the cookie-secret field.

Step 10: Restart Wiretastix

Restart the Wiretastix daemon:

sudo systemctl restart wiretastix

Or if running manually:

sudo wiretastix-daemon -c /etc/wiretastix/wiretastix.yaml

Step 11: Test the Integration

1. Open your web browser and navigate to https://vpn.example.com
2. You should be redirected to Keycloak’s sign-in page
3. Sign in with a Keycloak user account that is a member of an allowed group
4. If this is the first time, you may see a consent screen - click Yes or Accept
5. You should be redirected back to Wiretastix and logged in

If successful, you’ll see the Wiretastix dashboard.

Troubleshooting

Error: “invalid_redirect_uri” or “redirect_uri_mismatch”

Cause: The redirect URL doesn’t match what’s configured in Keycloak.

Solution:

1. Go to Keycloak admin console → Clients → Your client
2. Check Valid redirect URIs
3. Ensure it exactly matches redirect-url in wiretastix.yaml
4. Use exact URLs with protocol (https) and no trailing slashes
5. Click Save and restart Wiretastix

Error: “Client not found” or “Invalid client credentials”

Cause: Incorrect client ID or client secret.

Solutions:

1. Verify the client ID in Keycloak matches client-id in Wiretastix config
2. Regenerate the client secret in Keycloak Credentials tab if needed
3. Ensure the client is Enabled in Keycloak

Groups Not Appearing in Wiretastix

Cause: Group mapper not configured or groups not in token.

Solutions:

1. Verify the group mapper exists (Step 4)
2. Check the mapper is in the client’s dedicated scope
3. Ensure users are actually members of groups
4. Enable verbose: true in Wiretastix and check logs for received claims
5. Test token contents at Keycloak’s token introspection endpoint

“User Not Authorized” or No Groups in Token

Cause: User not in any allowed groups or group claim format mismatch.

Solutions:

1. Verify user group membership in Keycloak
2. Check if “Full group path” setting matches your constraints
3. Review group mapper configuration
4. Test with a known group member

Token Refresh Failures

Cause: Refresh token configuration issues.

Solutions:

1. Ensure offline_access scope is in Wiretastix config and Keycloak client
2. Check token lifetimes in Keycloak: Realm settings → Tokens
3. Verify client has refresh token enabled
4. Check Keycloak logs for errors

“Invalid Issuer” Error

Cause: Incorrect issuer URL.

Solutions:

1. Verify the realm name in the URL
2. Ensure format: https://keycloak.domain/realms/{realm-name}/.well-known/openid-configuration
3. Check Keycloak is accessible from Wiretastix server
4. Verify SSL certificates if using HTTPS

Enable Verbose Logging

In Wiretastix:

oidc:
    verbose: true

In Keycloak:

1. Realm settings → Events
2. Enable Login events and Admin events
3. Check logs in Events tabs

Advanced Keycloak Configuration

If your users actually live in LDAP or Active Directory rather than being created directly in Keycloak, that’s a separate Keycloak concept from what this guide covers: User federation (not Identity providers, which is for brokering to external SAML/OIDC/social logins instead) syncs those directory users and groups into the realm, after which they authenticate through Keycloak exactly as described above and Wiretastix never talks to LDAP/AD directly. Configure it under User federation → Add provider → LDAP in the realm’s left sidebar.

Role-Based Access Control (RBAC)

Use Keycloak roles alongside groups:

1. Create Realm roles or Client roles
2. Assign roles to users or groups
3. Create a role mapper similar to the group mapper
4. Map roles to groups in Wiretastix configuration

Custom User Attributes

Pass additional user metadata to Wiretastix:

1. Define user attributes in User attributes
2. Create protocol mappers to include these in tokens
3. Use in Wiretastix for advanced configurations

Wiretastix defers authentication policy entirely to the IdP – MFA (Authentication → Flows) and session lifetimes (Realm settings → Sessions) are both configured on the Keycloak side as you would for any other client; neither is Wiretastix-specific, and Wiretastix has no visibility into or control over them.

Keycloak and Wiretastix Group Synchronization

Wiretastix automatically synchronizes group memberships:

1. On First Login: User’s groups are imported from Keycloak
2. On Token Refresh: Groups are updated based on current Keycloak membership
3. Group Changes Take Effect on the Next Refresh, Not Just at Login: If the reissued token includes a non-empty groups claim, Wiretastix re-syncs group membership and rebuilds firewall rules on the next successful token refresh – not only at the user’s next full login. If a user no longer matches any real Wiretastix group, they fall back to whatever default_group is configured to. If that fallback group has a restrictive policy (e.g. drop) or its own restrictive rules, the user’s actual network access is cut off on that same refresh cycle – even though their Wiretastix user account stays enabled the whole time. This is a different thing from auto_disable_on_auth_error, which disables the account itself and only fires when the refresh call fails outright (e.g. the IdP revoked the token), not from a group change alone. The one thing that genuinely is login-gated rather than refresh-gated is constraints (the allow/deny rule for who may authenticate at all): that’s only re-checked at the user’s next full login.

Security Best Practices

1. Use HTTPS: Always use HTTPS for both Keycloak and Wiretastix
2. Strong Secrets: Generate strong client secrets and cookie secrets
3. Token Expiration: Set appropriate token lifetimes (balance security and UX)
4. MFA: Require multi-factor authentication
5. Audit Logs: Enable and regularly review event logs
6. Least Privilege: Only grant necessary group memberships
7. Regular Updates: Keep Keycloak updated for security patches
8. Network Security: Restrict Keycloak admin console access
9. Backup: Regularly backup Keycloak database

Next Steps

After successfully configuring Keycloak OIDC:

• Manage Users - Manage users in Wiretastix
• Manage Groups - Configure group policies
• Configure Network Rules - Set up group-based firewall rules
• Managing Peers - Understand peer management
• Default Configuration Settings - Fine-tune defaults

Additional Resources

• Keycloak Documentation
• Keycloak OIDC Configuration
• Keycloak Token Claims
• Wiretastix OIDC Integration Concepts