wiretastix

Configure Okta SSO Integration for WireGuard

How to integrate Okta SSO with Wiretastix for OIDC-based WireGuard authentication.

Partially verified. The core mechanism – the Org Authorization Server’s app-level Group Claims setting (Step 5) plus the separate Custom Authorization Server Claims-tab path (Step 8) – was checked against Okta’s own developer documentation and is accurate. The exact wording of some UI details (e.g. the “Value: Name vs. Okta Group ID” dropdown in Step 5) hasn’t been independently confirmed. This page’s source is on GitHub at wiretastix/wiretastix-website – if you spot something wrong (or outdated, since Okta’s admin console does change), a pull request is welcome.

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

Prerequisites

Before you begin, ensure you have:

  • An Okta account (Developer, Workforce Identity, or Customer Identity)
  • Administrative access to the Okta Admin Console
  • Your Wiretastix instance URL (e.g., https://vpn.example.com)
  • Administrative access to your Wiretastix configuration

Why Okta Works Well with Wiretastix

Okta is particularly well-suited for Wiretastix because:

  • Enterprise-grade: Industry-leading identity and access management
  • Full OIDC compliance: Complete OpenID Connect 1.0 support
  • Group management: Rich group hierarchy and dynamic group support
  • Universal Directory: Centralized user and group management
  • MFA support: Built-in multi-factor authentication
  • Integration ecosystem: Thousands of pre-built integrations
  • Excellent documentation: Comprehensive and well-maintained

Step 1: Access the Okta Admin Console

  1. Sign in to your Okta organization at https://your-domain.okta.com or https://your-domain.oktapreview.com
  2. Click Admin in the top-right corner to access the Admin Console
  3. Note your Okta domain (e.g., dev-12345.okta.com or company.okta.com) - you’ll need this later

Step 2: Create an Application Integration

  1. In the Admin Console, navigate to Applications → Applications in the left sidebar
  2. Click Create App Integration
  3. Select the sign-in method:
    • Choose OIDC - OpenID Connect
  4. Select the application type:
    • Choose Web Application
  5. Click Next

Step 3: Configure Application Settings

General Settings

  1. Fill in the application details:
    • App integration name: Wiretastix VPN
    • Logo: (Optional) Upload your organization’s logo

Sign-in redirect URIs

  1. Add the redirect URI:
    • Click + Add URI
    • Enter: https://vpn.example.com/callback
    • Replace vpn.example.com with your actual Wiretastix domain

Sign-out redirect URIs

  1. (Optional) Add sign-out redirect:
    • Click + Add URI
    • Enter: https://vpn.example.com

Assignments

  1. Select Controlled access:

    • Choose who can access this app:
      • Allow everyone in your organization to access: All Okta users (use constraints in Wiretastix to limit)
      • Limit access to selected groups: Select specific groups (recommended)
      • Skip group assignment for now: Assign later

  2. Click Save

Step 4: Retrieve Client Credentials

After creating the application, you’ll see the application settings:

  1. Client ID: Copy this value - you’ll need it for Wiretastix configuration
  2. Client secret: Copy this value immediately - you may need to reveal it by clicking Show
  3. Note the Okta domain from your browser URL (e.g., dev-12345.okta.com)

Step 5: Configure Token Claims (Groups)

Okta needs to include group information in tokens:

Add Group Claims to Tokens

  1. In your application settings, scroll down to Group Claims
  2. Click Edit next to OpenID Connect ID Token
  3. Configure group claims:
    • Filter: Choose based on your needs:
      • Matches regex: .* (includes all groups)
      • Starts with: VPN- (only groups starting with VPN-)
      • Equals: (specify exact group names)
    • Value: Choose Name (easier to use) or Okta Group ID (more secure)
  4. Click Save

Recommendation: Use “Starts with” filter with a prefix like VPN- to only include relevant groups and avoid token size issues.

Step 6: Create Groups in Okta

To leverage group-based access control:

  1. Navigate to Directory → Groups in the Admin Console

  2. Click Add Group

  3. Fill in the group details:

    • Name: VPN-Users (use the prefix that matches your filter from Step 5)
    • Group Description: Users with VPN access

  4. Click Save

  5. Repeat for additional groups:

    • VPN-Admins
    • VPN-Developers
    • VPN-Contractors

Assign Users to Groups

  1. Click on a group
  2. Go to the People tab
  3. Click Assign people
  4. Search for and select users
  5. Click Save

Step 7: Assign Groups to Application

To control which groups can access Wiretastix:

  1. Navigate to Applications → Applications
  2. Click on your Wiretastix VPN application
  3. Go to the Assignments tab
  4. Click Assign → Assign to Groups
  5. Select the groups that should have access (e.g., VPN-Users, VPN-Admins)
  6. Click Assign for each group
  7. Click Done

Note: Users must be assigned to the application (directly or via group) to authenticate.

Step 8: Configure Authorization Server (Optional)

For more control over tokens, configure the default authorization server:

  1. Navigate to Security → API in the Admin Console
  2. Select your authorization server (typically default)
  3. Go to the Claims tab
  4. Verify that group claims are configured:
    • Name: groups
    • Include in token type: ID Token, Always
    • Value type: Groups
    • Filter: Matches your configuration from Step 5

Step 9: Retrieve Okta Configuration Details

You’ll need the following information:

  1. Okta Domain: Your organization’s domain (e.g., dev-12345.okta.com)

  2. Client ID: From Step 4

  3. Client Secret: From Step 4

  4. Issuer URL: Constructed as:

    https://{okta-domain}/oauth2/default/.well-known/openid-configuration

    Or if using a custom authorization server:

    https://{okta-domain}/oauth2/{authServerId}/.well-known/openid-configuration

    For example:

    https://dev-12345.okta.com/oauth2/default/.well-known/openid-configuration

Step 10: Configure Wiretastix

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

oidc:
    name: Okta
    client-id: YOUR_OKTA_CLIENT_ID
    client-secret: YOUR_OKTA_CLIENT_SECRET
    redirect-url: https://vpn.example.com/callback
    config-issuer: https://dev-12345.okta.com/oauth2/default/.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
        - groups
    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 4
  • client-secret: The Client Secret from Step 4
  • redirect-url: Must match exactly what you configured in Okta
  • config-issuer: Okta’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 (note the groups scope)
  • constraints: Access control rules

Understanding Okta Scopes

Okta requires the groups scope to include group claims in tokens:

scopes:
    - openid
    - email
    - profile
    - offline_access  # For refresh tokens
    - groups         # For group claims (required!)

Without the groups scope, group information won’t be included in tokens.

Understanding Constraints with Okta

Okta provides excellent group support:

Control access based on Okta group membership:

constraints:
    groups:
        - VPN-Users
        - VPN-Developers

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

Important: The group names in constraints must match:

  • The actual group names in Okta (case-sensitive)
  • What’s returned in the groups claim (based on your Value setting in Step 5)

Email Constraints

You can also restrict by email:

constraints:
    email:
        - alice@example.com
        - bob@example.com
    groups:
        - VPN-Users

With both constraints, users must satisfy all constraint types.

Generate a secure random string:

openssl rand -base64 32

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

Step 12: Restart Wiretastix

Restart the Wiretastix daemon:

sudo systemctl restart wiretastix

Or if running manually:

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

Step 13: Test the Integration

  1. Open your web browser and navigate to https://vpn.example.com
  2. You should be redirected to Okta’s sign-in page
  3. Sign in with an Okta account that is:
    • Assigned to the Wiretastix application (directly or via group)
    • A member of one of the allowed groups
  4. If this is the first time, you may see a consent screen - click Allow
  5. You should be redirected back to Wiretastix and logged in

If successful, you’ll see the Wiretastix dashboard.

Troubleshooting

Error: “redirect_uri_mismatch” or Invalid Redirect URI

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

Solution:

  1. Go to Okta Admin Console → Applications → Your app
  2. Check Sign-in redirect URIs
  3. Ensure it exactly matches redirect-url in wiretastix.yaml
  4. Protocol (https), domain, and path (/callback) must match exactly
  5. Click Save

Error: “invalid_client” or Client Authentication Failed

Cause: Incorrect client ID or client secret.

Solutions:

  1. Verify the Client ID in Okta matches client-id in Wiretastix
  2. Regenerate the client secret in Okta if needed:
    • Go to application settings → Client Credentials
    • Click Edit → Generate new secret
  3. Update Wiretastix configuration with new secret

Error: “User is not assigned to the client application”

Cause: User not assigned to the Wiretastix application in Okta.

Solutions:

  1. Go to Applications → Wiretastix VPN → Assignments
  2. Assign the user directly or via a group
  3. Ensure the user’s group is assigned to the application

Groups Not Appearing in Token

Cause: Group claims not configured or groups scope missing.

Solutions:

  1. Verify groups scope is in Wiretastix configuration
  2. Check group claims configuration in Okta (Step 5)
  3. Ensure group filter matches your group names
  4. Verify users are actually members of groups
  5. Enable verbose: true in Wiretastix and check received claims

“User Not Authorized” Despite Being in Group

Cause: Group name mismatch or group not in token.

Solutions:

  1. Verify group names in Wiretastix constraints match Okta group names exactly (case-sensitive)
  2. Check if group filter in Okta includes the groups
  3. Review token contents (use Okta’s token preview or verbose logging)
  4. Ensure user is actually assigned to the application

Token Refresh Failures

Cause: Refresh token configuration issues.

Solutions:

  1. Ensure offline_access scope is in Wiretastix config
  2. Check token lifetime settings in Okta:
    • Security → API → Authorization server → Access Policies
  3. Verify refresh token rotation is configured appropriately

“Invalid Issuer” Error

Cause: Incorrect issuer URL or authorization server.

Solutions:

  1. Verify your Okta domain is correct
  2. Ensure format: https://{okta-domain}/oauth2/default/.well-known/openid-configuration
  3. If using custom authorization server, replace default with your server ID
  4. Check Okta is accessible from Wiretastix server

Enable Verbose Logging

In Wiretastix:

oidc:
    verbose: true

In Okta:

  1. Navigate to Reports → System Log in the Admin Console
  2. Filter by:
    • Event Type: User authentication
    • Target: Your application name
  3. Review authentication events for errors

Token Preview in Okta

To see what claims are in tokens:

  1. In Okta Admin Console, go to Applications → Your app
  2. Click Sign On tab
  3. Scroll to OpenID Connect ID Token
  4. Click Preview token
  5. Sign in as a test user
  6. Review token contents, especially the groups claim

Advanced Okta Configuration

Dynamic Groups

Automatically manage group membership:

  1. Navigate to Directory → Groups
  2. Click Add Group
  3. Choose Dynamic
  4. Define rules based on user attributes (e.g., user.department == "Engineering")
  5. Users are automatically added/removed based on attribute changes

Wiretastix defers authentication policy entirely to the IdP – if you want MFA, Okta ThreatInsight anomaly detection, or a custom authorization server enforced before a user ever reaches Wiretastix, configure it on the Okta side (Security → Multifactor/Authentication Policies/ThreatInsight/API) as you would for any other app; none of it is Wiretastix-specific, and Wiretastix has no visibility into or control over it.

Okta and Wiretastix Group Synchronization

Wiretastix automatically synchronizes group memberships:

  1. On First Login: User’s groups are imported from Okta
  2. On Token Refresh: Groups are updated based on current Okta 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 Wiretastix
  2. Strong Secrets: Generate strong client secrets and cookie secrets
  3. Secret Rotation: Regularly rotate client secrets
  4. Token Expiration: Configure appropriate token lifetimes
  5. MFA: Require multi-factor authentication for VPN access
  6. Least Privilege: Only grant necessary group memberships
  7. Authentication Policies: Use Okta policies to enforce security requirements
  8. Audit Logs: Regularly review Okta system logs
  9. Monitor: Set up alerts for suspicious authentication attempts
  10. Rate Limiting: Configure rate limits in Okta to prevent brute force attacks

Next Steps

After successfully configuring Okta OIDC:

Additional Resources