wiretastix

Configure LinkedIn OAuth SSO for WireGuard

How to set up LinkedIn OAuth/OIDC single sign-on (SSO) for Wiretastix WireGuard VPN authentication.

This guide will walk you through configuring LinkedIn OAuth/OIDC as your Identity Provider for Wiretastix, enabling single sign-on (SSO) so users authenticate with their LinkedIn accounts.

Prerequisites

Before you begin, ensure you have:

  • A LinkedIn account (personal or company account)
  • Access to the LinkedIn Developers Portal
  • Your Wiretastix instance URL (e.g., https://vpn.example.com)
  • Administrative access to your Wiretastix configuration

Important Note: LinkedIn’s OAuth 2.0 implementation has some differences from standard OpenID Connect. This guide covers the setup process, but be aware of LinkedIn’s specific limitations.

Step 1: Create a LinkedIn App

  1. Navigate to the LinkedIn Developers Portal
  2. Click Create app
  3. Fill in the required information:
    • App name: Wiretastix VPN (or your preferred name)
    • LinkedIn Page: Select your company’s LinkedIn page (you must be an admin of the page)
      • If you don’t have a company page, you’ll need to create one first
    • App logo: Upload your organization’s logo (optional but recommended)
    • Legal agreement: Check the box to agree to LinkedIn’s API Terms of Use
  4. Click Create app

Step 2: Configure App Settings

After creating the app, you’ll be taken to the app settings page:

  1. On the Settings tab, note your:

    • Client ID: You’ll need this for Wiretastix configuration
    • Client Secret: Click Show and copy this value (keep it secure)

  2. Scroll down to Redirect URLs (also called Authorized redirect URLs for your app)

  3. Click the Edit icon (pencil)

  4. Add your Wiretastix callback URL:

    https://vpn.example.com/callback

    Replace vpn.example.com with your actual Wiretastix domain

  5. Click Update

Step 3: Request API Access

LinkedIn requires you to request access to specific API products:

  1. Click on the Products tab in your app settings
  2. Find Sign In with LinkedIn using OpenID Connect
  3. Click Request access
  4. Fill in the required information about why you need access
  5. Submit the request

Note: LinkedIn typically reviews access requests within a few business days. For development and testing, you can proceed with the limited default access.

Step 4: Verify App Settings

Before configuring Wiretastix, verify the following on the Settings tab:

  1. Application Status: Should show as “Active” or “In Development”
  2. Redirect URLs: Verify your callback URL is listed
  3. Client ID and Secret: Ensure you have both values saved

Step 5: Configure Wiretastix

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

oidc:
    name: LinkedIn
    client-id: YOUR_LINKEDIN_CLIENT_ID
    client-secret: YOUR_LINKEDIN_CLIENT_SECRET
    redirect-url: https://vpn.example.com/callback
    config-issuer: https://www.linkedin.com/oauth/.well-known/openid-configuration
    cookie-secret: GENERATE_A_RANDOM_STRING_HERE
    force-approval: false
    verbose: false
    refresh-min-interval-sec: 300
    scopes:
        - openid
        - profile
        - email
    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 your LinkedIn app
  • client-secret: The Client Secret from your LinkedIn app
  • redirect-url: Must match exactly what you configured in LinkedIn app settings
  • config-issuer: LinkedIn’s OpenID Connect discovery endpoint
  • 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
  • scopes: Required OAuth scopes for LinkedIn
  • constraints: Access control rules

Understanding LinkedIn Scopes

LinkedIn supports the following OpenID Connect scopes:

  • openid: Required - Enables OpenID Connect authentication
  • profile: Provides access to basic profile information (name, picture)
  • email: Provides access to the user’s primary email address

Important: To access the email scope, your app must have been granted access to “Sign In with LinkedIn using OpenID Connect” in the Products tab.

Understanding Constraints

LinkedIn does not provide group or organization membership in OIDC claims. You must use email-based constraints:

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

Limitation: LinkedIn does not support group-based access control through OIDC. You’ll need to:

  1. Use email constraints to control access
  2. Manually assign users to groups in Wiretastix after their first login
  3. Configure a default_group in Wiretastix to automatically assign authenticated users

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 7: 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 8: 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 LinkedIn’s sign-in page
  3. Sign in with a LinkedIn account whose email matches your constraints
  4. If this is the first time, you’ll see the LinkedIn authorization screen:
    • Review the permissions being requested
    • Click Allow to grant access
  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 LinkedIn.

Solution:

  1. Go to your LinkedIn app Settings → Auth section
  2. Verify the redirect URL exactly matches your redirect-url in wiretastix.yaml
  3. Ensure there are no trailing slashes or protocol mismatches (http vs https)
  4. Click Update after making changes
  5. Restart Wiretastix and try again

Error: “access_denied”

Cause: The user declined authorization or their email is not in the constraints list.

Solutions:

  1. Ensure the user clicks Allow on the LinkedIn authorization screen
  2. Verify the user’s email address is in the constraints.email list
  3. Check that the user’s email is verified on their LinkedIn account

Error: “invalid_scope” or Scope Not Available

Cause: Your app doesn’t have access to the requested scope (typically email).

Solutions:

  1. Go to your LinkedIn app’s Products tab
  2. Verify you’ve requested “Sign In with LinkedIn using OpenID Connect”
  3. Wait for approval if the request is pending
  4. For testing, you may need to use test accounts or request expedited review

Email Not Returned by LinkedIn

Cause: The email scope requires special access from LinkedIn.

Solutions:

  1. Ensure you’ve been granted access to “Sign In with LinkedIn using OpenID Connect”
  2. Check that email is in your scopes list
  3. During development, use the primary email associated with your test accounts
  4. Consider implementing fallback logic to use LinkedIn ID instead of email

Token Refresh Issues

Cause: LinkedIn’s refresh token behavior differs from other providers.

Solutions:

  1. LinkedIn’s refresh token lifetime is long compared to most providers (check the current value for your app in the LinkedIn Developer Portal, since it isn’t uniform across API products and can change)
  2. Set a longer refresh-min-interval-sec value (e.g., 3600 = 1 hour)
  3. Consider running config set auto_disable_on_auth_error 0 (a CLI runtime parameter, not a wiretastix.yaml field) to prevent automatic user disablement

Enable Verbose Logging

For troubleshooting, enable verbose OIDC logging:

oidc:
    verbose: true

Restart Wiretastix and check the logs:

sudo journalctl -u wiretastix -f

LinkedIn-Specific Considerations

API Rate Limits

LinkedIn enforces rate limits on their APIs:

  • Be mindful of token refresh frequency
  • Increase refresh-min-interval-sec to reduce API calls
  • Monitor your app’s usage in the LinkedIn Developer Portal

Limited User Data

LinkedIn provides limited user information compared to other OIDC providers:

  • No group memberships
  • No organization roles
  • Basic profile data (name, email, picture)

User Verification

LinkedIn users must have verified email addresses to authenticate:

  • Unverified accounts may not return email claims
  • Direct users to verify their email on LinkedIn before attempting to authenticate

Production Access

For production use:

  1. Complete the LinkedIn app verification process
  2. Ensure your app complies with LinkedIn’s terms of service
  3. Request production access for all required scopes
  4. Add clear privacy policy and terms of service links

Testing with LinkedIn Test Accounts

During development, you can test with LinkedIn accounts that are administrators of your LinkedIn page:

  1. Go to your app’s Settings tab
  2. Scroll to App Settings
  3. Admins of the associated LinkedIn page can test authentication before approval

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 Credentials: Keep your client secret confidential
  4. Secure Cookie Secret: Generate a strong random cookie secret
  5. Monitor Access: Regularly review authentication logs
  6. Token Storage: LinkedIn tokens are stored encrypted by Wiretastix
  7. Limit Scope: Only request the scopes you actually need

Limitations and Alternatives

LinkedIn Limitations

  • No group-based access control
  • Limited to email-based user identification
  • Requires app verification for production use
  • API rate limits may affect large deployments

Alternative Approaches

If LinkedIn’s limitations are problematic, consider:

  1. Using LinkedIn as secondary authentication: Combine with another IdP for group management
  2. Manual group assignment: Assign users to Wiretastix groups after first login
  3. Alternative IdP: Use a more feature-rich OIDC provider like Authentik or Keycloak

Next Steps

After successfully configuring LinkedIn OIDC:

Additional Resources