wiretastix

Configure Google Workspace SSO for WireGuard

How to set up Google Workspace SSO for Wiretastix using OIDC, so your team signs in with their Google account.

This guide will walk you through configuring Google Workspace (or any Google account, via Google Cloud Platform) as your OpenID Connect (OIDC) Identity Provider for Wiretastix, enabling single sign-on (SSO) so users authenticate with their Google account.

Prerequisites

Before you begin, ensure you have:

  • A Google Cloud Platform account with administrative access
  • Access to the Google Cloud Console
  • Your Wiretastix instance URL (e.g., https://vpn.example.com)
  • Administrative access to your Wiretastix configuration

Step 1: Create a Google Cloud Project

If you don’t already have a Google Cloud project, create one:

  1. Navigate to the Google Cloud Console
  2. Click the project dropdown at the top of the page
  3. Click New Project
  4. Enter a project name (e.g., “Wiretastix VPN”)
  5. Click Create
  6. Select your newly created project from the project dropdown

Before creating OAuth credentials, you must configure the consent screen:

  1. In the Google Cloud Console, navigate to APIs & Services → OAuth consent screen

  2. Select the user type:

    • Internal: Only users in your Google Workspace organization can authenticate (recommended for enterprise)
    • External: Any Google account can authenticate (requires verification for production use)

  3. Click Create

  4. Fill in the required fields:

    • App name: Wiretastix VPN (or your preferred name)
    • User support email: Your support email address
    • App logo: (Optional) Upload your organization’s logo
    • Application home page: Your Wiretastix URL (e.g., https://vpn.example.com)
    • Authorized domains: Add your domain (e.g., example.com)
    • Developer contact information: Your email address

  5. Click Save and Continue

  6. On the Scopes page, click Add or Remove Scopes

  7. Select the following scopes:

    • openid
    • email
    • profile

  8. Click Update and then Save and Continue

  9. If using External user type, add test users on the next page (optional during development)

  10. Click Save and Continue and review your settings

  11. Click Back to Dashboard

Step 3: Create OAuth 2.0 Credentials

Now create the OAuth client credentials:

  1. Navigate to APIs & Services → Credentials

  2. Click + Create Credentials → OAuth client ID

  3. Select Application type: Web application

  4. Enter a Name: Wiretastix OIDC Client

  5. Under Authorized redirect URIs, click + Add URI

  6. Add your Wiretastix callback URL:

    https://vpn.example.com/callback

    Replace vpn.example.com with your actual Wiretastix domain

  7. Click Create

  8. A dialog will appear with your Client ID and Client Secret

    • Save these credentials immediately - you’ll need them for the Wiretastix configuration
    • Click Download JSON to save a copy (optional but recommended)

Step 4: Configure Wiretastix

Now configure Wiretastix to use Google as the OIDC provider. Edit your /etc/wiretastix/wiretastix.yaml file:

oidc:
    name: Google
    client-id: YOUR_CLIENT_ID.apps.googleusercontent.com
    client-secret: YOUR_CLIENT_SECRET
    redirect-url: https://vpn.example.com/callback
    config-issuer: https://accounts.google.com/.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
    constraints:
        email:
            - user1@example.com
            - user2@example.com

Configuration Parameters Explained

  • name: A friendly name for the provider (displayed in logs)
  • client-id: The Client ID from Step 3 (ends with .apps.googleusercontent.com)
  • client-secret: The Client Secret from Step 3
  • redirect-url: Must match exactly what you configured in Google Cloud Console
  • config-issuer: Google’s OIDC discovery URL (use the URL shown above)
  • 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 (usually false)
  • verbose: Enable detailed OIDC logging for troubleshooting
  • refresh-min-interval-sec: Minimum seconds between token refresh attempts (300 = 5 minutes)
  • scopes: Required OAuth scopes - these are standard for Google
  • constraints: Access control rules

Understanding Constraints

Google authentication doesn’t provide group claims by default. You must use email-based constraints to control access:

Email Constraints (Required for Google)

Specify which email addresses are allowed to authenticate:

constraints:
    email:
        - alice@example.com
        - bob@example.com
        - team@example.com

Important: Google does not provide group membership in standard OIDC claims. If you need group-based access control, consider:

  1. Using Google Workspace with a custom claim provider
  2. Using the default_group configuration parameter in Wiretastix to assign all Google users to a specific group
  3. Manually managing user group memberships in Wiretastix after authentication

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 6: 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 7: Test the Integration

  1. Open your web browser and navigate to your Wiretastix URL (e.g., https://vpn.example.com)
  2. You should be redirected to the Google sign-in page
  3. Sign in with a Google account that matches your email constraints
  4. If this is the first time, you’ll see the OAuth consent screen - click Allow
  5. 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 your Wiretastix configuration doesn’t match what’s configured in Google Cloud Console.

Solution:

  1. Check that the redirect URL in wiretastix.yaml exactly matches what you entered in Google Cloud Console
  2. Ensure there are no trailing slashes or typos
  3. Common format: https://your-domain.com/callback (no trailing slash)

Error: “access_denied” or “User not authorized”

Cause: The user’s email is not in the constraints.email list.

Solution:

  1. Add the user’s email address to the constraints.email list in wiretastix.yaml
  2. Restart Wiretastix daemon
  3. Try authenticating again

Cause: Your OAuth application hasn’t been verified by Google.

Solutions:

  • For Internal apps (Google Workspace): No verification needed
  • For External apps in development: Users will see a warning but can proceed by clicking “Advanced” → “Go to [app name] (unsafe)”
  • For External apps in production: Submit your app for Google OAuth verification

Token Refresh Failures

Cause: Google’s refresh tokens may expire or become invalid.

Solution:

  1. Wiretastix always requests offline access (Google’s access_type=offline) regardless of your scopes list, so there’s nothing to add here for Google specifically – an offline_access scope entry (needed for some other providers) isn’t recognized by Google and wouldn’t help.
  2. If you don’t want users disabled on token refresh failures, disable it via the CLI: config set auto_disable_on_auth_error 0 (this is a runtime parameter, not a wiretastix.yaml field)
  3. Increase refresh-min-interval-sec to reduce refresh frequency

Enable Verbose Logging

For troubleshooting, enable verbose OIDC logging:

oidc:
    verbose: true

Restart Wiretastix and check the logs:

sudo journalctl -u wiretastix -f

Google Workspace Considerations

If you’re using Google Workspace (formerly G Suite):

  1. Internal User Type: Select “Internal” on the OAuth consent screen to restrict access to your organization
  2. Admin SDK Access: For group-based access, you would need to use Google Admin SDK (requires additional setup not covered by standard OIDC)
  3. Domain Restriction: You can restrict email constraints to your domain:
constraints:
    email:
        - "*@yourcompany.com"  # Note: Wiretastix may not support wildcards - list users explicitly

Security Best Practices

  1. Use HTTPS: Always use HTTPS for your Wiretastix instance
  2. Restrict Email Access: Only add authorized users to the constraints.email list
  3. Secure Cookie Secret: Generate a strong random cookie secret and keep it confidential
  4. Monitor Access Logs: Regularly review Wiretastix logs for unauthorized access attempts
  5. Token Expiration: Configure appropriate token refresh intervals based on your security requirements

Next Steps

After successfully configuring Google OIDC:

Additional Resources