Skip to content

Commit a63bd2a

Browse files
SelaseKaySelaseKay
authored
docs(auth): enhance iOS phone authentication error handling and setup instructions (#18175)
1 parent 752cbca commit a63bd2a

2 files changed

Lines changed: 60 additions & 0 deletions

File tree

‎docs/auth/errors.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -97,3 +97,11 @@ try {
9797
}
9898
}
9999
```
100+
101+
## `recaptcha-sdk-not-linked` (iOS phone auth)
102+
103+
If `e.code` is **`recaptcha-sdk-not-linked`** during **`verifyPhoneNumber`** on **iOS**, the native layer expects **reCAPTCHA Enterprise**
104+
to be linked or your **Identity Platform** project configuration must be adjusted. This is not fixed from Dart alone.
105+
106+
See [Phone Authentication — iOS: reCAPTCHA SDK and Identity Platform](/docs/auth/phone-auth#ios-recaptcha-sdk-and-identity-platform) for
107+
recommended setup, the Safari flow, and a documented **GCP / Identity Toolkit** workaround with trade-offs.

‎docs/auth/phone-auth.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,12 +26,64 @@ Before starting with Phone Authentication, ensure you have followed these steps:
2626
your APNs authentication key is [configured with Firebase Cloud Messaging (FCM)](/docs/cloud-messaging/ios/certs). Additionally, you must
2727
[enable background modes](https://help.apple.com/xcode/mac/current/#/deve49d0ba96) for remote notifications.
2828
To view an in-depth explanation of this step, view the [Firebase iOS Phone Auth](/docs/auth/ios/phone-auth) documentation.
29+
If verification fails with **`recaptcha-sdk-not-linked`** (*The reCAPTCHA SDK is not linked to your app*), see
30+
[iOS: reCAPTCHA SDK and Identity Platform](#ios-recaptcha-sdk-and-identity-platform).
2931
4. **Web**: Ensure that you have added your applications domain on the [Firebase console](https://console.firebase.google.com/), under
3032
**OAuth redirect domains**.
3133

3234
**Note**; Phone number sign-in is only available for use on real devices and the web. To test your authentication flow on device emulators,
3335
please see [Testing](#testing).
3436

37+
## iOS: reCAPTCHA SDK and Identity Platform
38+
39+
On **iOS**, phone sign-in can fail with `FirebaseAuthException` code **`recaptcha-sdk-not-linked`** (for example: *The reCAPTCHA SDK is not linked to your app*).
40+
That error is raised by the **native Firebase iOS Auth** SDK when your Firebase / **Identity Platform** configuration expects **reCAPTCHA Enterprise**
41+
for SMS-related verification, but the **reCAPTCHA Enterprise iOS SDK** is not linked in your Xcode project.
42+
43+
The `firebase_auth` plugin does not inject a reCAPTCHA client from Dart—you must fix this in **native iOS** setup or in **Google Cloud / Firebase** configuration.
44+
45+
### Recommended: Link reCAPTCHA Enterprise on iOS
46+
47+
Add the **reCAPTCHA Enterprise** client to your app using Google’s guide:
48+
[Instrument your iOS app with reCAPTCHA Enterprise](https://cloud.google.com/recaptcha-enterprise/docs/instrument-ios-apps)
49+
(CocoaPods or Swift Package Manager), so Firebase Auth can satisfy the Enterprise requirement.
50+
51+
### Safari-hosted challenge (`SFSafariViewController`)
52+
53+
If the SDK uses a **Safari view controller**-hosted challenge instead of the Enterprise SDK, your app must handle the **return URL**
54+
(for example with **`uni_links`** / **`app_links`**, or **`onOpenUrl`** / **`application:openURL:`** in the iOS runner), following standard
55+
Flutter + Firebase iOS setup for OAuth-style callbacks.
56+
57+
### When you don’t need reCAPTCHA Enterprise for phone auth
58+
59+
[Google’s guide to reCAPTCHA SMS defense](https://cloud.google.com/identity-platform/docs/recaptcha-tfp) describes an **optional** Identity Platform
60+
feature that depends on the **reCAPTCHA Enterprise API** and (on iOS) linking the [reCAPTCHA Enterprise client](https://cloud.google.com/recaptcha-enterprise/docs/instrument-ios-apps).
61+
Standard Firebase phone authentication often **does not** require that flow—turning **reCAPTCHA Enterprise** on in Firebase / Google Cloud without also
62+
shipping the native SDK can surface **`recaptcha-sdk-not-linked`**.
63+
64+
### Disable reCAPTCHA SMS defense (Google-documented REST update)
65+
66+
To **disable** reCAPTCHA SMS defense (for example when you cannot or won’t link the Enterprise SDK), Google documents a **`projects.updateConfig`** call
67+
on **`projects/{project_id}/config`** with **`updateMask=recaptchaConfig`** and:
68+
69+
- `recaptchaConfig.phoneEnforcementState`: **`OFF`**
70+
- `recaptchaConfig.useSmsTollFraudProtection`: **`false`**
71+
72+
Use Google’s **official steps** (including the **APIs Explorer** URL with `PROJECT_ID` replaced by your project ID):
73+
74+
- [Disable reCAPTCHA SMS defense](https://cloud.google.com/identity-platform/docs/recaptcha-tfp#disable_recaptcha_sms_defense)
75+
- REST reference: [`projects.updateConfig`](https://cloud.google.com/identity-platform/docs/reference/rest/v2/projects/updateConfig)
76+
77+
Some developers report that **enabling then disabling** *Manage reCAPTCHA* / **reCAPTCHA Enterprise API** in the Firebase or Google Cloud UI can leave
78+
**`recaptchaConfig`** expecting Enterprise until the **`OFF` / `false`** update is applied; see
79+
[flutterfire#18171 (comment)](https://github.com/firebase/flutterfire/issues/18171#issuecomment-4195461765).
80+
81+
**Caution:** Disabling SMS defense **reduces fraud protection**. Prefer keeping defense **on** and [linking reCAPTCHA Enterprise on iOS](#recommended-link-recaptcha-enterprise-on-ios) when your product allows.
82+
83+
More context: [flutterfire#18171](https://github.com/firebase/flutterfire/issues/18171),
84+
[flutterfire#17557](https://github.com/firebase/flutterfire/issues/17557),
85+
[firebase-ios-sdk#15345](https://github.com/firebase/firebase-ios-sdk/issues/15345).
86+
3587
## Usage
3688

3789
The Firebase Authentication SDK for Flutter provides two individual ways to sign a user in with their phone number. Native (e.g. Android & iOS) platforms provide

0 commit comments

Comments
 (0)