Configure Authentik SSO for WireGuard

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

This guide will walk you through configuring Authentik as your OpenID Connect (OIDC) Identity Provider for Wiretastix, enabling single sign-on (SSO). Authentik is an excellent choice for Wiretastix integration as it provides comprehensive group management, flexible user policies, and full OIDC compliance.

Prerequisites

Before you begin, ensure you have:

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

Why Authentik Works Well with Wiretastix

Authentik is particularly well-suited for Wiretastix because:

Full OIDC support: Native OpenID Connect implementation
Group management: Robust group claims support
User policies: Fine-grained access control
Self-hosted: Complete control over your identity infrastructure
Modern UI: Easy to manage users and groups
Active development: Regular updates and good documentation

Step 1: Create an OAuth2/OIDC Provider in Authentik

Log into your Authentik admin interface (typically at https://authentik.example.com/if/admin/)
Navigate to Applications → Providers in the left sidebar
Click Create button (or the “+” icon)
Select OAuth2/OpenID Provider
Fill in the provider configuration:

Provider Configuration

Basic Settings:

Name: Wiretastix VPN Provider
Authorization flow: Select your preferred authentication flow (e.g., default-authentication-flow)
Protocol settings: Leave as default (OAuth2/OIDC)

OAuth2/OIDC Settings:

Client type: Confidential
Client ID: Leave auto-generated or set to wiretastix (note this value)
Client Secret: Will be auto-generated - you’ll copy this later
Redirect URIs/Origins (RegEx): Add your Wiretastix callback URL:
```
https://vpn.example.com/callback
```
Replace vpn.example.com with your actual Wiretastix domain

Scopes:

Ensure the following scopes are included (add if not present):

openid
email
profile
offline_access (for refresh tokens)

Advanced settings:

Subject mode: Based on the User's UUID (recommended) or Based on the User's username
Include claims in id_token: Enabled (recommended)
Token validity: Set according to your security requirements
- Access token validity: minutes=30 (default)
- Refresh token validity: days=30 (default)

Click Finish to create the provider
After creation, click on the provider name to view details
Copy the Client ID and Client Secret - you’ll need these for Wiretastix configuration

Step 2: Create Groups in Authentik (Optional but Recommended)

To leverage group-based access control in Wiretastix, create groups in Authentik:

Navigate to Directory → Groups in the left sidebar
Click Create to add a new group
Fill in the group details:
- Name: vpn-users (or your preferred group name)
- Parent: (Optional) Select a parent group if using hierarchical structure
Click Create
Repeat this process to create additional groups as needed:
- vpn-developers
- vpn-admins
- vpn-contractors
- etc.
Assign users to groups:
- Navigate to Directory → Users
- Click on a user
- Go to the Groups tab
- Click Add to existing group and select the appropriate groups

Step 3: Configure Property Mappings (Ensure Groups are Included)

Authentik needs to be configured to include group information in OIDC tokens:

Navigate to Customization → Property Mappings in the left sidebar
Look for a mapping named authentik default OAuth Mapping: OpenID 'groups' (or similar)
If it doesn’t exist, create one:
- Click Create
- Select Scope Mapping
- Name: OpenID Groups
- Scope name: groups
- Expression:
```
return {
    "groups": [group.name for group in request.user.ak_groups.all()]
}
```
- Click Create
Ensure this mapping is attached to your provider:
- Go back to Applications → Providers
- Click on your Wiretastix provider
- Scroll to Property Mappings
- Ensure the groups mapping is selected
- Click Update if you made changes

Step 4: Create an Application in Authentik

Now link your provider to an application:

Navigate to Applications → Applications
Click Create
Fill in the application details:
- Name: Wiretastix VPN
- Slug: wiretastix-vpn (URL-friendly identifier)
- Provider: Select the provider you created in Step 1
- Launch URL: https://vpn.example.com (your Wiretastix URL)
- Icon: (Optional) Upload an icon for the application
Click Create

Step 5: Configure Authorization (Optional)

To restrict which users can access Wiretastix through Authentik:

Navigate to Applications → Applications
Click on your Wiretastix VPN application
Go to the Policy / Group / User Bindings tab
Click Create Binding to add access policies:

Option A: Group-Based Access

Bind specific groups to the application:

Policy / Group / User: Select a group (e.g., vpn-users)
Order: 0 (lower numbers = higher priority)
Enabled: Yes
Click Create

Option B: Policy-Based Access

Create custom policies for more complex access control:

Navigate to Policies → Policies
Create expression policies based on user attributes
Bind these policies to the application

Step 6: Retrieve Configuration Details

You’ll need the following information from Authentik:

Client ID: Found in your provider’s settings (e.g., wiretastix or auto-generated UUID)
Client Secret: Found in your provider’s settings

Issuer URL: Your Authentik instance URL with the realm path:

https://authentik.example.com/application/o/wiretastix-vpn/.well-known/openid-configuration

Or for the discovery URL format:

https://authentik.example.com/application/o/wiretastix-vpn/

You can find the exact issuer URL by:

Going to your provider settings
Looking for the OpenID Configuration Issuer field
Or constructing it as: https://<authentik-domain>/application/o/<provider-slug>/

Step 7: Configure Wiretastix

Edit your /etc/wiretastix/wiretastix.yaml file to configure Authentik as the OIDC provider:

oidc:
    name: Authentik
    client-id: YOUR_AUTHENTIK_CLIENT_ID
    client-secret: YOUR_AUTHENTIK_CLIENT_SECRET
    redirect-url: https://vpn.example.com/callback
    config-issuer: https://authentik.example.com/application/o/wiretastix-vpn/.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 your Authentik provider
client-secret: The Client Secret from your Authentik provider
redirect-url: Must match exactly what you configured in Authentik
config-issuer: Authentik’s OpenID Connect discovery URL
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
constraints: Access control rules

Understanding Constraints with Authentik

Authentik provides excellent group support, making group-based constraints ideal:

Group Constraints (Recommended)

Control access based on Authentik group membership:

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

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

Email Constraints

You can also restrict by email address:

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

With both constraints, users must satisfy all constraint types (email AND group membership).

No Constraints (Allow All Authenticated Users)

To allow any user who can authenticate through Authentik:

constraints:
    groups: []
    email: []

Note: This requires that users can access the Wiretastix application in Authentik (via application bindings).

Generate a secure random string for the cookie-secret parameter:

openssl rand -base64 32

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

Step 9: Restart Wiretastix

After updating the configuration, restart the Wiretastix daemon:

sudo systemctl restart wiretastix

Or if running manually:

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

Step 10: Test the Integration

Open your web browser and navigate to your Wiretastix URL (e.g., https://vpn.example.com)
You should be redirected to Authentik’s sign-in page
Sign in with an Authentik user account that:
- Has access to the Wiretastix application (via policy bindings)
- Is a member of one of the groups in your constraints
If this is the first time, you may see a consent screen - click Allow or Continue
You should be redirected back to Wiretastix and logged in

If successful, you’ll see the Wiretastix dashboard where you can create VPN devices.

Troubleshooting

Error: “redirect_uri_mismatch”

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

Solution:

Go to Authentik: Applications → Providers → Your Wiretastix provider
Check Redirect URIs/Origins
Ensure it exactly matches redirect-url in wiretastix.yaml
No trailing slashes, correct protocol (https)
Click Update and restart Wiretastix

Error: “access_denied” or “Application not assigned”

Cause: User doesn’t have access to the Wiretastix application in Authentik.

Solutions:

Check application policy bindings in Authentik
Ensure the user is in an allowed group
Verify group assignments in Directory → Users → (user) → Groups
Check that groups match the constraints in wiretastix.yaml

Groups Not Appearing in Wiretastix

Cause: Group claims not included in OIDC tokens.

Solutions:

Verify property mapping exists for groups (Step 3)
Ensure the mapping is attached to your provider
Check that groups scope is included in provider settings
Enable verbose: true in Wiretastix and check logs for received claims

Token Refresh Failures

Cause: Refresh token configuration issues.

Solutions:

Ensure offline_access scope is in Wiretastix config
Check refresh token validity in Authentik provider settings
Verify token expiration settings are reasonable
Check Authentik logs for token refresh errors

“Invalid Issuer” Error

Cause: Incorrect config-issuer URL in Wiretastix configuration.

Solutions:

In Authentik, go to your provider settings
Copy the exact OpenID Configuration Issuer URL
Ensure it ends with /.well-known/openid-configuration
Common format: https://authentik.domain/application/o/provider-slug/.well-known/openid-configuration

Enable Verbose Logging

For troubleshooting, enable verbose OIDC logging in Wiretastix:

oidc:
    verbose: true

Also enable debug logging in Authentik:

Navigate to System → Settings
Set log level to Debug
Check logs in System → Logs

Restart both Wiretastix and check logs:

# Wiretastix logs
sudo journalctl -u wiretastix -f

# Authentik logs (if running with Docker)
docker-compose logs -f authentik-server

Advanced Authentik Configuration

Custom Claims for Wiretastix Groups

You can customize how groups are passed to Wiretastix:

Navigate to Customization → Property Mappings

Create a new Scope Mapping:

Name: Wiretastix Custom Groups
Scope name: groups

Expression:

# Pass only groups that start with 'vpn-'
return {
    "groups": [
        group.name for group in request.user.ak_groups.all()
        if group.name.startswith('vpn-')
    ]
}

Attach this mapping to your Wiretastix provider

Multi-Factor Authentication (MFA)

Enhance security by requiring MFA:

Navigate to Flows & Stages → Flows
Edit your authentication flow
Add MFA stages (e.g., TOTP, WebAuthn)
Assign the flow to your Wiretastix provider

User Self-Service

Enable users to manage their own accounts:

Ensure your Authentik user interface is accessible
Users can manage their profile, MFA devices, and group memberships (if permitted)
This complements Wiretastix’s self-service VPN provisioning

Authentik and Wiretastix Group Synchronization

Wiretastix automatically synchronizes group memberships from Authentik:

On First Login: User’s groups are imported from Authentik
On Token Refresh: Groups are updated based on current Authentik membership
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. Authentik 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.

This provides dynamic access control based on your identity management in Authentik.

Security Best Practices

Use HTTPS: Always use HTTPS for both Authentik and Wiretastix
Strong Secrets: Generate strong, unique client secrets and cookie secrets
Token Expiration: Set appropriate token validity periods
MFA: Require multi-factor authentication for VPN access
Audit Logs: Regularly review logs in both Authentik and Wiretastix
Least Privilege: Only grant necessary group memberships
Regular Updates: Keep both Authentik and Wiretastix updated
Backup: Regularly backup your Authentik database

Production Deployment Considerations

High Availability

For production deployments:

Run Authentik in a redundant configuration
Use a robust database (PostgreSQL in HA mode)
Configure session persistence
Use a load balancer if needed

Monitoring

Monitor both systems:

Authentik health endpoints
Wiretastix metrics (Prometheus)
Authentication success/failure rates
Token refresh patterns

Disaster Recovery

Plan for failures:

Backup Authentik database regularly
Document recovery procedures
Test authentication failover scenarios
Have offline access methods for emergencies

Next Steps

After successfully configuring Authentik 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 default behaviors

Configure Authentik SSO for WireGuard

Prerequisites

Why Authentik Works Well with Wiretastix

Step 1: Create an OAuth2/OIDC Provider in Authentik

Provider Configuration

Step 2: Create Groups in Authentik (Optional but Recommended)

Step 3: Configure Property Mappings (Ensure Groups are Included)

Step 4: Create an Application in Authentik

Step 5: Configure Authorization (Optional)

Option A: Group-Based Access

Option B: Policy-Based Access

Step 6: Retrieve Configuration Details

Step 7: Configure Wiretastix

Configuration Parameters Explained

Understanding Constraints with Authentik

Group Constraints (Recommended)

Email Constraints

No Constraints (Allow All Authenticated Users)

Step 8: Generate a Cookie Secret

Step 9: Restart Wiretastix

Step 10: Test the Integration

Troubleshooting

Error: “redirect_uri_mismatch”

Error: “access_denied” or “Application not assigned”

Groups Not Appearing in Wiretastix

Token Refresh Failures

“Invalid Issuer” Error

Enable Verbose Logging

Advanced Authentik Configuration

Custom Claims for Wiretastix Groups

Multi-Factor Authentication (MFA)

User Self-Service

Authentik and Wiretastix Group Synchronization

Security Best Practices

Production Deployment Considerations

High Availability

Monitoring

Disaster Recovery

Next Steps

Additional Resources