App Check¶
App Check proves to Firebase (and to your own backend) that a request comes from your genuine app on a genuine device, not from a script that copied your API key. Firestore, the Realtime Database, Storage, Functions, Auth and Remote Config can then refuse requests without a valid token.
Installation¶
- Add the
FirebaseAppCheckSwift package product (Installation). - In the console, open App Check, register the iOS app with App Attest (and/or DeviceCheck).
- Choose the provider in the app, before
core.configure(). - Watch the metrics in the console, then turn enforcement on for each product once the traffic is verified.
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 = ["FirebaseAppCheck"]
[tool.kivy.ios.xcode.build_settings]
OTHER_LDFLAGS = "$(inherited) -ObjC"
# App Attest: "development" for debug builds,
# "production" for TestFlight and the App Store
[tool.kivy.ios.entitlements]
"com.apple.developer.devicecheck.appattest-environment" = "production"
# optional: stop refreshing tokens in the background
[tool.kivy.ios.info_plist]
FirebaseAppCheckTokenAutoRefreshEnabled = false
- File > Add Package Dependencies...,
https://github.com/firebase/firebase-ios-sdk.git, and pickFirebaseAppCheck. - Build Settings > Other Linker Flags: add
-ObjC. - Add
GoogleService-Info.plistto the app target. - Signing & Capabilities > + Capability > App Attest (for App Attest).
- Optional, in Info:
FirebaseAppCheckTokenAutoRefreshEnabled=NO.
Note
DeviceCheck and the debug provider need no entitlement. In CI, pass the debug token as the FIRAAppCheckDebugToken environment variable.
Choose a provider¶
from pyios_firebase import app_check, core
if app_check.running_in_simulator():
app_check.use_debug_provider() # the Simulator cannot attest
else:
app_check.use_app_attest_provider()
core.configure()
| Provider | Function | Works on | Needs |
|---|---|---|---|
| App Attest | use_app_attest_provider() |
Devices, iOS 14+ | The App Attest capability (com.apple.developer.devicecheck.appattest-environment) |
| DeviceCheck | use_device_check_provider() |
Devices | Your DeviceCheck key in the console |
| reCAPTCHA Enterprise | use_recaptcha_provider(site_key) |
Devices and the Simulator | The reCAPTCHA Enterprise SDK, a site key |
| Debug | use_debug_provider() |
The Simulator, CI, development devices | A debug token registered in the console |
| Custom | use_custom_provider(provider) |
Anywhere | Your own attestation service |
Setting a provider after core.configure() raises RuntimeError: Firebase
reads it only when the app is configured.
App Attest in production
App Attest has a development and a production environment, set by the
entitlement. TestFlight and App Store builds must use production.
The debug provider¶
For the Simulator and development builds:
- Run the app with
use_debug_provider(). - Copy the token from the console log:
Firebase App Check debug token: <token>(or readAppCheck.debug_token()in the app). - In the console: App Check > Apps > your app > Manage debug tokens, add it.
In CI, set the token yourself, so it is the same on every run: pass the
environment variable FIRAAppCheckDebugToken to the app (with
xcrun simctl launch, as SIMCTL_CHILD_FIRAAppCheckDebugToken=...).
Danger
Never ship the debug provider: anyone with the token passes App Check.
Tokens for your own backend¶
from pyios_firebase.app_check import AppCheck
def call_backend():
def on_token(token, error):
if error is None:
post(url, headers={"X-Firebase-AppCheck": token.token})
AppCheck.app_check().token(on_token)
Verify it on the server with the Admin SDK (firebase_admin.app_check.verify_token).
| Call | Gives |
|---|---|
token(callback, force_refresh=False) |
The cached token, or a new one when it expires |
limited_use_token(callback) |
A single-use token, for replay protection: the server consumes it |
add_token_listener(listener) |
Calls listener(token) on every refresh; .remove() stops |
Tokens are cached across launches: force_refresh=True asks the provider
for a new one. token.expiration_date is a UTC datetime.
A custom provider in Python¶
For your own attestation (a device-integrity service, a hardware key...):
from datetime import UTC, datetime, timedelta
from pyios_firebase.app_check import AppCheckProvider, AppCheckToken
class MyProvider(AppCheckProvider):
def get_token(self, callback):
def on_response(response, error):
if error is not None:
callback(None, str(error)) # a message: App Check reports it
return
expires = datetime.now(UTC) + timedelta(seconds=response["ttl"])
callback(AppCheckToken(response["token"], expires), None)
my_attestation_service.request_token(on_response)
# optional: by default, limited-use tokens come from get_token
def get_limited_use_token(self, callback):
...
app_check.use_custom_provider(MyProvider())
Your server makes the token: a JWT signed with a key you registered as a
custom provider in the console. callback must be called exactly once; if
get_token raises, App Check gets an error instead. To make one provider per
Firebase app, pass a factory: use_custom_provider(lambda app: MyProvider()).
Settings¶
FirebaseAppCheckTokenAutoRefreshEnabled = NO in Info.plist sets it at
build time.
Errors¶
AppCheckErrorCode |
Means |
|---|---|
SERVER_UNREACHABLE |
No network, or the App Check server is down |
INVALID_CONFIGURATION |
The app is not registered for this provider, or the debug token is unknown |
KEYCHAIN |
The keychain is not reachable |
UNSUPPORTED |
The provider does not work here (App Attest in the Simulator) |
UNKNOWN |
Anything else, including errors from a custom provider |
The emulators¶
The Firebase emulators do not check App Check tokens, so any provider works against them.