Skip to content

Commit 32487b0

Browse files
demolafdemolaf
authored
docs: update README to include prerequisites and initialization options (#199)
* docs: update README to include prerequisites and initialization options * updates * updates
1 parent 6c09bea commit 32487b0

1 file changed

Lines changed: 111 additions & 2 deletions

File tree

‎packages/dart_firebase_admin/README.md‎

Lines changed: 111 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,15 @@
22

33
## Table of Contents
44

5+
- [Prerequisites](#prerequisites)
56
- [Overview](#overview)
67
- [Installation](#installation)
7-
- [Initalization](#initalization)
8+
- [Add the Firebase Admin SDK to your server](#add-the-firebase-admin-sdk-to-your-server)
9+
- [Initialize the SDK](#initialize-the-sdk)
10+
- [Initialize the SDK in non-Google environments](#initialize-the-sdk-in-non-google-environments)
11+
- [Using Workload Identity Federation](#using-workload-identity-federation)
12+
- [Initialize multiple apps](#initialize-multiple-apps)
13+
- [Testing with gcloud end user credentials](#testing-with-gcloud-end-user-credentials)
814
- [Usage](#usage)
915
- [Authentication](#authentication)
1016
- [App Check](#app-check)
@@ -18,6 +24,10 @@
1824
- [Contributing](#contributing)
1925
- [License](#license)
2026

27+
## Prerequisites
28+
29+
Make sure that your server runs **Dart SDK 3.9 or higher**.
30+
2131
## Overview
2232

2333
[Firebase](https://firebase.google.com) provides the tools and infrastructure
@@ -42,7 +52,7 @@ To use the SDK in your application, `import` it from any Dart file:
4252
import 'package:dart_firebase_admin/dart_firebase_admin.dart';
4353
```
4454

45-
## Initalization
55+
## Add the Firebase Admin SDK to your server
4656

4757
### Initialize the SDK
4858

@@ -55,6 +65,17 @@ final app = FirebaseApp.initializeApp();
5565

5666
This will automatically initialize the SDK with [Google Application Default Credentials](https://cloud.google.com/docs/authentication/production#providing_credentials_to_your_application). Because default credentials lookup is fully automated in Google environments, with no need to supply environment variables or other configuration, this way of initializing the SDK is strongly recommended for applications running in Google environments such as Firebase App Hosting, Cloud Run, App Engine, and Cloud Functions for Firebase.
5767

68+
To optionally specify initialization options, use the `FIREBASE_CONFIG` environment variable. If the content begins with `{` it will be parsed as a JSON object, otherwise it is treated as a path to a JSON file containing the options:
69+
70+
```bash
71+
export FIREBASE_CONFIG='{"projectId":"my-project"}'
72+
```
73+
74+
```dart
75+
// Options are read automatically from FIREBASE_CONFIG
76+
final app = FirebaseApp.initializeApp();
77+
```
78+
5879
### Initialize the SDK in non-Google environments
5980

6081
If you are working in a non-Google server environment in which default credentials lookup can't be fully automated, you can initialize the SDK with an exported service account key file.
@@ -77,6 +98,94 @@ The following `Credential` constructors are available:
7798
- `Credential.fromServiceAccount(File)` — Loads credentials from a service account JSON file downloaded from the Firebase Console.
7899
- `Credential.fromServiceAccountParams({required String privateKey, required String email, required String projectId, String? clientId})` — Builds credentials from individual service account fields directly.
79100

101+
#### Using Workload Identity Federation
102+
103+
[Workload Identity Federation](https://cloud.google.com/iam/docs/workload-identity-federation) lets external workloads (such as GitHub Actions, AWS, or Azure) authenticate as a Google service account without a long-lived key file.
104+
105+
Once your WIF credential configuration file is generated, point `GOOGLE_APPLICATION_CREDENTIALS` to it:
106+
107+
```bash
108+
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/wif-credential-config.json"
109+
```
110+
111+
Then initialize the SDK with ADC, providing the impersonated service account email via `serviceAccountId`. This is required because WIF credential configs do not embed a `client_email` field, unlike service account key files:
112+
113+
```dart
114+
final app = FirebaseApp.initializeApp(
115+
options: AppOptions(
116+
credential: Credential.fromApplicationDefaultCredentials(
117+
serviceAccountId: 'my-service-account@my-project.iam.gserviceaccount.com',
118+
),
119+
projectId: 'my-project',
120+
),
121+
);
122+
```
123+
124+
### Initialize multiple apps
125+
126+
In most cases, you only have to initialize a single default app:
127+
128+
```dart
129+
// Initialize the default app
130+
final defaultApp = FirebaseApp.initializeApp();
131+
132+
print(defaultApp.name); // '[DEFAULT]'
133+
134+
// Access services from the default app
135+
final defaultAuth = defaultApp.auth();
136+
final defaultFirestore = defaultApp.firestore();
137+
```
138+
139+
Some use cases require multiple app instances at the same time — for example, reading data from one Firebase project and creating custom tokens for another, or authenticating two apps with separate credentials:
140+
141+
```dart
142+
// Each AppOptions points to a different Firebase project
143+
final defaultApp = FirebaseApp.initializeApp(
144+
options: AppOptions(
145+
credential: Credential.fromServiceAccount(File('path/to/default-service-account.json')),
146+
projectId: 'my-default-project',
147+
),
148+
);
149+
150+
// Initialize another app with a different config
151+
final otherApp = FirebaseApp.initializeApp(
152+
options: AppOptions(
153+
credential: Credential.fromServiceAccount(File('path/to/other-service-account.json')),
154+
projectId: 'my-other-project',
155+
),
156+
name: 'other',
157+
);
158+
159+
print(defaultApp.name); // '[DEFAULT]'
160+
print(otherApp.name); // 'other'
161+
162+
// Access services from each app
163+
final defaultAuth = defaultApp.auth();
164+
final defaultFirestore = defaultApp.firestore();
165+
166+
final otherAuth = otherApp.auth();
167+
final otherFirestore = otherApp.firestore();
168+
```
169+
170+
### Testing with gcloud end user credentials
171+
172+
When testing locally with Google Application Default Credentials obtained via `gcloud auth application-default login`, you must explicitly provide a project ID because Firebase Authentication does not accept gcloud end-user credentials without one:
173+
174+
```dart
175+
final app = FirebaseApp.initializeApp(
176+
options: AppOptions(
177+
credential: Credential.fromApplicationDefaultCredentials(),
178+
projectId: '<FIREBASE_PROJECT_ID>',
179+
),
180+
);
181+
```
182+
183+
Alternatively, set the `GOOGLE_CLOUD_PROJECT` environment variable to avoid changing your code:
184+
185+
```bash
186+
export GOOGLE_CLOUD_PROJECT="<FIREBASE_PROJECT_ID>"
187+
```
188+
80189
## Usage
81190

82191
Once you have initialized an app instance with a credential, you can use any of the [supported services](#supported-services) to interact with Firebase.

0 commit comments

Comments
 (0)