Updated- December 2025 -Step-by-Step Guide to Set Up Google as an OAuth 2.0 / OIDC Identity Provider in Your App

General
,
1

Prerequisites : Google account, Google Cloud Console access, and your Pangolin app running locally.

Step 1: Create a Google Cloud Project (Unchanged)

  1. Go to Google Cloud Console.
  2. Click project dropdown > New Project > Name it (e.g., “Pangolin OAuth”) > Create.
  3. Select the project.

Step 2: Enable APIs (Optional)

  • APIs & Services > Library > Enable Google+ API if needed for profile data.

image
image1035×541 59.3 KB

Step 3: Create OAuth 2.0 Credentials in Google

  1. APIs & Services > Credentials > + CREATE CREDENTIALS > OAuth client ID.
  2. Configure OAuth consent screen (External/Internal, app details, scopes, etc.).
  3. Select Web application.
  4. Name it (e.g., “Pangolin Web App”).
  5. Authorized redirect URIs: Leave blank for now—we’ll add the exact Pangolin path in Step 5.
  6. Create and copy Client ID & Client Secret.

image
image1735×810 151 KB

Step 4: Configure the OAuth 2.0 / OIDC Provider in Pangolin Dashboard (Unchanged Core, But Note Path)

  1. In Pangolin: Identity Providers > Add Provider > OAuth2/OIDC.
  2. Client ID: Paste from Google.
  3. Client Secret: Paste from Google.
  4. Authorization URL: https://accounts.google.com/o/oauth2/v2/auth
  5. Token URL: https://oauth2.googleapis.com/token
  6. Token Configuration (JMESPath from ID token):
    • Identifier Path: sub
    • Email Path: email
    • Name Path: name
  7. Scopes: openid email profile
  8. Save/Create. Pangolin will generate and display your callback URL: http://localhost:3000/auth/idp/1/oidc/callback (or your base URL + /auth/idp/1/oidc/callback). Copy this exact full URL—it’s unique to your IDP #1.

Step 5: Add the Exact Callback URL to Google (Updated for Your Path)

  1. In Google Cloud Console: APIs & Services > Credentials > [Your Client ID].
  2. Under Authorized redirect URIs, click + Add URI.
  3. Paste the full exact URL from Pangolin: http://localhost:3000/auth/idp/1/oidc/callback
    • Key Notes on This Path:
      • Base URL: Use http://localhost:3000 for local dev (HTTP is allowed here). Switch to https://yourdomain.com for production.
      • /auth/idp/1/oidc/callback: Don’t modify—/idp/1 is Pangolin’s slot for your first provider (e.g., Google). /oidc/callback handles the OIDC token exchange securely.
      • Exact Match Required: Google rejects mismatches (e.g., no extra /, wrong casing, or missing /1). If your base changes (e.g., port 8080), regenerate in Pangolin and update here.
  4. Save. Wait 5–10 minutes for changes to propagate (as per Google’s note).

Step 6: Test the Integration (Updated for Path Verification)

  1. Start your Pangolin app locally (http://localhost:3000).
  2. Trigger login (e.g., “Sign in with Google”).
  3. Flow: App → Google Auth Page → Consent → Redirect to /auth/idp/1/oidc/callback → Token exchange → User session with extracted data (sub, email, name).
  4. Verify in Browser/Logs:
    • Success: Redirect lands on your app’s post-login page (e.g., dashboard) with Google user info.
    • Check URL bar during redirect: Should hit exactly .../auth/idp/1/oidc/callback?code=... (code is the auth token).
  5. Troubleshoot Path-Specific Issues:
    • redirect_uri_mismatch: Path doesn’t match—re-copy from Pangolin and re-add to Google.
    • 404 on Callback: App server not routing to /auth/idp/1/oidc/callback—check Pangolin routes or restart server.
    • No Data Extraction: Confirm JMESPath paths (sub, etc.) and openid scope.

Step 7: Go Live (Production) (Updated for Path)

  • Update callback in Pangolin to production base (e.g., https://yourapp.com/auth/idp/1/oidc/callback).
  • Add this exact new URL to Google (remove localhost).
  • Authorized JavaScript origins: Add https://yourapp.com if using client-side auth.
  • Publish OAuth consent screen.
  • Test end-to-end on live domain.

Why This Path is Secure & Reliable (Keeping in Mind)

  • Pangolin-Specific: The /idp/1 ensures isolation if you add more providers (e.g., GitHub as /idp/2). It won’t conflict or expose other auths.
  • OIDC Best Practice: Handles ID token validation automatically—no manual JWT parsing needed in your code.
  • Scalable: If you delete/recreate the provider, Pangolin might reassign the number (e.g., to /idp/2)—just update Google accordingly.