App Check reference¶
At a glance¶
- Providers (before
core.configure()):use_debug_provider(),use_device_check_provider(),use_app_attest_provider(),use_recaptcha_provider(site_key),use_custom_provider(provider);running_in_simulator();initialize_debug_appcheck()(0.1 name) AppCheckProvider(get_token(callback),get_limited_use_token(callback)),AppCheckToken(token, expiration_date)AppCheck.app_check():token(cb, force_refresh),limited_use_token(cb),add_token_listener(listener)→AppCheckTokenListener,is_token_auto_refresh_enabled,debug_token()AppCheckErrorCode,DEBUG_TOKEN_ENVIRONMENT_VARIABLE
pyios_firebase.app_check¶
Firebase App Check: prove requests come from your real app.
Choose a provider before core.configure()::
from pyios_firebase import app_check, core
if app_check.running_in_simulator():
app_check.use_debug_provider() # register the debug token in the console
else:
app_check.use_app_attest_provider() # or use_device_check_provider()
core.configure()
Firestore, Functions, Storage, Auth and the other Firebase SDKs then attach App
Check tokens by themselves. For your own backend, get a token with
AppCheck.app_check().token(...).
Needs the FirebaseAppCheck framework. App Attest also needs the App Attest
capability (com.apple.developer.devicecheck.appattest-environment).
Classes:
| Name | Description |
|---|---|
AppCheckErrorCode |
The |
AppCheckToken |
An App Check token. |
AppCheckProvider |
A custom App Check provider, written in Python: for example tokens from |
AppCheckTokenListener |
Given back by |
AppCheck |
App Check for the default Firebase app. Get it with |
Functions:
| Name | Description |
|---|---|
running_in_simulator |
True in the iOS Simulator, where App Attest and DeviceCheck do not work |
use_debug_provider |
Use the debug provider: for the Simulator, development and CI. |
initialize_debug_appcheck |
The 0.1 name of |
use_device_check_provider |
Use Apple's DeviceCheck (the default provider). Works on real devices |
use_app_attest_provider |
Use Apple's App Attest: the strongest attestation, on real devices with |
use_recaptcha_provider |
Use reCAPTCHA Enterprise. Needs the reCAPTCHA Enterprise SDK in the app. |
use_custom_provider |
Use a custom provider written in Python. |
Attributes:
| Name | Type | Description |
|---|---|---|
APP_CHECK_ERROR_DOMAIN |
Final
|
The |
DEBUG_TOKEN_ENVIRONMENT_VARIABLE |
Final
|
Set it (for example in CI) to make the debug provider use that token |
TokenCallback |
|
APP_CHECK_ERROR_DOMAIN
module-attribute
¶
The error.domain of App Check errors.
DEBUG_TOKEN_ENVIRONMENT_VARIABLE
module-attribute
¶
Set it (for example in CI) to make the debug provider use that token
instead of a random one. AppCheckDebugToken also works.
TokenCallback
module-attribute
¶
TokenCallback = Callable[
[AppCheckToken | None, str | None], None
]
(token, None) or (None, error_message).
AppCheckErrorCode
¶
The error.code values of App Check errors (FIRAppCheckErrorCode).
Attributes:
| Name | Type | Description |
|---|---|---|
SERVER_UNREACHABLE |
Final
|
No network, or the App Check server did not answer. |
INVALID_CONFIGURATION |
Final
|
The provider or the Firebase project is not set up right. |
KEYCHAIN |
Final
|
The keychain could not store the token. |
UNSUPPORTED |
Final
|
The provider does not work here (for example App Attest in the Simulator). |
SERVER_UNREACHABLE
class-attribute
instance-attribute
¶
No network, or the App Check server did not answer.
INVALID_CONFIGURATION
class-attribute
instance-attribute
¶
The provider or the Firebase project is not set up right.
KEYCHAIN
class-attribute
instance-attribute
¶
The keychain could not store the token.
UNSUPPORTED
class-attribute
instance-attribute
¶
The provider does not work here (for example App Attest in the Simulator).
AppCheckToken
dataclass
¶
An App Check token.
Methods:
| Name | Description |
|---|---|
from_native |
Copy a native |
to_native |
Make the native |
Attributes:
| Name | Type | Description |
|---|---|---|
token |
str
|
The token: send it in the |
expiration_date |
datetime
|
When it expires (UTC). |
token
instance-attribute
¶
The token: send it in the X-Firebase-AppCheck header to your backend.
from_native
classmethod
¶
from_native(native: ObjCObject) -> AppCheckToken
Copy a native FIRAppCheckToken.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
native
|
ObjCObject
|
the |
required |
AppCheckProvider
¶
Bases: ABC
A custom App Check provider, written in Python: for example tokens from
your own attestation service. Pass it to use_custom_provider.
::
class MyProvider(AppCheckProvider):
def get_token(self, callback):
my_service.fetch(lambda token, expires: callback(AppCheckToken(token, expires), None))
Firebase may call these methods on a background thread.
Methods:
| Name | Description |
|---|---|
get_token |
Make a token, then call |
get_limited_use_token |
Make a single-use token (for replay protection). By default, the |
get_token
abstractmethod
¶
get_token(callback: TokenCallback) -> None
Make a token, then call callback exactly once.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
callback
|
TokenCallback
|
call it with |
required |
get_limited_use_token
¶
get_limited_use_token(callback: TokenCallback) -> None
Make a single-use token (for replay protection). By default, the
same as get_token.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
callback
|
TokenCallback
|
call it with |
required |
PyAppCheckProviderBridge
¶
Bases: NSObject
Lets Firebase call a Python AppCheckProvider.
Rubicon reads these methods' annotations to build their Objective-C signatures: parameters must be annotated with ctypes types.
Methods:
| Name | Description |
|---|---|
getTokenWithCompletion_ |
Firebase asks for a token. |
getLimitedUseTokenWithCompletion_ |
Firebase asks for a limited-use token. |
PyAppCheckProviderFactory
¶
Bases: NSObject
Lets Firebase ask Python for a provider for each Firebase app.
Methods:
| Name | Description |
|---|---|
createProviderWithApp_ |
Firebase asks for the provider of |
createProviderWithApp_
¶
Firebase asks for the provider of app.
AppCheckTokenListener
¶
AppCheckTokenListener(
observer: ObjCObject, release: Callable[[], None]
)
Given back by AppCheck.add_token_listener. Call remove() to stop.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
observer
|
ObjCObject
|
the native |
required |
release
|
Callable[[], None]
|
releases the listener's callback block. |
required |
Methods:
| Name | Description |
|---|---|
remove |
Stop the updates. Safe to call more than once. |
AppCheck
¶
AppCheck(native: ObjCObject)
App Check for the default Firebase app. Get it with AppCheck.app_check().
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
native
|
ObjCObject
|
the native |
required |
Methods:
| Name | Description |
|---|---|
app_check |
The shared instance (after |
token |
Get an App Check token, for example to call your own backend. |
limited_use_token |
Get a limited-use (single-use) token, for backends with replay |
add_token_listener |
Listen for new App Check tokens (each refresh), on the main thread. |
debug_token |
The debug provider's token: the |
Attributes:
| Name | Type | Description |
|---|---|---|
native |
ObjCObject
|
The |
is_token_auto_refresh_enabled |
bool
|
Whether App Check refreshes the token before it expires (the default |
is_token_auto_refresh_enabled
property
writable
¶
Whether App Check refreshes the token before it expires (the default
comes from FirebaseAppCheckTokenAutoRefreshEnabled in Info.plist,
else Firebase's data collection setting).
token
¶
token(
callback: Callable[
[AppCheckToken | None, FirebaseError | None], None
],
force_refresh: bool = False,
) -> None
Get an App Check token, for example to call your own backend.
The token is cached, also across app launches, until it is about to
expire: the provider is only asked again then, or with force_refresh.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
callback
|
Callable[[AppCheckToken | None, FirebaseError | None], None]
|
gets |
required |
force_refresh
|
bool
|
get a new token even if the cached one is valid. |
False
|
limited_use_token
¶
limited_use_token(
callback: Callable[
[AppCheckToken | None, FirebaseError | None], None
],
) -> None
Get a limited-use (single-use) token, for backends with replay
protection. It is not cached and does not affect token.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
callback
|
Callable[[AppCheckToken | None, FirebaseError | None], None]
|
gets |
required |
add_token_listener
¶
add_token_listener(
listener: Callable[[str], None],
) -> AppCheckTokenListener
Listen for new App Check tokens (each refresh), on the main thread.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
listener
|
Callable[[str], None]
|
gets the new token string. |
required |
Returns:
| Type | Description |
|---|---|
AppCheckTokenListener
|
An |
debug_token
staticmethod
¶
The debug provider's token: the DEBUG_TOKEN_ENVIRONMENT_VARIABLE
token if set, else this device's local one. Register it in the Firebase
console. Works whichever provider is in use (after core.configure()).
Returns:
| Type | Description |
|---|---|
str
|
The token. |
running_in_simulator
¶
True in the iOS Simulator, where App Attest and DeviceCheck do not work (use the debug provider there).
use_debug_provider
¶
Use the debug provider: for the Simulator, development and CI.
On first run it prints Firebase App Check debug token: '...' in the
Xcode console; add that token in the Firebase console (App Check, your app,
Manage debug tokens). In CI, set DEBUG_TOKEN_ENVIRONMENT_VARIABLE to a
registered token. Never ship it: anyone with the token passes App Check.
Raises:
| Type | Description |
|---|---|
RuntimeError
|
|
use_device_check_provider
¶
Use Apple's DeviceCheck (the default provider). Works on real devices with iOS 11+; not in the Simulator.
Raises:
| Type | Description |
|---|---|
RuntimeError
|
|
use_app_attest_provider
¶
Use Apple's App Attest: the strongest attestation, on real devices with iOS 14+. Needs the App Attest capability; not in the Simulator.
Raises:
| Type | Description |
|---|---|
RuntimeError
|
|
use_recaptcha_provider
¶
Use reCAPTCHA Enterprise. Needs the reCAPTCHA Enterprise SDK in the app.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
site_key
|
str
|
the reCAPTCHA Enterprise site key for iOS. |
required |
Raises:
| Type | Description |
|---|---|
RuntimeError
|
|
use_custom_provider
¶
use_custom_provider(
provider: AppCheckProvider
| Callable[[ObjCObject], AppCheckProvider],
) -> None
Use a custom provider written in Python.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
provider
|
AppCheckProvider | Callable[[ObjCObject], AppCheckProvider]
|
an |
required |
Raises:
| Type | Description |
|---|---|
RuntimeError
|
|