From 903a5424535ecc0f1f4da0fe42750b5412899e0d Mon Sep 17 00:00:00 2001 From: Jonathan Edey Date: Fri, 10 Nov 2023 12:47:35 -0500 Subject: [PATCH 1/7] Update Firebase integration test project setup instructions. --- CONTRIBUTING.md | 116 +++++++++++++++++++++++++++++++++--------------- 1 file changed, 79 insertions(+), 37 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index eefd161066..65a24634a7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -156,43 +156,85 @@ below covers how to run the full test suite against an actual Firebase project. #### Integration Tests with an actual Firebase project -Other integration tests require 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 against. 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 `test/resources/key.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 `test/resources/apikey.txt`. - -Then set up your Firebase/Google Cloud 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 Console](https://console.cloud.google.com) and make - sure your Firebase/Google Cloud 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 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'. +Other integration tests require 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 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. + + +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'**. + Finally, to run the integration test suite: From 83b72e18f2e0a110774023d1f2f44b7dea42c5c2 Mon Sep 17 00:00:00 2001 From: Jonathan Edey Date: Fri, 10 Nov 2023 12:51:11 -0500 Subject: [PATCH 2/7] fix: path to resource keys --- CONTRIBUTING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 65a24634a7..874016cde2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -163,12 +163,12 @@ 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`. +so it's available at `test/resources/key.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`. +file at `test/resources/apikey.txt`. Set up your Firebase project as follows: From 53947557e5969762778d6ca9d9439272897080a1 Mon Sep 17 00:00:00 2001 From: Jonathan Edey Date: Mon, 13 Nov 2023 13:13:16 -0500 Subject: [PATCH 3/7] fix: add step --- CONTRIBUTING.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 874016cde2..3cb2c9eb61 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -162,8 +162,9 @@ suitable for running the tests against, you can create a new project in the 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 `test/resources/key.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 `test/resources/key.json`. 2. Web API key: This is displayed in the **'Settings > General'** tab of the Firebase console From 1977c054e0643524b1a5447e6cadd99f0f573367 Mon Sep 17 00:00:00 2001 From: Jonathan Edey Date: Thu, 16 Nov 2023 10:03:55 -0500 Subject: [PATCH 4/7] fix: mirror Tech Writer review --- CONTRIBUTING.md | 82 +++++++++++++++++++++++++++---------------------- 1 file changed, 45 insertions(+), 37 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3cb2c9eb61..e5bf082f6c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -156,18 +156,21 @@ below covers how to run the full test suite against an actual Firebase project. #### Integration Tests with an actual Firebase project -Other integration tests require 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 `test/resources/key.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 +`test/resources/key.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 `test/resources/apikey.txt`. @@ -176,65 +179,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'**. 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**. Finally, to run the integration test suite: From 1cc87f8d7fc7251ee7e25fad602d7c4a53f81c3e Mon Sep 17 00:00:00 2001 From: Jonathan Edey Date: Thu, 16 Nov 2023 10:15:06 -0500 Subject: [PATCH 5/7] remove quote --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e5bf082f6c..cb9befd68c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -216,7 +216,7 @@ Set up your Firebase project as follows: 1. Go to the [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: From 3917f1aec0b79f6c0d3e7b4e61f7ef6bf10225cc Mon Sep 17 00:00:00 2001 From: Jonathan Edey Date: Thu, 30 Nov 2023 16:32:19 -0500 Subject: [PATCH 6/7] fix: pencil --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index cb9befd68c..5cb5e2aeb9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -239,7 +239,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 0fe171fa41a114c38ef2db27e7769ea888c0d63e Mon Sep 17 00:00:00 2001 From: Jonathan Edey Date: Mon, 18 Dec 2023 17:46:57 -0500 Subject: [PATCH 7/7] Added service account management note. --- CONTRIBUTING.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5cb5e2aeb9..28d15bf290 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -167,6 +167,7 @@ which is required for all integration tests. This can be downloaded as a JSON fi **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 `test/resources/key.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