Authentication¶
Firebase Authentication signs users
in with a password, an email link, a phone number, an identity provider
(Google, Apple, Facebook...), or your own system, and gives each user a
stable uid that Firestore, Storage and the Realtime Database security rules
can check.
from pyios_firebase.auth import Auth
auth = Auth.auth()
def on_user(user):
if user is None:
show_sign_in()
else:
show_home(user.uid)
auth.add_state_did_change_listener(on_user)
Installation¶
- Add the
FirebaseAuthSwift package product (Installation). - In the Firebase console, open Authentication > Sign-in method and enable the providers you use.
- Some methods need more in the app:
| Method | Also needs |
|---|---|
The GoogleSignIn package, and its reversed client ID URL scheme |
|
| Apple | The Sign in with Apple capability (com.apple.developer.applesignin) |
The FacebookLogin package and its Info.plist keys (Social providers) |
|
| Phone, web providers (Microsoft, GitHub...) | A callback URL scheme (Phone) |
| Shared keychain | The Keychain Sharing capability |
| Multi-factor | Identity Platform enabled on the project |
App configuration¶
What the app's build needs for this product. To combine several products, list
them all in one products; see App configuration.
[[tool.kivy.ios.include_files]]
dest = "."
sources = ["GoogleService-Info.plist"]
[tool.kivy.ios.native.swift_packages.Firebase]
url = "https://github.com/firebase/firebase-ios-sdk.git"
requirement = { from = "13.1.1" }
products = ["FirebaseAuth"]
[tool.kivy.ios.xcode.build_settings]
OTHER_LDFLAGS = "$(inherited) -ObjC"
# phone and web sign-in (Microsoft, GitHub, OIDC...): a callback URL scheme,
# the REVERSED_CLIENT_ID, or "app-" + GOOGLE_APP_ID with "-" for ":"
[[tool.kivy.ios.info_plist.CFBundleURLTypes]]
CFBundleTypeRole = "Editor"
CFBundleURLSchemes = ["app-1-1234567890-ios-0123456789abcdef"]
# Google Sign-In (pyios_firebase.auth.google)
[tool.kivy.ios.native.swift_packages.GoogleSignIn-iOS]
url = "https://github.com/google/GoogleSignIn-iOS"
requirement = { from = "10.1.0" }
products = ["GoogleSignIn"]
[[tool.kivy.ios.info_plist.CFBundleURLTypes]]
CFBundleTypeRole = "Editor"
# the REVERSED_CLIENT_ID
CFBundleURLSchemes = ["com.googleusercontent.apps.1234567890-abcdef"]
# Facebook Login (pyios_firebase.auth.facebook)
[tool.kivy.ios.native.swift_packages.facebook-ios-sdk]
url = "https://github.com/facebook/facebook-ios-sdk.git"
requirement = { from = "19.0.1" }
products = ["FacebookLogin"]
[tool.kivy.ios.info_plist]
FacebookAppID = "1234567890"
FacebookClientToken = "your-client-token"
FacebookDisplayName = "My App"
LSApplicationQueriesSchemes = ["fbapi", "fb-messenger-share-api"]
[[tool.kivy.ios.info_plist.CFBundleURLTypes]]
CFBundleTypeRole = "Editor"
# fb + FacebookAppID
CFBundleURLSchemes = ["fb1234567890"]
# Sign in with Apple, Game Center, a shared keychain
[tool.kivy.ios.entitlements]
"com.apple.developer.applesignin" = ["Default"]
"com.apple.developer.game-center" = true
"keychain-access-groups" = ["$(AppIdentifierPrefix)com.example.shared"]
- File > Add Package Dependencies...,
https://github.com/firebase/firebase-ios-sdk.git, and pickFirebaseAuth. - Build Settings > Other Linker Flags: add
-ObjC. - Add
GoogleService-Info.plistto the app target. - Info > URL Types: add the callback scheme (the
REVERSED_CLIENT_ID, orapp-+GOOGLE_APP_IDwith-for:). - Google: add the
GoogleSignIn-iOSpackage (https://github.com/google/GoogleSignIn-iOS), and itsREVERSED_CLIENT_IDas a URL scheme. - Facebook: add the
facebook-ios-sdkpackage (productFacebookLogin); in Info,FacebookAppID,FacebookClientToken,FacebookDisplayName,LSApplicationQueriesSchemes, and the URL schemefb<APP_ID>. - Signing & Capabilities: Sign in with Apple, Game Center, Keychain Sharing, for the methods you use.
Note
Keep only the parts for the sign-in methods you use: email, anonymous and custom tokens need nothing beyond FirebaseAuth.
Note
Google Sign-In's REVERSED_CLIENT_ID is in GoogleService-Info.plist once the Google provider is enabled (download the file again after enabling it).
Guides¶
- Email and password: accounts, password reset, verification, email links.
- Social providers: Google, Apple, Facebook, Microsoft, GitHub, OIDC, SAML, Game Center.
- Phone number: SMS codes, testing numbers.
- Anonymous and custom: guests who sign up later, your own auth system.
- Multi-factor: SMS and authenticator-app second factors.
- Users and accounts: profiles, linking, tokens for your backend, shared keychain, deleting.
Who is signed in¶
listener = auth.add_state_did_change_listener(on_user) # runs now, then on each change
...
listener.remove()
The state listener is the reliable way to know: auth.current_user gives
the user at once, but it can be None for a moment at app start while
Firebase restores the saved user from the keychain.
| Listener | Called when |
|---|---|
add_state_did_change_listener(callback) |
A user signs in or out |
add_id_token_did_change_listener(callback) |
The same, and every time the ID token is refreshed (about hourly) |
The user stays signed in across launches (in the keychain) until you call:
The User¶
| Property | |
|---|---|
uid |
The user's ID, the same for every provider linked to the account |
email, phone_number, display_name, photo_url |
From the providers, or set by you |
is_email_verified, is_anonymous |
|
provider_data |
One UserInfo per linked provider (provider_id, uid, email...) |
metadata |
creation_date, last_sign_in_date (UTC datetime) |
multi_factor |
The enrolled second factors (Multi-factor) |
tenant_id |
The Identity Platform tenant, if any |
The user's data is cached: call user.reload(callback) to read the latest
(after the user verified their email in a browser, for example).
Sign-in results¶
Every sign-in callback gets (result, error). result is an
AuthDataResult:
| Field | |
|---|---|
result.user |
The signed-in User |
result.additional_user_info.is_new_user |
True on the first sign-in: create the user's profile document then |
result.additional_user_info.provider_id |
"password", "google.com", "apple.com"... |
result.additional_user_info.profile |
What the provider sent about the user (a dict) |
result.credential |
The provider's credential (OAuth tokens), when there is one |
def on_signed_in(result, error):
if error is not None:
return show_error(error)
info = result.additional_user_info
if info is not None and info.is_new_user:
db.document_with_path(f"users/{result.user.uid}").set_data({"created": datetime.now(UTC)})
Errors¶
Errors are AuthErrors: a FirebaseError with name (the AuthErrorCode
name), and more keys for some codes (Errors).
AuthErrorCode |
Means | Do |
|---|---|---|
INVALID_CREDENTIAL |
Wrong email or password (with email enumeration protection, both look the same) | Ask again |
EMAIL_ALREADY_IN_USE |
An account has that email | Offer to sign in |
WEAK_PASSWORD |
Under 6 characters, or the project's password policy | Ask for a stronger one |
INVALID_EMAIL |
Not an email address | |
USER_DISABLED |
Disabled in the console | |
TOO_MANY_REQUESTS |
Too many attempts from this device | Wait |
NETWORK_ERROR |
No connection | Retry |
REQUIRES_RECENT_LOGIN |
A sensitive change (password, email, delete) after an old sign-in | Re-authenticate, then retry |
ACCOUNT_EXISTS_WITH_DIFFERENT_CREDENTIAL |
The email has an account with another provider | Sign in with that one, then link (error.email, error.updated_credential) |
CREDENTIAL_ALREADY_IN_USE |
Linking a credential another account uses | error.updated_credential signs in to that account |
SECOND_FACTOR_REQUIRED |
The account has multi-factor | error.resolver (Multi-factor) |
OPERATION_NOT_ALLOWED |
The provider is not enabled in the console | |
KEYCHAIN_ERROR |
The keychain is not reachable (Keychain Sharing set up wrong) |
error.cancelled is True when the user closed a Google, Apple or web
sign-in sheet: that is not a failure to report.
Language¶
Emails, SMS and the reCAPTCHA page use the project's language. Change it:
Use the local emulator¶
The emulator signs anything in without email or SMS: its REST API lists the codes it would have sent, so tests can finish every flow:
curl "http://127.0.0.1:9099/emulator/v1/projects/demo-my-app/oobCodes" # email links
curl "http://127.0.0.1:9099/emulator/v1/projects/demo-my-app/verificationCodes" # SMS codes
It also turns app verification off, so phone sign-in works without APNs or reCAPTCHA. The Auth emulator supports SMS second factors, but not TOTP.
Firebase's iOS guide, page by page¶
| Guide page | In pyios-firebase |
|---|---|
| Sign in with a pre-built UI | Not available: FirebaseUI is SwiftUI-only (unreachable from Rubicon), or CocoaPods-only for UIKit. Build the screens with your UI toolkit |
| Get Started, Manage Users | Auth, User (Users and accounts) |
| Password Authentication | Email and password |
| Email Link Authentication | Email links |
| Sign in with Google / Apple / Facebook | Social providers |
| Twitter, GitHub, Microsoft, Yahoo, OpenID Connect, SAML | Web providers |
| Game Center | Game Center |
| Phone Number | Phone number |
| Custom Auth System, Anonymous | Anonymous and custom |
| Cross-app auth with shared Keychain | Shared keychain |
| Link Multiple Auth Providers | Link providers |
| SMS / TOTP Multi-factor | Multi-factor |
| Passing State in Email Actions | Passing state |
| Handle Errors | Errors |