0
# Authentication
1
2
Comprehensive Firebase Authentication management providing server-side user authentication, custom token generation, ID token verification, user management operations, and multi-tenant authentication capabilities.
3
4
## Capabilities
5
6
### Token Management
7
8
Generate and verify Firebase authentication tokens for secure user authentication flows.
9
10
```python { .api }
11
def create_custom_token(uid, developer_claims=None, app=None):
12
"""
13
Create a custom token for the given UID.
14
15
Args:
16
uid: The UID to use for the custom token
17
developer_claims: Optional developer claims dict to include in the token
18
app: Firebase app instance (optional)
19
20
Returns:
21
bytes: A custom token for the given UID
22
23
Raises:
24
ValueError: If the UID is invalid or developer_claims are malformed
25
"""
26
27
def verify_id_token(id_token, app=None, check_revoked=False, clock_skew_seconds=0):
28
"""
29
Verify a Firebase ID token.
30
31
Args:
32
id_token: A Firebase ID token string
33
app: Firebase app instance (optional)
34
check_revoked: Whether to check if the token has been revoked (optional)
35
clock_skew_seconds: Allowed clock skew in seconds (optional)
36
37
Returns:
38
dict: Decoded token claims
39
40
Raises:
41
ExpiredIdTokenError: If the token has expired
42
InvalidIdTokenError: If the token is invalid
43
RevokedIdTokenError: If the token has been revoked (when check_revoked=True)
44
"""
45
46
def revoke_refresh_tokens(uid, app=None):
47
"""
48
Revoke all refresh tokens for a user.
49
50
Args:
51
uid: The UID of the user whose tokens should be revoked
52
app: Firebase app instance (optional)
53
54
Raises:
55
UserNotFoundError: If no user record exists for the given UID
56
"""
57
```
58
59
### Session Cookies
60
61
Manage Firebase session cookies for web applications requiring server-side session management.
62
63
```python { .api }
64
def create_session_cookie(id_token, expires_in, app=None):
65
"""
66
Create a session cookie from an ID token.
67
68
Args:
69
id_token: A Firebase ID token
70
expires_in: Session duration as datetime.timedelta
71
app: Firebase app instance (optional)
72
73
Returns:
74
bytes: A session cookie
75
76
Raises:
77
InvalidIdTokenError: If the ID token is invalid
78
"""
79
80
def verify_session_cookie(session_cookie, check_revoked=False, app=None, clock_skew_seconds=0):
81
"""
82
Verify a Firebase session cookie.
83
84
Args:
85
session_cookie: A Firebase session cookie string
86
check_revoked: Whether to check if the underlying token has been revoked
87
app: Firebase app instance (optional)
88
clock_skew_seconds: Allowed clock skew in seconds (optional)
89
90
Returns:
91
dict: Decoded session claims
92
93
Raises:
94
ExpiredSessionCookieError: If the session cookie has expired
95
InvalidSessionCookieError: If the session cookie is invalid
96
RevokedSessionCookieError: If revoked (when check_revoked=True)
97
"""
98
```
99
100
### User Retrieval
101
102
Retrieve user information by various identifiers including UID, email, and phone number.
103
104
```python { .api }
105
def get_user(uid, app=None):
106
"""
107
Get a user by UID.
108
109
Args:
110
uid: A user UID string
111
app: Firebase app instance (optional)
112
113
Returns:
114
UserRecord: A UserRecord instance
115
116
Raises:
117
UserNotFoundError: If no user record exists for the given UID
118
"""
119
120
def get_user_by_email(email, app=None):
121
"""
122
Get a user by email address.
123
124
Args:
125
email: A user email address string
126
app: Firebase app instance (optional)
127
128
Returns:
129
UserRecord: A UserRecord instance
130
131
Raises:
132
UserNotFoundError: If no user record exists for the given email
133
"""
134
135
def get_user_by_phone_number(phone_number, app=None):
136
"""
137
Get a user by phone number.
138
139
Args:
140
phone_number: A user phone number string
141
app: Firebase app instance (optional)
142
143
Returns:
144
UserRecord: A UserRecord instance
145
146
Raises:
147
UserNotFoundError: If no user record exists for the given phone number
148
"""
149
150
def get_users(identifiers, app=None):
151
"""
152
Get users by multiple identifiers.
153
154
Args:
155
identifiers: List of UserIdentifier instances
156
app: Firebase app instance (optional)
157
158
Returns:
159
GetUsersResult: Result containing found users and not found identifiers
160
"""
161
```
162
163
### User Management
164
165
Create, update, and delete user accounts with comprehensive user profile management.
166
167
```python { .api }
168
def create_user(**kwargs):
169
"""
170
Create a new user.
171
172
Args:
173
uid: The UID for the new user (optional)
174
email: The email address for the new user (optional)
175
email_verified: Whether the email is verified (optional)
176
phone_number: The phone number for the new user (optional)
177
password: The password for the new user (optional)
178
display_name: The display name for the new user (optional)
179
photo_url: The photo URL for the new user (optional)
180
disabled: Whether the user is disabled (optional)
181
182
Returns:
183
UserRecord: A UserRecord instance for the new user
184
185
Raises:
186
EmailAlreadyExistsError: If a user with the email already exists
187
PhoneNumberAlreadyExistsError: If a user with the phone number already exists
188
"""
189
190
def update_user(uid, **kwargs):
191
"""
192
Update an existing user.
193
194
Args:
195
uid: The UID of the user to update
196
email: Updated email address (optional)
197
email_verified: Updated email verification status (optional)
198
phone_number: Updated phone number (optional)
199
password: Updated password (optional)
200
display_name: Updated display name (optional)
201
photo_url: Updated photo URL (optional)
202
disabled: Updated disabled status (optional)
203
custom_claims: Updated custom claims dict (optional)
204
205
Returns:
206
UserRecord: Updated UserRecord instance
207
208
Raises:
209
UserNotFoundError: If no user record exists for the given UID
210
EmailAlreadyExistsError: If email is already in use by another user
211
"""
212
213
def delete_user(uid, app=None):
214
"""
215
Delete a user.
216
217
Args:
218
uid: The UID of the user to delete
219
app: Firebase app instance (optional)
220
221
Raises:
222
UserNotFoundError: If no user record exists for the given UID
223
"""
224
225
def delete_users(uids, app=None):
226
"""
227
Delete multiple users.
228
229
Args:
230
uids: List of user UIDs to delete
231
app: Firebase app instance (optional)
232
233
Returns:
234
DeleteUsersResult: Result with success/failure counts and errors
235
"""
236
```
237
238
### User Listing
239
240
List and paginate through all users in the Firebase project.
241
242
```python { .api }
243
def list_users(page_token=None, max_results=1000, app=None):
244
"""
245
List users in the Firebase project.
246
247
Args:
248
page_token: Token for paginating results (optional)
249
max_results: Maximum number of users to return (optional, max 1000)
250
app: Firebase app instance (optional)
251
252
Returns:
253
ListUsersPage: Page of user records with pagination info
254
"""
255
```
256
257
### Custom Claims
258
259
Manage custom user claims for role-based access control and user permissions.
260
261
```python { .api }
262
def set_custom_user_claims(uid, custom_claims, app=None):
263
"""
264
Set custom claims for a user.
265
266
Args:
267
uid: The UID of the user
268
custom_claims: Dict of custom claims to set (max 1000 chars serialized)
269
app: Firebase app instance (optional)
270
271
Raises:
272
UserNotFoundError: If no user record exists for the given UID
273
ValueError: If custom_claims exceed size limits or contain reserved keys
274
"""
275
```
276
277
### Email Actions
278
279
Generate action links for password reset, email verification, and sign-in flows.
280
281
```python { .api }
282
def generate_password_reset_link(email, action_code_settings=None, app=None):
283
"""
284
Generate a password reset link for the user.
285
286
Args:
287
email: The email address of the user
288
action_code_settings: Optional ActionCodeSettings instance
289
app: Firebase app instance (optional)
290
291
Returns:
292
str: Password reset link URL
293
294
Raises:
295
UserNotFoundError: If no user exists with the given email
296
"""
297
298
def generate_email_verification_link(email, action_code_settings=None, app=None):
299
"""
300
Generate an email verification link.
301
302
Args:
303
email: The email address to verify
304
action_code_settings: Optional ActionCodeSettings instance
305
app: Firebase app instance (optional)
306
307
Returns:
308
str: Email verification link URL
309
"""
310
311
def generate_sign_in_with_email_link(email, action_code_settings, app=None):
312
"""
313
Generate a sign-in with email link.
314
315
Args:
316
email: The email address for sign-in
317
action_code_settings: ActionCodeSettings instance (required)
318
app: Firebase app instance (optional)
319
320
Returns:
321
str: Sign-in with email link URL
322
"""
323
```
324
325
### User Import
326
327
Bulk import users from external systems with password hashing options.
328
329
```python { .api }
330
def import_users(users, hash_alg=None, app=None):
331
"""
332
Import multiple users into Firebase.
333
334
Args:
335
users: List of ImportUserRecord instances
336
hash_alg: Optional UserImportHash for password hashing
337
app: Firebase app instance (optional)
338
339
Returns:
340
UserImportResult: Import operation results with success/failure counts
341
"""
342
```
343
344
### OIDC Provider Configuration
345
346
Manage OpenID Connect (OIDC) provider configurations for Identity Platform integration.
347
348
```python { .api }
349
def get_oidc_provider_config(provider_id, app=None):
350
"""
351
Get an OIDC provider configuration by ID.
352
353
Args:
354
provider_id: Provider ID string with 'oidc.' prefix
355
app: Firebase app instance (optional)
356
357
Returns:
358
OIDCProviderConfig: OIDC provider configuration instance
359
360
Raises:
361
ValueError: If provider ID is invalid or missing 'oidc.' prefix
362
ConfigurationNotFoundError: If provider config not found
363
"""
364
365
def create_oidc_provider_config(
366
provider_id, client_id, issuer, display_name=None, enabled=None,
367
client_secret=None, id_token_response_type=None, code_response_type=None, app=None):
368
"""
369
Create a new OIDC provider configuration.
370
371
Args:
372
provider_id: Provider ID string with 'oidc.' prefix
373
client_id: Client ID of the OIDC provider
374
issuer: Issuer URL of the OIDC provider
375
display_name: Display name for the provider (optional)
376
enabled: Whether the provider is enabled (optional)
377
client_secret: Client secret for code flow (optional)
378
id_token_response_type: Enable ID token response flow (optional)
379
code_response_type: Enable code response flow (optional)
380
app: Firebase app instance (optional)
381
382
Returns:
383
OIDCProviderConfig: The newly created OIDC provider config
384
"""
385
386
def update_oidc_provider_config(
387
provider_id, client_id=None, issuer=None, display_name=None, enabled=None,
388
client_secret=None, id_token_response_type=None, code_response_type=None, app=None):
389
"""
390
Update an existing OIDC provider configuration.
391
392
Args:
393
provider_id: Provider ID string with 'oidc.' prefix
394
client_id: Updated client ID (optional)
395
issuer: Updated issuer URL (optional)
396
display_name: Updated display name (optional)
397
enabled: Updated enabled status (optional)
398
client_secret: Updated client secret (optional)
399
id_token_response_type: Updated ID token response flow setting (optional)
400
code_response_type: Updated code response flow setting (optional)
401
app: Firebase app instance (optional)
402
403
Returns:
404
OIDCProviderConfig: The updated OIDC provider config
405
"""
406
407
def delete_oidc_provider_config(provider_id, app=None):
408
"""
409
Delete an OIDC provider configuration.
410
411
Args:
412
provider_id: Provider ID string with 'oidc.' prefix
413
app: Firebase app instance (optional)
414
415
Raises:
416
ValueError: If provider ID is invalid or missing 'oidc.' prefix
417
ConfigurationNotFoundError: If provider config not found
418
"""
419
420
def list_oidc_provider_configs(page_token=None, max_results=100, app=None):
421
"""
422
List OIDC provider configurations with pagination.
423
424
Args:
425
page_token: Token for pagination (optional)
426
max_results: Maximum number of results per page (optional, max 100)
427
app: Firebase app instance (optional)
428
429
Returns:
430
ListProviderConfigsPage: Page of OIDC provider configurations
431
"""
432
```
433
434
### SAML Provider Configuration
435
436
Manage SAML provider configurations for Identity Platform integration.
437
438
```python { .api }
439
def get_saml_provider_config(provider_id, app=None):
440
"""
441
Get a SAML provider configuration by ID.
442
443
Args:
444
provider_id: Provider ID string with 'saml.' prefix
445
app: Firebase app instance (optional)
446
447
Returns:
448
SAMLProviderConfig: SAML provider configuration instance
449
450
Raises:
451
ValueError: If provider ID is invalid or missing 'saml.' prefix
452
ConfigurationNotFoundError: If provider config not found
453
"""
454
455
def create_saml_provider_config(
456
provider_id, idp_entity_id, sso_url, x509_certificates, rp_entity_id, callback_url,
457
display_name=None, enabled=None, app=None):
458
"""
459
Create a new SAML provider configuration.
460
461
Args:
462
provider_id: Provider ID string with 'saml.' prefix
463
idp_entity_id: SAML IdP entity identifier
464
sso_url: SAML IdP SSO URL
465
x509_certificates: List of SAML IdP X.509 certificates
466
rp_entity_id: SAML relying party entity ID
467
callback_url: Callback URL string
468
display_name: Display name for the provider (optional)
469
enabled: Whether the provider is enabled (optional)
470
app: Firebase app instance (optional)
471
472
Returns:
473
SAMLProviderConfig: The newly created SAML provider config
474
"""
475
476
def update_saml_provider_config(
477
provider_id, idp_entity_id=None, sso_url=None, x509_certificates=None,
478
rp_entity_id=None, callback_url=None, display_name=None, enabled=None, app=None):
479
"""
480
Update an existing SAML provider configuration.
481
482
Args:
483
provider_id: Provider ID string with 'saml.' prefix
484
idp_entity_id: Updated SAML IdP entity identifier (optional)
485
sso_url: Updated SAML IdP SSO URL (optional)
486
x509_certificates: Updated list of X.509 certificates (optional)
487
rp_entity_id: Updated relying party entity ID (optional)
488
callback_url: Updated callback URL (optional)
489
display_name: Updated display name (optional)
490
enabled: Updated enabled status (optional)
491
app: Firebase app instance (optional)
492
493
Returns:
494
SAMLProviderConfig: The updated SAML provider config
495
"""
496
497
def delete_saml_provider_config(provider_id, app=None):
498
"""
499
Delete a SAML provider configuration.
500
501
Args:
502
provider_id: Provider ID string with 'saml.' prefix
503
app: Firebase app instance (optional)
504
505
Raises:
506
ValueError: If provider ID is invalid or missing 'saml.' prefix
507
ConfigurationNotFoundError: If provider config not found
508
"""
509
510
def list_saml_provider_configs(page_token=None, max_results=100, app=None):
511
"""
512
List SAML provider configurations with pagination.
513
514
Args:
515
page_token: Token for pagination (optional)
516
max_results: Maximum number of results per page (optional, max 100)
517
app: Firebase app instance (optional)
518
519
Returns:
520
ListProviderConfigsPage: Page of SAML provider configurations
521
"""
522
```
523
524
## Types
525
526
```python { .api }
527
class UserRecord:
528
"""Firebase user record."""
529
530
@property
531
def uid(self):
532
"""The user's UID."""
533
534
@property
535
def email(self):
536
"""The user's email address."""
537
538
@property
539
def email_verified(self):
540
"""Whether the user's email is verified."""
541
542
@property
543
def phone_number(self):
544
"""The user's phone number."""
545
546
@property
547
def display_name(self):
548
"""The user's display name."""
549
550
@property
551
def photo_url(self):
552
"""The user's photo URL."""
553
554
@property
555
def disabled(self):
556
"""Whether the user account is disabled."""
557
558
@property
559
def user_metadata(self):
560
"""User metadata including creation and last sign-in times."""
561
562
@property
563
def custom_claims(self):
564
"""Custom claims set for the user."""
565
566
@property
567
def provider_data(self):
568
"""List of provider-specific user info."""
569
570
class UserMetadata:
571
"""User metadata information."""
572
573
@property
574
def creation_timestamp(self):
575
"""User creation timestamp."""
576
577
@property
578
def last_sign_in_timestamp(self):
579
"""Last sign-in timestamp."""
580
581
@property
582
def last_refresh_timestamp(self):
583
"""Last token refresh timestamp."""
584
585
class UserInfo:
586
"""Provider-specific user information."""
587
588
@property
589
def uid(self):
590
"""Provider-specific user ID."""
591
592
@property
593
def display_name(self):
594
"""Display name."""
595
596
@property
597
def email(self):
598
"""Email address."""
599
600
@property
601
def phone_number(self):
602
"""Phone number."""
603
604
@property
605
def photo_url(self):
606
"""Photo URL."""
607
608
@property
609
def provider_id(self):
610
"""Provider ID."""
611
612
class GetUsersResult:
613
"""Result of get_users operation."""
614
615
@property
616
def users(self):
617
"""List of UserRecord instances that were found."""
618
619
@property
620
def not_found(self):
621
"""List of UserIdentifier instances that were not found."""
622
623
class DeleteUsersResult:
624
"""Result of delete_users operation."""
625
626
@property
627
def success_count(self):
628
"""Number of users successfully deleted."""
629
630
@property
631
def failure_count(self):
632
"""Number of users that failed to delete."""
633
634
@property
635
def errors(self):
636
"""List of ErrorInfo instances for failed deletions."""
637
638
class ListUsersPage:
639
"""Page of user records with pagination."""
640
641
@property
642
def users(self):
643
"""List of UserRecord instances in this page."""
644
645
@property
646
def next_page_token(self):
647
"""Token for the next page (None if no more pages)."""
648
649
@property
650
def has_next_page(self):
651
"""Whether there are more pages available."""
652
653
def get_next_page(self):
654
"""Get the next page of results."""
655
656
class ImportUserRecord:
657
"""User record for import operations."""
658
659
def __init__(self, uid, **kwargs):
660
"""
661
Initialize import user record.
662
663
Args:
664
uid: User UID
665
email: Email address (optional)
666
password_hash: Hashed password bytes (optional)
667
password_salt: Password salt bytes (optional)
668
custom_claims: Custom claims dict (optional)
669
provider_data: List of UserInfo instances (optional)
670
"""
671
672
class UserImportResult:
673
"""Result of user import operation."""
674
675
@property
676
def success_count(self):
677
"""Number of users successfully imported."""
678
679
@property
680
def failure_count(self):
681
"""Number of users that failed to import."""
682
683
@property
684
def errors(self):
685
"""List of ErrorInfo instances for failed imports."""
686
687
class ActionCodeSettings:
688
"""Settings for email action code generation."""
689
690
def __init__(self, url, handle_code_in_app=None, ios_bundle_id=None, android_package_name=None, dynamic_link_domain=None):
691
"""
692
Initialize action code settings.
693
694
Args:
695
url: The link the user is redirected to
696
handle_code_in_app: Whether to handle the code in the app
697
ios_bundle_id: iOS bundle ID for deep linking
698
android_package_name: Android package name for deep linking
699
dynamic_link_domain: Custom dynamic link domain
700
"""
701
702
class UserIdentifier:
703
"""Base class for user identifiers."""
704
705
class UidIdentifier(UserIdentifier):
706
"""User identifier by UID."""
707
708
def __init__(self, uid):
709
"""Initialize with UID."""
710
711
class EmailIdentifier(UserIdentifier):
712
"""User identifier by email."""
713
714
def __init__(self, email):
715
"""Initialize with email."""
716
717
class PhoneIdentifier(UserIdentifier):
718
"""User identifier by phone number."""
719
720
def __init__(self, phone_number):
721
"""Initialize with phone number."""
722
723
class ProviderIdentifier(UserIdentifier):
724
"""User identifier by provider."""
725
726
def __init__(self, provider_id, provider_uid):
727
"""Initialize with provider ID and UID."""
728
729
class ProviderConfig:
730
"""Base class for authentication provider configurations."""
731
732
@property
733
def provider_id(self):
734
"""The provider ID."""
735
736
@property
737
def display_name(self):
738
"""The display name of the provider."""
739
740
@property
741
def enabled(self):
742
"""Whether the provider is enabled."""
743
744
class OIDCProviderConfig(ProviderConfig):
745
"""OIDC authentication provider configuration."""
746
747
@property
748
def issuer(self):
749
"""The OIDC issuer URL."""
750
751
@property
752
def client_id(self):
753
"""The OIDC client ID."""
754
755
@property
756
def client_secret(self):
757
"""The OIDC client secret."""
758
759
@property
760
def id_token_response_type(self):
761
"""Whether ID token response type is enabled."""
762
763
@property
764
def code_response_type(self):
765
"""Whether code response type is enabled."""
766
767
class SAMLProviderConfig(ProviderConfig):
768
"""SAML authentication provider configuration."""
769
770
@property
771
def idp_entity_id(self):
772
"""The SAML IdP entity ID."""
773
774
@property
775
def sso_url(self):
776
"""The SAML IdP SSO URL."""
777
778
@property
779
def x509_certificates(self):
780
"""List of SAML IdP X.509 certificates."""
781
782
@property
783
def callback_url(self):
784
"""The callback URL."""
785
786
@property
787
def rp_entity_id(self):
788
"""The SAML relying party entity ID."""
789
790
class ListProviderConfigsPage:
791
"""Page of provider configurations with pagination."""
792
793
@property
794
def provider_configs(self):
795
"""List of provider configurations in this page."""
796
797
@property
798
def next_page_token(self):
799
"""Token for the next page (empty string if no more pages)."""
800
801
@property
802
def has_next_page(self):
803
"""Whether there are more pages available."""
804
805
def get_next_page(self):
806
"""Get the next page of results."""
807
808
def iterate_all(self):
809
"""Iterator for all provider configs starting from this page."""
810
```