From 63dc21034b4d017f2335ad57502550675dd92770 Mon Sep 17 00:00:00 2001 From: Jonathan Edey Date: Fri, 10 Nov 2023 12:12:50 -0500 Subject: [PATCH 1/6] Update Firebase test project setup instructions. --- CONTRIBUTING.md | 117 ++++++++++++++++++++++++++++++++---------------- 1 file changed, 79 insertions(+), 38 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1d500cba8..4c3eb907f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -162,44 +162,85 @@ pytest --cov=firebase_admin --cov=tests ### Integration Testing -A suite of integration tests are available under the `integration/` directory. -These tests are designed to run against an actual Firebase project. Create a new -project in the [Firebase Console](https://console.firebase.google.com), if you -do not already have one suitable for running the tests aginst. Then obtain the -following credentials from the project: - -1. *Service account certificate*: This can be downloaded as a JSON file from - the "Settings > Service Accounts" tab of the Firebase console. Copy the - file into the repo so it's available at `cert.json`. -2. *Web API key*: This is displayed in the "Settings > General" tab of the - console. Copy it and save to a new text file at `apikey.txt`. - -Then set up your Firebase/GCP project as follows: - -1. Enable Firestore: Go to the Firebase Console, and select "Database" from - the "Develop" menu. Click on the "Create database" button. You may choose - to set up Firestore either in the locked mode or in the test mode. -2. Enable password auth: Select "Authentication" from the "Develop" menu in - Firebase Console. Select the "Sign-in method" tab, and enable the - "Email/Password" sign-in method, including the Email link (passwordless - sign-in) option. -3. Enable the Firebase ML API: Go to the - [Google Developers Console]( - https://console.developers.google.com/apis/api/firebaseml.googleapis.com/overview) - and make sure your project is selected. If the API is not already enabled, click Enable. -4. Enable the IAM API: Go to the - [Google Cloud Platform Console](https://console.cloud.google.com) and make - sure your Firebase/GCP project is selected. Select "APIs & Services > - Dashboard" from the main menu, and click the "ENABLE APIS AND SERVICES" - button. Search for and enable the "Identity and Access Management (IAM) - API". -5. Grant your service account the 'Firebase Authentication Admin' role. This is - required to ensure that exported user records contain the password hashes of - the user accounts: - 1. Go to [Google Cloud Platform Console / IAM & admin](https://console.cloud.google.com/iam-admin). - 2. Find your service account in the list, and click the 'pencil' icon to edit it's permissions. - 3. Click 'ADD ANOTHER ROLE' and choose 'Firebase Authentication Admin'. - 4. Click 'SAVE'. + +A suite of integration tests are available under the `integration/` directory. These tests +are designed to run against an actual Firebase project. If you do not already have one +suitable for running the tests against, you can create a new project in the +[Firebase Console](https://console.firebase.google.com) following the setup guide below. +Otherwise you can obtain the following credentials from your current project: + + +1. Service account certificate: This can be downloaded as a JSON file from the +**'Settings > Service Accounts'** tab of the Firebase console. Copy the file into the repo +so it's available at `cert.json`. + + +2. Web API key: This is displayed in the **'Settings > General'** tab of the Firebase console +after enabling Authentication as described in the steps below. Copy it and save to a new text +file at `apikey.txt`. + + +Set up your Firebase project as follows: + + +1. Enable Authentication: + 1. Go to the Firebase Console, and select **'Authentication'** from the **'Build'** menu. + 2. Click on **'Get Started'**. + 3. Select **'Sign-in method > Add new provider > Email/Password'** then enable both the + **'Email/Password'** and **'Email link (passwordless sign-in)'** options. + + +2. Enable Firestore: + 1. Go to the Firebase Console, and select **'Firestore Database'** from the **'Build'** menu. + 2. Click on the **'Create database'** button. You can choose to set up Firestore either in + the production mode or in the test mode. + + +3. Enable Realtime Database: + 1. Go to the Firebase Console, and select **'Realtime Database'** from the **'Build'** menu. + 2. Click on the **'Create database'** button. You can choose to set up the Realtime database + either in the locked mode or in the test mode. + 3. In the **'Data'** tab click on the kebab menu (3 dots) and select **'Create Database'**. + 4. Enter your Project ID (Found in the **'General'** tab in **'Account Settings'**) as the + **'Realtime Database reference'**. Again, you can choose to set up the Realtime database + either in the locked mode or in the test mode. + + +4. Enable Storage: + 1. Go to the Firebase Console, and select **'Storage'** from the **'Build'** menu. + 2. Click on the **'Get started'** button. You can choose to set up the Realtime database + either in the production mode or in the test mode. + + +5. Enable the Firebase ML API: + 1. Go to the [Google Developers Console | Firebase ML API]( + https://console.developers.google.com/apis/api/firebaseml.googleapis.com/overview) and make + sure your project is selected. + 2. If the API is not already enabled, click **'Enable'**. + + +6. Enable the IAM API: + 1. Go to the [Google Cloud Platform Console](https://console.cloud.google.com) and make sure + your Firebase project is selected. + 2. Select **'APIs & Services'** from the main menu, and click the + **'ENABLE APIS AND SERVICES'** button. + 3. Search for and enable **'Identity and Access Management (IAM) API'** by Google Enterprise API. + + +7. Enable Tenant Management: + 1. Go to + [Google Developers Console | Identity Platform](https://console.cloud.google.com/customer-identity/) + and if it is not already enabled, click **'Enable'**. + 2. Then follow [this guide](https://cloud.google.com/identity-platform/docs/multi-tenancy-quickstart#enabling_multi-tenancy) to enable multi-tenancy. + + +8. Ensure your service account has the **'Firebase Authentication Admin'** role. This is required +to ensure that exported user records contain the password hashes of the user accounts: + 1. Go to [Google Cloud Platform Console / IAM & admin](https://console.cloud.google.com/iam-admin). + 2. Find your service account in the list. If not added click the **'pencil'** icon to edit its + permissions. + 3. Click **'ADD ANOTHER ROLE'** and choose **'Firebase Authentication Admin'**. + 4. Click **'SAVE'**. Now you can invoke the integration test suite as follows: From 93731809091684206860469d76cc7eb7638c2a65 Mon Sep 17 00:00:00 2001 From: Jonathan Edey Date: Fri, 10 Nov 2023 12:19:10 -0500 Subject: [PATCH 2/6] fix: numbering --- CONTRIBUTING.md | 72 +++++++++++++++++++++++++------------------------ 1 file changed, 37 insertions(+), 35 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4c3eb907f..a125d3cee 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -184,63 +184,65 @@ Set up your Firebase project as follows: 1. Enable Authentication: - 1. Go to the Firebase Console, and select **'Authentication'** from the **'Build'** menu. - 2. Click on **'Get Started'**. - 3. Select **'Sign-in method > Add new provider > Email/Password'** then enable both the - **'Email/Password'** and **'Email link (passwordless sign-in)'** options. + 1. Go to the Firebase Console, and select **'Authentication'** from the **'Build'** menu. + 2. Click on **'Get Started'**. + 3. Select **'Sign-in method > Add new provider > Email/Password'** then enable both the + **'Email/Password'** and **'Email link (passwordless sign-in)'** options. 2. Enable Firestore: - 1. Go to the Firebase Console, and select **'Firestore Database'** from the **'Build'** menu. - 2. Click on the **'Create database'** button. You can choose to set up Firestore either in - the production mode or in the test mode. + 1. Go to the Firebase Console, and select **'Firestore Database'** from the **'Build'** menu. + 2. Click on the **'Create database'** button. You can choose to set up Firestore either in + the production mode or in the test mode. 3. Enable Realtime Database: - 1. Go to the Firebase Console, and select **'Realtime Database'** from the **'Build'** menu. - 2. Click on the **'Create database'** button. You can choose to set up the Realtime database - either in the locked mode or in the test mode. - 3. In the **'Data'** tab click on the kebab menu (3 dots) and select **'Create Database'**. - 4. Enter your Project ID (Found in the **'General'** tab in **'Account Settings'**) as the - **'Realtime Database reference'**. Again, you can choose to set up the Realtime database - either in the locked mode or in the test mode. + 1. Go to the Firebase Console, and select **'Realtime Database'** from the **'Build'** menu. + 2. Click on the **'Create database'** button. You can choose to set up the Realtime database + either in the locked mode or in the test mode. + 3. In the **'Data'** tab click on the kebab menu (3 dots) and select **'Create Database'**. + 4. Enter your Project ID (Found in the **'General'** tab in **'Account Settings'**) as the + **'Realtime Database reference'**. Again, you can choose to set up the Realtime database + either in the locked mode or in the test mode. 4. Enable Storage: - 1. Go to the Firebase Console, and select **'Storage'** from the **'Build'** menu. - 2. Click on the **'Get started'** button. You can choose to set up the Realtime database - either in the production mode or in the test mode. + 1. Go to the Firebase Console, and select **'Storage'** from the **'Build'** menu. + 2. Click on the **'Get started'** button. You can choose to set up the Realtime database + either in the production mode or in the test mode. 5. Enable the Firebase ML API: - 1. Go to the [Google Developers Console | Firebase ML API]( - https://console.developers.google.com/apis/api/firebaseml.googleapis.com/overview) and make - sure your project is selected. - 2. If the API is not already enabled, click **'Enable'**. + 1. Go to the + [Google Developers Console | Firebase ML API](https://console.developers.google.com/apis/api/firebaseml.googleapis.com/overview) + and make sure your project is selected. + 2. If the API is not already enabled, click **'Enable'**. 6. Enable the IAM API: - 1. Go to the [Google Cloud Platform Console](https://console.cloud.google.com) and make sure - your Firebase project is selected. - 2. Select **'APIs & Services'** from the main menu, and click the - **'ENABLE APIS AND SERVICES'** button. - 3. Search for and enable **'Identity and Access Management (IAM) API'** by Google Enterprise API. + 1. Go to the[Google Cloud Platform Console](https://console.cloud.google.com) + and make sureyour Firebase project is selected. + 2. Select **'APIs & Services'** from the main menu, and click the + **'ENABLE APIS AND SERVICES'** button. + 3. Search for and enable **'Identity and Access Management (IAM) API'** by Google Enterprise API. 7. Enable Tenant Management: - 1. Go to - [Google Developers Console | Identity Platform](https://console.cloud.google.com/customer-identity/) - and if it is not already enabled, click **'Enable'**. - 2. Then follow [this guide](https://cloud.google.com/identity-platform/docs/multi-tenancy-quickstart#enabling_multi-tenancy) to enable multi-tenancy. + 1. Go to + [Google Developers Console | Identity Platform](https://console.cloud.google.com/customer-identity/) + and if it is not already enabled, click **'Enable'**. + 2. Then follow + [this guide](https://cloud.google.com/identity-platform/docs/multi-tenancy-quickstart#enabling_multi-tenancy) + to enable multi-tenancy. 8. Ensure your service account has the **'Firebase Authentication Admin'** role. This is required to ensure that exported user records contain the password hashes of the user accounts: - 1. Go to [Google Cloud Platform Console / IAM & admin](https://console.cloud.google.com/iam-admin). - 2. Find your service account in the list. If not added click the **'pencil'** icon to edit its - permissions. - 3. Click **'ADD ANOTHER ROLE'** and choose **'Firebase Authentication Admin'**. - 4. Click **'SAVE'**. + 1. Go to [Google Cloud Platform Console / IAM & admin](https://console.cloud.google.com/iam-admin). + 2. Find your service account in the list. If not added click the **'pencil'** icon to edit its + permissions. + 3. Click **'ADD ANOTHER ROLE'** and choose **'Firebase Authentication Admin'**. + 4. Click **'SAVE'**. Now you can invoke the integration test suite as follows: From 62e95763dcd182b44158c25605aace22afe1ceb7 Mon Sep 17 00:00:00 2001 From: Jonathan Edey Date: Mon, 13 Nov 2023 13:09:31 -0500 Subject: [PATCH 3/6] fix: add missing step. --- CONTRIBUTING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a125d3cee..1eaaaab62 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -171,8 +171,8 @@ Otherwise you can obtain the following credentials from your current project: 1. Service account certificate: This can be downloaded as a JSON file from the -**'Settings > Service Accounts'** tab of the Firebase console. Copy the file into the repo -so it's available at `cert.json`. +**'Settings > Service Accounts'** tab of the Firebase console when you click the +**'Generate new private key'** button. Copy the file into the repo so it's available at `cert.json`. 2. Web API key: This is displayed in the **'Settings > General'** tab of the Firebase console From 60beb7fc46b0fcdaf8b5691813007f00d32a8a24 Mon Sep 17 00:00:00 2001 From: Jonathan Edey Date: Thu, 16 Nov 2023 11:00:33 -0500 Subject: [PATCH 4/6] mirror Tech Writer review changes --- CONTRIBUTING.md | 83 +++++++++++++++++++++++++++---------------------- 1 file changed, 45 insertions(+), 38 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1eaaaab62..421327b5c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -163,19 +163,21 @@ pytest --cov=firebase_admin --cov=tests ### Integration Testing -A suite of integration tests are available under the `integration/` directory. These tests -are designed to run against an actual Firebase project. If you do not already have one -suitable for running the tests against, you can create a new project in the +Integration tests are executed against a real life Firebase project. If you do not already +have one suitable for running the tests against, you can create a new project in the [Firebase Console](https://console.firebase.google.com) following the setup guide below. -Otherwise you can obtain the following credentials from your current project: +If you already have a Firebase project, you'll need to obtain credentials to communicate and +authorize access to your Firebase project: -1. Service account certificate: This can be downloaded as a JSON file from the -**'Settings > Service Accounts'** tab of the Firebase console when you click the -**'Generate new private key'** button. Copy the file into the repo so it's available at `cert.json`. +1. Service account certificate: This allows access to your Firebase project through a service account +which is required for all integration tests. This can be downloaded as a JSON file from the +**Settings > Service Accounts** tab of the Firebase console when you click the +**Generate new private key** button. Copy the file into the repo so it's available at `cert.json`. -2. Web API key: This is displayed in the **'Settings > General'** tab of the Firebase console +2. Web API key: This allows for Auth sign-in needed for some Authentication and Tenant Management +integration tests. This is displayed in the **Settings > General** tab of the Firebase console after enabling Authentication as described in the steps below. Copy it and save to a new text file at `apikey.txt`. @@ -184,65 +186,70 @@ Set up your Firebase project as follows: 1. Enable Authentication: - 1. Go to the Firebase Console, and select **'Authentication'** from the **'Build'** menu. - 2. Click on **'Get Started'**. - 3. Select **'Sign-in method > Add new provider > Email/Password'** then enable both the - **'Email/Password'** and **'Email link (passwordless sign-in)'** options. + 1. Go to the Firebase Console, and select **Authentication** from the **Build** menu. + 2. Click on **Get Started**. + 3. Select **Sign-in method > Add new provider > Email/Password** then enable both the + **Email/Password** and **Email link (passwordless sign-in)** options. 2. Enable Firestore: - 1. Go to the Firebase Console, and select **'Firestore Database'** from the **'Build'** menu. - 2. Click on the **'Create database'** button. You can choose to set up Firestore either in + 1. Go to the Firebase Console, and select **Firestore Database** from the **Build** menu. + 2. Click on the **Create database** button. You can choose to set up Firestore either in the production mode or in the test mode. 3. Enable Realtime Database: - 1. Go to the Firebase Console, and select **'Realtime Database'** from the **'Build'** menu. - 2. Click on the **'Create database'** button. You can choose to set up the Realtime database + 1. Go to the Firebase Console, and select **Realtime Database** from the **Build** menu. + 2. Click on the **Create Database** button. You can choose to set up the Realtime Database either in the locked mode or in the test mode. - 3. In the **'Data'** tab click on the kebab menu (3 dots) and select **'Create Database'**. - 4. Enter your Project ID (Found in the **'General'** tab in **'Account Settings'**) as the - **'Realtime Database reference'**. Again, you can choose to set up the Realtime database + + > **Note:** Integration tests are not run against the default Realtime Database reference and are + instead run against a database created at `https://{PROJECT_ID}.firebaseio.com`. + This second Realtime Database reference is created in the following steps. + + 3. In the **Data** tab click on the kebab menu (3 dots) and select **Create Database**. + 4. Enter your Project ID (Found in the **General** tab in **Account Settings**) as the + **Realtime Database reference**. Again, you can choose to set up the Realtime Database either in the locked mode or in the test mode. 4. Enable Storage: - 1. Go to the Firebase Console, and select **'Storage'** from the **'Build'** menu. - 2. Click on the **'Get started'** button. You can choose to set up the Realtime database + 1. Go to the Firebase Console, and select **Storage** from the **Build** menu. + 2. Click on the **Get started** button. You can choose to set up Cloud Storage either in the production mode or in the test mode. 5. Enable the Firebase ML API: 1. Go to the - [Google Developers Console | Firebase ML API](https://console.developers.google.com/apis/api/firebaseml.googleapis.com/overview) + [Google Cloud console | Firebase ML API](https://console.cloud.google.com/apis/api/firebaseml.googleapis.com/overview) and make sure your project is selected. - 2. If the API is not already enabled, click **'Enable'**. + 2. If the API is not already enabled, click **Enable**. 6. Enable the IAM API: - 1. Go to the[Google Cloud Platform Console](https://console.cloud.google.com) - and make sureyour Firebase project is selected. - 2. Select **'APIs & Services'** from the main menu, and click the - **'ENABLE APIS AND SERVICES'** button. - 3. Search for and enable **'Identity and Access Management (IAM) API'** by Google Enterprise API. + 1. Go to the [Google Cloud console](https://console.cloud.google.com) + and make sure your Firebase project is selected. + 2. Select **APIs & Services** from the main menu, and click the + **ENABLE APIS AND SERVICES** button. + 3. Search for and enable **Identity and Access Management (IAM) API** by Google Enterprise API. 7. Enable Tenant Management: 1. Go to - [Google Developers Console | Identity Platform](https://console.cloud.google.com/customer-identity/) - and if it is not already enabled, click **'Enable'**. - 2. Then follow - [this guide](https://cloud.google.com/identity-platform/docs/multi-tenancy-quickstart#enabling_multi-tenancy) - to enable multi-tenancy. + [Google Cloud console | Identity Platform](https://console.cloud.google.com/customer-identity/) + and if it is not already enabled, click **Enable**. + 2. Then + [enable multi-tenancy](https://cloud.google.com/identity-platform/docs/multi-tenancy-quickstart#enabling_multi-tenancy) + for your project. -8. Ensure your service account has the **'Firebase Authentication Admin'** role. This is required +8. Ensure your service account has the **Firebase Authentication Admin** role. This is required to ensure that exported user records contain the password hashes of the user accounts: - 1. Go to [Google Cloud Platform Console / IAM & admin](https://console.cloud.google.com/iam-admin). - 2. Find your service account in the list. If not added click the **'pencil'** icon to edit its + 1. Go to [Google Cloud console | IAM & admin](https://console.cloud.google.com/iam-admin). + 2. Find your service account in the list. If not added click the **pencil** icon to edit its permissions. - 3. Click **'ADD ANOTHER ROLE'** and choose **'Firebase Authentication Admin'**. - 4. Click **'SAVE'**. + 3. Click **ADD ANOTHER ROLE** and choose **Firebase Authentication Admin**. + 4. Click **SAVE**. Now you can invoke the integration test suite as follows: From 69e099163ae59a365747c6385c404dbaa831360f Mon Sep 17 00:00:00 2001 From: Jonathan Edey Date: Thu, 30 Nov 2023 16:18:08 -0500 Subject: [PATCH 5/6] fix: pencil --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 421327b5c..ea9063ade 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -246,7 +246,7 @@ Set up your Firebase project as follows: 8. Ensure your service account has the **Firebase Authentication Admin** role. This is required to ensure that exported user records contain the password hashes of the user accounts: 1. Go to [Google Cloud console | IAM & admin](https://console.cloud.google.com/iam-admin). - 2. Find your service account in the list. If not added click the **pencil** icon to edit its + 2. Find your service account in the list. If not added click the pencil icon to edit its permissions. 3. Click **ADD ANOTHER ROLE** and choose **Firebase Authentication Admin**. 4. Click **SAVE**. From 7d211589b3e8f082b4d460e02a8fb25e79caaad5 Mon Sep 17 00:00:00 2001 From: Jonathan Edey Date: Mon, 18 Dec 2023 17:04:44 -0500 Subject: [PATCH 6/6] Added service account management note. --- CONTRIBUTING.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ea9063ade..c06d7de2c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -174,6 +174,7 @@ authorize access to your Firebase project: which is required for all integration tests. This can be downloaded as a JSON file from the **Settings > Service Accounts** tab of the Firebase console when you click the **Generate new private key** button. Copy the file into the repo so it's available at `cert.json`. + > **Note:** Service accounts should be carefully managed and their keys should never be stored in publicly accessible source code or repositories. 2. Web API key: This allows for Auth sign-in needed for some Authentication and Tenant Management