Skip to main content

OIDC SSO Integration Guide

This guide explains how to integrate OpenID Connect (OIDC) Single Sign-On with Protrak.

Prerequisites​

Before configuring OIDC SSO, ensure you have:

  • Administrative access to your Identity Provider (IdP)
  • Administrative access to Protrak
  • Your Identity Provider's OIDC configuration details

Step 1: Register Protrak App and Gather Identity Provider Configuration​

1.1 Register Protrak Application​

First, register your Protrak application with your Identity Provider:

  1. Access your Identity 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:

FieldDescriptionExample
issuerThe base URL of the IdPhttps://your-identity-provider-url
clientIdThe unique identifier for your app registered with the IdPabc123-def456-ghi789
clientSecretSecret key for your registered application(Do not pass this if your client is public)XyZ789-secure-secret-key
redirectUriURI where the IdP will redirect after loginhttps://app.protrak.io/oidc/callback
postLogoutRedirectUriURI where the IdP will redirect after logouthttps://app.protrak.io/oidc/logout/callback
responseTypeOAuth response type (usually "code" for Authorization Code Flow)code
scopeRequested scopes for user informationopenid profile email

Step 2: Create JSON Configuration​

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

Configuration Template​

{
  "issuer": "https://your-identity-provider-url",
  "clientId": "your-client-id",
  "clientSecret": "your-client-secret",(Do not pass this if your client is public)
  "redirectUri": "https://your-domain.protrak.io/oidc/callback",
  "postLogoutRedirectUri": "https://your-domain.protrak.io/oidc/logout/callback",
  "responseType": "code",
  "scope": "openid email profile",
}

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 "+ SSO Setting" button on right top

3.2 Fill SSO Configuration Form​

  1. Name: Enter a descriptive name (e.g., "IDP-name-OIDC")
  2. Provider Name: Enter a descriptive name (e.g., "Login with Google/Azure")
  3. Identity Provider Type: Select "OIDC"
  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 Configuration​

  1. Click "Save" to store the configuration
  2. Logout from Protrak to test the new SSO setup

Step 4: Test SSO Integration​

4.1 Test Login Flow​

  1. Navigate to your Protrak login page
  2. Enter an email address from your configured domain
  3. You should be redirected to your Identity Provider
  4. Complete authentication with your IdP credentials
  5. Verify successful redirect back to Protrak

4.2 End-to-End Testing​

  • Test with different users to ensure proper access control
  • Verify user information is correctly mapped from IdP to Protrak
  • Test logout functionality to ensure proper session termination and redirect to logout URI
  • Check error handling with invalid credentials

Step 5: External Application Integration​

5.1 Redirect Configuration for External Applications​

When redirecting from external applications(already using your IDP) to Protrak using pre-authentication, you need to configure the proper redirect URLs and parameters.

5.2 Redirect URI Setup​

For external applications redirecting to Protrak, use the following redirect URI format:

https://your-protrak-domain.io/oidcAutoLogin

Important: Replace your-protrak-domain.io with your actual Protrak domain.

5.3 Complete URL Example​

After successful authentication, the user will be redirected to a URL like this:

https://your-protrak-domain.io/oidcAutoLogin?code=skjdhfkjshf&state=protrak-type-name/create

5.4 URL Components Breakdown​

  • Base URL: https://your-protrak-domain.io/oidcAutoLogin
  • Authorization Code: code=skjdhfkjshf (received from IdP)
  • Redirect Path: state=protrak-type-name/create (where to go after login)

5.5 Implementation Notes​

  • The code parameter contains the authorization code from your Identity Provider
  • The state parameter allows you to specify where users should land in Protrak after successful authentication
  • This URL format enables seamless single sign-on without requiring users to authenticate again in Protrak

Troubleshooting​

Common Issues​

Issue: "Invalid Redirect URI" error

  • Solution: Ensure the redirectUri in your JSON config matches exactly with what's configured in your Identity Provider

Issue: "Invalid Client" error

  • Solution: Verify clientId and clientSecret are correct and the application is enabled in your IdP

Issue: "User not found" error

  • Solution: Ensure the user exists in Protrak or enable auto-user creation if supported

Issue: Token validation fails

  • Solution: Check that issuer and tokenEndpoint URLs are correct and accessible

Issue: Logout redirect fails or user not properly logged out

  • Solution: Verify that postLogoutRedirectUri is correctly configured in both your IdP and Protrak configuration

Testing Tips​

  • Use browser developer tools to inspect network requests during login
  • Check Protrak 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 Identity Provider

This document was last updated on August 27, 2025.