Skip to main content
This guide walks you through setting up Google OAuth authentication for NetBird Selfservice. While this guide focuses on Google OAuth, you can use any OAuth provider supported by Laravel Socialite.

​
Prerequisites

  • A Google Cloud Console account
  • Admin access to your Google Workspace (if using domain restriction)
  • Access to your application’s .env file

​
Google OAuth Setup

1

Access Google Cloud Console

Navigate to the Google Cloud Console and sign in with your Google account.If you don’t have a project yet, create a new one for your VPN Selfservice application.
2

Enable Google+ API

In your Google Cloud project:
  1. Go to APIs & Services > Library
  2. Search for “Google+ API” or “Google Identity”
  3. Click Enable if not already enabled
Some Google Cloud projects may have this API enabled by default.
3

Configure OAuth Consent Screen

Before creating credentials, configure the OAuth consent screen:
  1. Navigate to APIs & Services > OAuth consent screen
  2. Select Internal (for Google Workspace users only) or External
  3. Fill in the required information:
    • App name: “NetBird Selfservice” or your preferred name
    • User support email: Your support email
    • Developer contact information
  4. Click Save and Continue
  5. Skip adding scopes (default scopes are sufficient)
  6. Click Save and Continue through the remaining steps
If you select Internal, only users within your Google Workspace organization can sign in.
4

Create OAuth Client ID

Now create the OAuth credentials:
  1. Navigate to APIs & Services > Credentials
  2. Click Create Credentials > OAuth client ID
  3. Select Web application as the application type
  4. Enter a name (e.g., “VPN Selfservice Web Client”)
5

Configure Redirect URIs

In the OAuth client configuration, add your authorized redirect URIs:Authorized redirect URIs:
https://your-domain.com/admin/oauth/callback/google
For local development, also add:
http://localhost:8000/admin/oauth/callback/google
Click Create when done.
6

Copy Credentials

After creating the OAuth client, Google will display your credentials:
  • Client ID: A long string ending in .apps.googleusercontent.com
  • Client Secret: A shorter secret string
Keep this window open or download the credentials JSON file.
7

Configure Environment Variables

Open your application’s .env file and add the OAuth credentials:
# Google OAuth Configuration
GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secret
GOOGLE_REDIRECT_URI=https://your-domain.com/admin/oauth/callback/google
Replace the values with your actual credentials from the previous step.
8

Configure Domain Restriction (Recommended)

To restrict access to users from your organization’s domain:
# Security Settings
NETBIRD_ALLOWED_DOMAIN=example.com
Only users with email addresses from this domain will be able to sign in. Make sure this matches your organization’s email domain.

​
Testing Authentication

After configuring OAuth:
1

Restart Your Application

Restart your web server to load the new environment variables:
# If using Laravel's built-in server
php artisan serve

# If using a process manager
php artisan config:clear
2

Test Sign In

  1. Navigate to your application’s login page
  2. Click the “Sign in with Google” button
  3. You should be redirected to Google’s OAuth consent screen
  4. After granting permission, you’ll be redirected back to the application
First-time users may need to grant permission for the application to access their basic profile information.
3

Verify Domain Restriction

If you configured NETBIRD_ALLOWED_DOMAIN, test with:
  • A user from the allowed domain (should succeed)
  • A user from a different domain (should be rejected)

​
Alternative OAuth Providers

NetBird Selfservice uses Laravel Socialite, which supports many OAuth providers:
  1. Create an OAuth App in GitHub Settings > Developer settings
  2. Add to .env:
GITHUB_CLIENT_ID=your-github-client-id
GITHUB_CLIENT_SECRET=your-github-client-secret
GITHUB_REDIRECT_URI=https://your-domain.com/auth/github/callback
  1. Update routes in routes/web.php to use github driver
  1. Register an application in Azure Portal
  2. Install the Socialite provider:
composer require socialiteproviders/microsoft-azure
  1. Configure in .env and update authentication controller
  1. Create an application in your Okta admin panel
  2. Install the Socialite provider:
composer require socialiteproviders/okta
  1. Configure with your Okta domain and credentials
When using alternative providers, you’ll need to modify app/Http/Controllers/Auth/GoogleController.php to support the new driver. Refer to Laravel Socialite documentation for provider-specific configuration.

​
Troubleshooting

​
”Redirect URI mismatch” error

  • Verify the redirect URI in your .env file exactly matches the one configured in Google Cloud Console
  • Check for trailing slashes (e.g., /callback vs /callback/)
  • Ensure you’re using HTTPS in production

​
”Access blocked” error

  • Check if NETBIRD_ALLOWED_DOMAIN is configured correctly
  • Verify the user’s email domain matches the allowed domain
  • Review the OAuth consent screen configuration

​
”Invalid client” error

  • Verify GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET are correct
  • Check for extra spaces or line breaks in the .env file
  • Run php artisan config:clear after changing environment variables

​
Security Best Practices

  • Always use HTTPS in production
  • Keep your GOOGLE_CLIENT_SECRET secure and never commit it to version control
  • Regularly rotate your OAuth credentials
  • Enable domain restriction with NETBIRD_ALLOWED_DOMAIN
  • Review OAuth consent scope permissions regularly

​
Next Steps

Once OAuth is configured, proceed to:

Build docs developers (and LLMs) love

Get started for freeTalk to us