From 1fd8c92755a44df131a37c8b9994d769551de059 Mon Sep 17 00:00:00 2001 From: Subhankar Maiti Date: Tue, 20 Jan 2026 15:23:50 +0530 Subject: [PATCH] docs: Add troubleshooting section for app hanging during social login --- FAQ.md | 89 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 13 ++++++++ 2 files changed, 102 insertions(+) diff --git a/FAQ.md b/FAQ.md index 9001243f..e77b6ec7 100644 --- a/FAQ.md +++ b/FAQ.md @@ -16,6 +16,7 @@ 14. [How do I migrate existing users to DPoP?](#14-how-do-i-migrate-existing-users-to-dpop) 15. [How do I know if my tokens are using DPoP?](#15-how-do-i-know-if-my-tokens-are-using-dpop) 16. [What happens if I disable DPoP after enabling it?](#16-what-happens-if-i-disable-dpop-after-enabling-it) +17. [Why does the app hang or freeze during Social Login (Google, Facebook, etc.)?](#17-why-does-the-app-hang-or-freeze-during-social-login-google-facebook-etc) ## 1. How can I have separate Auth0 domains for each environment on Android? @@ -848,3 +849,91 @@ async function migrateFromDPoP() { - The `getDPoPHeaders()` method gracefully handles both token types - User sessions remain active (no forced logout) - All other SDK functionality remains unchanged + +## 17. Why does the app hang or freeze during Social Login (Google, Facebook, etc.)? + +If your app gets stuck during social authentication (Google, Facebook, etc.) but Auth0 logs show success, the cause is almost always an **incorrectly formatted callback URL**. + +### Step 1: Upgrade to the Latest SDK Version + +Before troubleshooting, ensure you're on the latest version: + +```bash +# Check current version +npm list react-native-auth0 + +# Upgrade to latest +npm install react-native-auth0@latest + +# For iOS, reinstall pods +cd ios && pod install && cd .. +``` + +See the [Migration Guide](https://github.com/auth0/react-native-auth0/blob/master/MIGRATION_GUIDE.md) for breaking changes between major versions. + +### Step 2: Verify Callback URL Format + +#### Android + +``` +{YOUR_APP_PACKAGE_NAME}.auth0://{YOUR_AUTH0_DOMAIN}/android/{YOUR_APP_PACKAGE_NAME}/callback +``` + +**Example:** `com.example.myapp.auth0://example.us.auth0.com/android/com.example.myapp/callback` + +#### iOS + +``` +{PRODUCT_BUNDLE_IDENTIFIER}.auth0://{YOUR_AUTH0_DOMAIN}/ios/{PRODUCT_BUNDLE_IDENTIFIER}/callback +``` + +**Example:** `com.example.myapp.auth0://example.us.auth0.com/ios/com.example.myapp/callback` + +### Common Mistakes + +| ❌ Wrong | ✅ Correct | Platform | +| ------------------------------- | ------------------------------------------------ | -------- | +| `com.example.MyApp.auth0://...` | `com.example.myapp.auth0://...` (lowercase) | Both | +| `.../callback/` | `.../callback` (no trailing slash) | Both | +| `/android/` in iOS URL | `/ios/` for iOS, `/android/` for Android | Both | +| Mismatched domain | Domain must match exactly (e.g., `us.auth0.com`) | Both | + +### Quick Checklist + +- [ ] Using the **latest SDK version** +- [ ] Package/Bundle ID is **all lowercase** in callback URL +- [ ] **No trailing slash** at the end +- [ ] Correct platform path (`/ios/` or `/android/`) +- [ ] Domain matches exactly (e.g., `us.auth0.com` vs `auth0.com`) +- [ ] URL added to **both** Allowed Callback URLs and Allowed Logout URLs in Auth0 Dashboard + +#### Android-specific + +- [ ] `manifestPlaceholders` in `build.gradle` match the dashboard configuration + +#### iOS-specific + +- [ ] `CFBundleURLSchemes` in `Info.plist` matches the callback URL scheme +- [ ] `AppDelegate` has the URL handling code (see README) + +### Debugging + +**Both platforms:** + +1. Check **Auth0 Dashboard → Monitoring → Logs** for success/failure events +2. Test with database connection first—if that works but social doesn't, check the social provider configuration + +**Android:** + +```bash +adb shell dumpsys package your.package.name | grep -A 20 "auth0" +``` + +**iOS:** + +```bash +# Check URL schemes registered +plutil -p ios/YourApp/Info.plist | grep -A 5 "CFBundleURLSchemes" +``` + +> **Note**: The SDK automatically lowercases your package/bundle identifier. If it's `com.example.MyApp`, the callback URL uses `com.example.myapp`. diff --git a/README.md b/README.md index ca37f896..a4aa5ca0 100644 --- a/README.md +++ b/README.md @@ -225,6 +225,9 @@ Now you can run the application using `expo run:android` or `expo run:ios`. Callback URLs are the URLs that Auth0 invokes after the authentication process. Auth0 routes your application back to this URL and appends additional parameters to it, including a token. Since callback URLs can be manipulated, you will need to add this URL to your Application's **Allowed Callback URLs** for security. This will enable Auth0 to recognize these URLs as valid. If omitted, authentication will not be successful. +> [!IMPORTANT] +> **Callback URL Formatting**: Must be **all lowercase**, have **no trailing slash**, and exactly match the URL in Auth0 Dashboard. Incorrect formatting causes the app to "hang" after authentication. See [FAQ #17](https://github.com/auth0/react-native-auth0/blob/master/FAQ.md#17-why-does-the-app-hang-or-freeze-during-social-login-google-facebook-etc) for troubleshooting. + On the Android platform this URL is case-sensitive. Because of that, this SDK will auto convert the Bundle Identifier (iOS) and Application ID (Android) values to lowercase in order to build the Callback URL with them. If any of these values contains uppercase characters a warning message will be printed in the console. Make sure to check that the right Callback URL is whitelisted in the Auth0 dashboard or the browser will not route successfully back to your application. Go to the [Auth0 Dashboard](https://manage.auth0.com/#/applications), select your application and make sure that **Allowed Callback URLs** contains the URLs defined below. @@ -244,6 +247,12 @@ If in addition you plan to use the log out method, you must also add these URLs {YOUR_APP_PACKAGE_NAME}.auth0://{YOUR_AUTH0_DOMAIN}/android/{YOUR_APP_PACKAGE_NAME}/callback ``` +**Example:** If your package name is `com.example.myapp` and your Auth0 domain is `example.us.auth0.com`: + +```text +com.example.myapp.auth0://example.us.auth0.com/android/com.example.myapp/callback +``` + ##### App Link (Recommended): ```text @@ -820,6 +829,10 @@ This library provides a unified API across Native (iOS/Android) and Web platform ## Troubleshooting +### App Hangs During Social Login + +If your app "hangs" during authentication with social connections (Google, Facebook, etc.), first upgrade to the latest SDK version, then verify your callback URL is correctly formatted: **all lowercase**, **no trailing slash**, correct platform path (`/ios/` or `/android/`), and matches the Auth0 Dashboard exactly. See [FAQ #17](https://github.com/auth0/react-native-auth0/blob/master/FAQ.md#17-why-does-the-app-hang-or-freeze-during-social-login-google-facebook-etc) for details. + ### Swift 6 Compatibility Issues on iOS If your main application project is configured to use Swift 6, and you encounter build errors related to Swift version incompatibilities with `react-native-auth0` or its dependencies (like `Auth0.swift`, `JWTDecode`, `SimpleKeychain`), you can ensure these specific pods are compiled with Swift 5.