OAuth2 SSO Integration Guide

This guide explains how to integrate OAuth2 Single Sign-On with Protrak.

Prerequisites

Before configuring OAuth2 SSO, ensure you have:

• Administrative access to your OAuth2 Provider
• Administrative access to Protrak
• Your OAuth2 Provider's configuration details

Step 1: Register Protrak App and Gather OAuth2 Provider Configuration

1.1 Register Protrak Application

First, register your Protrak application with your OAuth2 Provider:

1. Access your OAuth2 Provider's admin console
2. Create a new application/client registration with redirect URIs:
   • Login Redirect URI: https://app.protrak.io/oidc/callback
   • Logout Redirect URI: https://app.protrak.io/oidc/logout/callback
3. Note down the generated details

1.2 Gather Configuration Details

You'll need the following configuration details from previous step:

Field	Description	Example
authorizationEndpoint	The OAuth2 authorization URL	https://provider.com/oauth2/authorize
tokenEndpoint	The OAuth2 token exchange URL	https://provider.com/oauth2/token
clientId	The unique identifier for your app registered with the provider	abc123-def456-ghi789
clientSecret	Secret key for your registered application	XyZ789-secure-secret-key
redirectUri	URI where the provider will redirect after login	https://app.protrak.io/oidc/callback
postLogoutRedirectUri	URI where the provider will redirect after logout	https://app.protrak.io/oidc/logout/callback
responseType	OAuth2 response type (usually "code" for Authorization Code Flow)	code
scope	Requested scopes for user information	openid email profile
grantType	OAuth2 grant type	authorization_code

Step 2: Create JSON Configuration

Create a JSON configuration object using the information gathered from your OAuth2 Provider:

Configuration Template

{
  "authorizationEndpoint": "https://your-oauth2-provider/oauth2/authorize",
  "tokenEndpoint": "https://your-oauth2-provider/oauth2/token",
  "clientId": "your-client-id",
  "clientSecret": "your-client-secret",
  "redirectUri": "https://your-domain.protrak.io/oauth2/callback",
  "postLogoutRedirectUri": "https://your-domain.protrak.io/oauth2/logout/callback",
  "responseType": "code",
  "grantType": "authorization_code",
  "scope": "openid email profile",
  "userInfoEndpoint": "https://your-oauth2-provider/user"
}

Example Configuration (Google OAuth2)

{
  "authorizationEndpoint": "https://accounts.google.com/o/oauth2/v2/auth",
  "tokenEndpoint": "https://oauth2.googleapis.com/token",
  "clientId": "123456789-abc123def456.apps.googleusercontent.com",
  "clientSecret": "GOCSPX-xyz789abc123def456",
  "redirectUri": "https://app.protrak.io/oauth2/callback",
  "postLogoutRedirectUri": "https://app.protrak.io/oauth2/logout/callback",
  "responseType": "code",
  "grantType": "authorization_code",
  "scope": "openid email profile"
}

Example Configuration (Custom OAuth2 Provider)

{
  "authorizationEndpoint": "https://auth.company.com/oauth2/authorize",
  "tokenEndpoint": "https://auth.company.com/oauth2/token",
  "clientId": "protrak-app-client-id",
  "clientSecret": "super-secure-client-secret",
  "redirectUri": "https://app.protrak.io/oauth2/callback",
  "postLogoutRedirectUri": "https://app.protrak.io/oauth2/logout/callback",
  "responseType": "code",
  "grantType": "authorization_code",
  "scope": "profile email company:read",
  "userInfoEndpoint": "https://auth.company.com/api/user"
}

Step 3: Configure SSO in Protrak

3.1 Access SSO Settings

1. Login to your Protrak application as an administrator
2. Navigate to Tenant Settings → SSO Settings
3. Click the "Create SSO Setting" button

3.2 Configure OAuth2 Settings

1. Name: Enter a descriptive name (e.g., "IDP-name-OAuth2")
2. Provider Name: Enter a descriptive name (e.g., "Login with Google/Azure")
3. Identity Provider Type: Select "OAuth 2"
4. Web Config: Paste the JSON configuration created in Step 2
5. Default Setting: Check this box if you want this to be the default SSO method for all users

3.3 Save and Test Configuration

1. Click "Save" to store the configuration
2. Note: The system will validate your configuration before saving
3. Once saved, logout from Protrak to test the new SSO setup

Step 4: Testing OAuth2 Integration

4.1 Initial Login Test

1. Logout from Protrak (if currently logged in)
2. Navigate to your Protrak login page
3. Enter an email address from your configured domain
4. Verify redirection to your OAuth2 provider
5. Complete authentication with your provider credentials
6. Confirm successful redirect back to Protrak with proper user session

4.2 Comprehensive Testing Checklist

