Skip to main content

OAuth Authentication - Complete Guide

Overview​

This system supports 3 OAuth providers for social login on Web, iOS, and Android.

How OAuth Works​

Configuration Summary​

Environment Variables (.env)​

# URLs
API_BASE_URL=https://gateway-dev.vislagps.com
FRONTEND_URL=https://app.vislagps.com

# Google
OPENID_GOOGLE_ENABLED=true
OPENID_GOOGLE_CLIENT_ID=861438780212-us1il74aga5qt5op4b40urbmjs1j6pvj.apps.googleusercontent.com

# Apple
OPENID_APPLE_ENABLED=true
OPENID_APPLE_CLIENT_ID=com.vislagps.auth
OPENID_APPLE_TEAM_ID=NUNKKKUWA5
OPENID_APPLE_KEY_ID=<your-key-id>

# Facebook
OPENID_FACEBOOK_ENABLED=true
OPENID_FACEBOOK_CLIENT_ID=1811641626160163

Secrets (secrets/ folder)​

FileContent
google_client_secretGoogle OAuth client secret
facebook_client_secretFacebook App Secret
apple_private_keyContents of .p8 file from Apple

1. Google OAuth​

👉 Google Cloud Console - Visla GPS

Web Configuration​

SettingValue
JavaScript Originshttps://app.vislagps.com, http://localhost:3000
Redirect URIshttps://gateway-dev.vislagps.com/api/auth/openid/callback

iOS Configuration​

  • Create separate OAuth client (Type: iOS)
  • Bundle ID: com.visla.vislagps
  • Client ID: 861438780212-cgm257n7a1o31cvnt2kims6i0r6rone6.apps.googleusercontent.com

Android Configuration​

  • Create separate OAuth client (Type: Android)
  • Package: com.visla.vislagps
  • SHA-1: Get from keystore with keytool -list -v -keystore <path>
  • Client ID: 861438780212-po9gav58mees3daco25oh94540sb15c3.apps.googleusercontent.com

2. Apple Sign In​

👉 Apple Developer - Service ID

Requirements​

  1. App ID (com.visla.vislagps) - Sign in with Apple enabled
  2. Service ID (com.vislagps.auth) - For web login
  3. Key - Download .p8 file for backend

Web Configuration​

SettingValue
Domainsgateway-dev.vislagps.com
Return URLshttps://gateway-dev.vislagps.com/api/auth/openid/callback

iOS Configuration​

  • Uses native ASAuthorizationController
  • Bundle ID: com.visla.vislagps
  • Enable "Sign in with Apple" capability in Xcode
  • Backend accepts both Service ID and Bundle ID as valid audiences

Android Configuration​

  • Apple Sign In on Android uses web-based flow
  • Uses Service ID (com.vislagps.auth)

[!WARNING] Apple only sends user's name on first login. Store it immediately!

3. Facebook Login​

👉 Facebook Developers - Visla GPS

Web Configuration​

SettingPath
Valid OAuth Redirect URIsFacebook Login → Settings
Valuehttps://gateway-dev.vislagps.com/api/auth/openid/callback

iOS Configuration​

In Info.plist:

<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>fb1811641626160163</string>
    </array>
  </dict>
</array>
<key>FacebookAppID</key>
<string>1811641626160163</string>
<key>FacebookClientToken</key>
<string><!-- Get from Facebook Console → Settings → Advanced --></string>
<key>FacebookDisplayName</key>
<string>Visla GPS</string>
<key>LSApplicationQueriesSchemes</key>
<array>
  <string>fbapi</string>
  <string>fb-messenger-share-api</string>
</array>

Android Configuration​

In res/values/strings.xml:

<string name="facebook_app_id">1811641626160163</string>
<string name="facebook_client_token"><!-- From Facebook Console --></string>
<string name="fb_login_protocol_scheme">fb1811641626160163</string>

In AndroidManifest.xml:

<meta-data android:name="com.facebook.sdk.ApplicationId" android:value="@string/facebook_app_id"/>
<meta-data android:name="com.facebook.sdk.ClientToken" android:value="@string/facebook_client_token"/>

[!IMPORTANT] Facebook app must be in Live mode for public users. Development mode = only test users.

Troubleshooting​

ErrorCauseFix
Invalid redirect URIRedirect URL mismatchCheck exact URL in console matches backend
Invalid audienceWrong client IDVerify OPENID_*_CLIENT_ID matches console
Apple invalid_requestConfig not propagatedWait 5-10 min after saving Apple config
Facebook email missingUser denied permissionRequest must include email scope

Deploy Changes​

After any configuration change:

docker-compose up -d --build auth