Test Type	Action	Expected Result
User Authentication	Login with valid OAuth2 credentials	Successful login and user session creation
User Information Mapping	Verify user profile in Protrak	Correct name, email, and attributes from OAuth2 provider
Access Control	Test with different user roles	Proper role-based access within Protrak
Session Management	Test logout functionality	Complete session termination and redirect
Error Handling	Test with invalid credentials	Appropriate error messages and graceful failure
Domain Validation	Test with non-configured domain email	Proper fallback to standard authentication

Step 5: OAuth2 Flow Details

Authorization Code Flow

The OAuth2 integration follows the standard Authorization Code flow:

1. User Initiates Login: User enters email in Protrak

2. Authorization Request: Protrak redirects to OAuth2 provider with:

   GET https://provider.com/oauth2/authorize?
     response_type=code&
     client_id=YOUR_CLIENT_ID&
     redirect_uri=https://your-domain.protrak.io/oauth2/callback&
     scope=read:user read:email&
     state=RANDOM_STATE_VALUE

3. User Authentication: User authenticates with OAuth2 provider

4. Authorization Code: Provider redirects back with authorization code:

   GET https://your-domain.protrak.io/oauth2/callback?
     code=AUTHORIZATION_CODE&
     state=RANDOM_STATE_VALUE

5. Token Exchange: Protrak exchanges code for access token:

   POST https://provider.com/oauth2/token
   Content-Type: application/x-www-form-urlencoded
   
   grant_type=authorization_code&
   code=AUTHORIZATION_CODE&
   redirect_uri=https://your-domain.protrak.io/oauth2/callback&
   client_id=YOUR_CLIENT_ID&
   client_secret=YOUR_CLIENT_SECRET

Troubleshooting

Common Issues

Issue: "Invalid Redirect URI" error

• Solution: Ensure the redirectUri in your JSON config matches exactly with what's configured in your OAuth2 Provider
• Check: Verify the redirect URI is registered in your OAuth2 application settings

Issue: "Invalid Client" error

• Solution: Verify clientId and clientSecret are correct and the application is enabled in your OAuth2 provider
• Check: Ensure the client credentials haven't expired

Issue: "Insufficient Scope" error

• Solution: Verify the requested scopes are available and approved for your application
• Check: Ensure your OAuth2 app has permission to access user email and profile information

Issue: "User not found" error

• Solution: Ensure the user exists in Protrak or enable auto-user creation if supported
• Check: Verify the email mapping between OAuth2 provider and Protrak

Issue: "Access Token Invalid" error

• Solution: Check token endpoint URL and ensure proper token exchange
• Check: Verify network connectivity and SSL certificates

Issue: "User Info Fetch Failed" error

• Solution: Verify userInfoEndpoint URL is correct and accessible
• Check: Ensure access token has sufficient permissions to fetch user information

Testing Tips

• Use browser developer tools to inspect network requests during login
• Check OAuth2 provider logs for detailed error messages
• Test with a dedicated test user first before rolling out to all users
• Verify time synchronization between Protrak and your OAuth2 provider
• Use tools like Postman to test OAuth2 endpoints independently

OAuth2 Provider Specific Troubleshooting

GitHub OAuth2

• Ensure your GitHub App has "User email addresses" permission enabled
• Verify the application is not suspended or rate-limited
• Check that the repository/organization access is correctly configured

Google OAuth2

• Verify your Google Cloud Console project has the necessary APIs enabled
• Check OAuth consent screen configuration and approval status
• Ensure the application is not in testing mode if using production users

Custom OAuth2 Providers

• Verify CORS configuration allows requests from Protrak domain
• Check that the OAuth2 implementation follows RFC 6749 standards
• Ensure proper error response formats are implemented

Security Considerations

OAuth2 Provider Security

• Rotate Client Secrets regularly (every 90-180 days)
• Use strong, unique Client Secrets
• Implement proper scope restrictions
• Monitor for unusual access patterns
• Use PKCE (Proof Key for Code Exchange) when supported

Token Security

• Set appropriate token lifetimes (1-8 hours for access tokens)
• Implement token refresh mechanisms when available
• Secure token storage and transmission
• Monitor for token abuse or anomalies

Network Security

• Use HTTPS for all communications
• Implement proper certificate validation
• Configure appropriate CORS policies
• Monitor network traffic for anomalies

Protrak Security

• Regularly audit OAuth2 user access
• Implement least-privilege access principles
• Monitor user login patterns
• Disable unused accounts promptly

Support

For additional help with OAuth2 SSO configuration:

• Check Protrak documentation portal
• Contact your system administrator
• Reach out to Protrak support team
• Consult your OAuth2 provider's documentation

---

This document was last updated on August 27, 2025.