From a62220dc10bccce38adc62f69161fa1dd2f5d667 Mon Sep 17 00:00:00 2001 From: Matthias Schoettle Date: Tue, 16 Dec 2025 16:06:36 -0500 Subject: [PATCH 1/4] docs: move firebase project setup into its dedicated page --- docs/development/local-dev-setup.md | 92 +------------ docs/install/firebase-project-setup.md | 182 +++++++++++++++++++++++++ docs/install/index.md | 83 +---------- mkdocs.yml | 1 + 4 files changed, 188 insertions(+), 170 deletions(-) create mode 100644 docs/install/firebase-project-setup.md diff --git a/docs/development/local-dev-setup.md b/docs/development/local-dev-setup.md index 90a5d41..650fe6c 100644 --- a/docs/development/local-dev-setup.md +++ b/docs/development/local-dev-setup.md @@ -46,96 +46,8 @@ The other components are considered optional. The user applications [communicate via Firebase](architecture/index.md#communication-between-user-applications-and-the-opal-pie) with the _Opal PIE_. You need your own Firebase project so that your local app can communicate with the backend components. -!!! note - - Firebase is a Google product. - Therefore, you need a Google account to be able to use Firebase. - -#### Create a new Firebase project - -1. Open the [Firebase Console](https://console.firebase.google.com) -1. Click on "Create a new Firebase project" -1. Give it a relevant project name, such as "Opal Local" -1. Uncheck "Enable Google Analytics for this project" and other options that are proposed to you -1. Click "Create project" - -The "Authentication" and "Realtime Database" features are needed for communication between the apps and backend components. -Follow the instructions below to enable and configure these features. - -#### Create a new Realtime Database - -1. In the left panel of your newly created Firebase project, expand "Build" and click on "Realtime Database". -1. Click "Create Database" -1. On the second step of "Set up database" (Security rules), select "Start in test mode". - -!!! note Security rules - - This configures your Realtime Database to be accessible to anyone for 30 days. - It is also possible to restrict access to authenticated users only by specifying the condition as `auth.uid !== null`. - However, not all features will work. - The rules in use by the Opal solution can be found in the [listener project](https://github.com/opalmedapps/opal-listener/blob/main/firebase/database.rules.json). - See the [instructions on how to deploy them](https://github.com/opalmedapps/opal-listener/blob/main/docs/source/firebase-rules.md) to your project or copy-and-paste them into your project's rules. - -See also the Firebase documentation on [Firebase Security Rules](https://firebase.google.com/docs/rules). - -#### Enable email and password authentication - -1. In the left panel, expand "Build" and click on "Authentication" -1. Click on "Get started" -1. Choose "Email/Password" as the sign-in provider -1. Enable "Email/Password" and click "Save" - -See also the Firebase documentation on [Firebase Authentication](https://firebase.google.com/docs/auth). - -#### Retrieve the Firebase project configurations - -Retrieve the client configuration for browser and Android apps: - -##### Browser client configuration - -1. Click on the settings icon (gear) next to "Project Overview" - -1. Click on "Project Settings" - -1. In the "General" tab, under "Your Apps", click the "\" icon - -1. Choose an app nickname, such as "Opal Local" - - You can also enable "Firebase Hosting" at this time if you are planning to use this project for production or intend to test the password reset feature in the app. - -1. Click "Register app" - -1. Copy the code and save it somewhere for later - -##### Mobile app client configuration - -1. Go back to the "Project Settings" page -1. In the "General" tab, under "Your Apps", click the Android icon -1. Choose an Android package name -1. Click "Register app" -1. Download the `google-services.json` file and save it somewhere for later - -!!! question "Do I also need to add an iOS app?" - - You do not need to add it if you are only building the iOS app. - The iOS app is reusing the `google-services.json` file during the build. - - However, if you intend to use [Firebase App Distribution](https://firebase.google.com/docs/app-distribution) to distribute your mobile app to testers, you will need to register an iOS app as well. - - 1. Go back to the "Project Settings" page - 1. In the "General" tab, under "Your Apps", click the iOS icon - 1. Provide the Apple bundle ID of your app - 1. Click "Register app" - -##### Service account - -Retrieve the private key for the admin SDK: - -1. Go back to the "Project Settings" page and click on the "Service accounts" tab -1. Click on "Generate new private key" and then "Generate key" -1. Download the file somewhere safe on your machine for later - -See also the Firebase documentation on [Admin SDK Authentication](https://firebase.google.com/docs/database/admin/start). +Follow the [instructions on how to set up a Firebase project](../install/firebase-project-setup.md). +Note that the instructions on restricting permissions are optional for development. ### Set up the legacy databases diff --git a/docs/install/firebase-project-setup.md b/docs/install/firebase-project-setup.md new file mode 100644 index 0000000..538889a --- /dev/null +++ b/docs/install/firebase-project-setup.md @@ -0,0 +1,182 @@ + + +# Firebase project setup + +The user applications [communicate via Firebase](../development/architecture/index.md#communication-between-user-applications-and-the-opal-pie) with the _Opal PIE_. +You need your own Firebase project so that your app can communicate with the backend components. + +!!! note + + Firebase is a Google product. + Therefore, you need a Google account to be able to use Firebase. + +## Create a new Firebase project + +1. Open the [Firebase Console](https://console.firebase.google.com) +1. Click on "Create a new Firebase project" +1. Give it a relevant project name, such as "Opal Local" +1. Uncheck "Enable Google Analytics for this project" and other options that are proposed to you +1. Click "Create project" + +The "Authentication" and "Realtime Database" features are needed for communication between the apps and backend components. +Follow the instructions below to enable and configure these features. + +## Create a new Realtime Database + +1. In the left panel of your newly created Firebase project, expand "Build" and click on "Realtime Database". +1. Click "Create Database" +1. On the second step of "Set up database" (Security rules), select "Start in test mode". + +!!! note Security rules + + This configures your Realtime Database to be accessible to anyone for 30 days. + It is also possible to restrict access to authenticated users only by specifying the condition as `auth.uid !== null`. + However, not all features will work. + The rules in use by the Opal solution can be found in the [listener project](https://github.com/opalmedapps/opal-listener/blob/main/firebase/database.rules.json). + See the [instructions on how to deploy them](https://github.com/opalmedapps/opal-listener/blob/main/docs/source/firebase-rules.md) to your project or copy-and-paste them into your project's rules. + +See also the Firebase documentation on [Firebase Security Rules](https://firebase.google.com/docs/rules). + +## Enable email and password authentication + +1. In the left panel, expand "Build" and click on "Authentication" +1. Click on "Get started" +1. Choose "Email/Password" as the sign-in provider +1. Enable "Email/Password" and click "Save" + +See also the Firebase documentation on [Firebase Authentication](https://firebase.google.com/docs/auth). + +## Retrieve the Firebase project configurations + +Retrieve the client configuration for browser and Android apps: + +### Browser client configuration + +1. Click on the settings icon (gear) next to "Project Overview" + +1. Click on "Project Settings" + +1. In the "General" tab, under "Your Apps", click the "\" icon + +1. Choose an app nickname, such as "Opal Local" + + You can also enable "Firebase Hosting" at this time if you are planning to use this project for production or intend to test the password reset feature in the app. + +1. Click "Register app" + +1. Copy the code and save it somewhere for later + +### Mobile app client configuration + +1. Go back to the "Project Settings" page +1. In the "General" tab, under "Your Apps", click the Android icon +1. Choose an Android package name +1. Click "Register app" +1. Download the `google-services.json` file and save it somewhere for later + +!!! question "Do I also need to add an iOS app?" + + You do not need to add it if you are only building the iOS app. + The iOS app is reusing the `google-services.json` file during the build. + + However, if you intend to use [Firebase App Distribution](https://firebase.google.com/docs/app-distribution) to distribute your mobile app to testers, you will need to register an iOS app as well. + + 1. Go back to the "Project Settings" page + 1. In the "General" tab, under "Your Apps", click the iOS icon + 1. Provide the Apple bundle ID of your app + 1. Click "Register app" + +### Service account + +Retrieve the private key for the admin SDK: + +1. Go back to the "Project Settings" page and click on the "Service accounts" tab +1. Click on "Generate new private key" and then "Generate key" +1. Download the file somewhere safe on your machine for later + +See also the Firebase documentation on [Admin SDK Authentication](https://firebase.google.com/docs/database/admin/start). + +## Restrict permissions + +During the above set up, Firebase creates a service account and API keys for you. +By default, these have permissions that are more permissive than what is needed. +Therefore, we strongly recommend to restrict their permissions, especially for production environments. + +### Restrict service account permissions + +By default, Firebase creates a service account and API keys. +The service account likely has more permissions than are needed. +We recommend to restrict the permissions as much as possible. + +Go to the [Service Accounts in Google Cloud](https://console.cloud.google.com/projectselector2/iam-admin/serviceaccounts) and select your Firebase project, then: + +1. Click on the name of the service account that was created for you +1. Go to "Permissions" and click on "Manage access" +1. Update the assigned roles to match the following roles: + - _Firebase Authentication Admin_ + - _Firebase Cloud Messaging Admin_ + - _Firebase Realtime Database Admin_ + - _Firebase Rules Admin_ +1. Click "Save" + +### Restrict API keys + +When registering apps on your Firebase project, Firebase automatically creates API keys. +These should be further restricted. + +!!! question "Can new API keys be created instead?" + + This is generally possible. + However, as part of the set up you will need to get a `google-services.json` file. + When this file is retrieved, Firebase automatically creates corresponding API keys. + +Go to the [API Credentials in Google Cloud](https://console.cloud.google.com/apis/credentials) and select the corresponding Firebase project. + +#### Browser key + +1. The browser key should have a name like "Browser key (auto created by Firebase)" + +1. Click on its name to edit it + +1. Under "Application restrictions", choose "Websites" + +1. Add the following websites at a minimum to allow mobile app users to access this project + + - `app://localhost` + - `http://localhost` + - `https://.firebaseapp.com` + + You should also add the base URL of your registration and web app to this list. + +1. Under "API Restrictions", choose "Restrict key" + +1. Choose the following APIs + + - _FCM Registration API_ + - _Firebase Realtime Database Management API_ + - _Identity Toolkit API_ + +1. Click "Save" + +#### Android key + +1. The Android API key should have a name like "Android key (auto created by Firebase)" +1. Click on its name to edit it +1. Under "API Restrictions", choose "Restrict key" +1. Choose the following APIs + - _FCM Registration API_ + - _Firebase Realtime Database Management API_ + - _Identity Toolkit API_ + - _Firebase Installations API_ +1. Click "Save" + +It is also possible to restrict the key further to a specific Android app. + +#### iOS key + +The iOS key gets generated when [registering an iOS app](../development/local-dev-setup.md#mobile-app-client-configuration). +This key, named "iOS key (auto created by Firebase)", is not needed and can be deleted. diff --git a/docs/install/index.md b/docs/install/index.md index 83e7a6f..932f667 100644 --- a/docs/install/index.md +++ b/docs/install/index.md @@ -49,29 +49,8 @@ In addition, you need a Firebase project. #### Create and set up a new Firebase project -If you don't have a dedicated Firebase project yet, follow the steps to [create a Firebase project](../development/local-dev-setup.md#create-a-new-firebase-project). -If you already have a dedicated Firebase project, ensure that you have done the following steps: - -- [create a Realtime Database](../development/local-dev-setup.md#create-a-new-realtime-database) -- [enable email and password authentication](../development/local-dev-setup.md#enable-email-and-password-authentication) -- [retrieve Firebase configurations](../development/local-dev-setup.md#retrieve-the-firebase-project-configurations) - -#### Restrict service account permissions - -By default, Firebase creates a service account and API keys. -The service account likely has more permissions than are needed. -We recommend to restrict the permissions as much as possible. - -Go to the [Service Accounts in Google Cloud](https://console.cloud.google.com/projectselector2/iam-admin/serviceaccounts) and select your Firebase project, then: - -1. Click on the name of the service account that was created for you -1. Go to "Permissions" and click on "Manage access" -1. Update the assigned roles to match the following roles: - - *Firebase Authentication Admin* - - *Firebase Cloud Messaging Admin* - - *Firebase Realtime Database Admin* - - *Firebase Rules Admin* -1. Click "Save" +If you don't have a dedicated Firebase project yet, follow the steps to [set up a Firebase project]. +Please also ensure that you restrict the permissions of the Firebase service account and API keys. #### Retrieve the Apple Push Notification certificates @@ -139,61 +118,5 @@ Please follow the instructions in the [`deploy-pie`](https://github.com/opalmeda ### Requirements -#### Restrict Firebase API keys - We assume that you already [set up your Firebase project](#create-and-set-up-a-new-firebase-project) and [retrieved Firebase client configurations](../development/local-dev-setup.md#retrieve-the-firebase-project-configurations). -This means that API keys were already created for you. -By default, Firebase creates a service account and API keys with excessive permissions. - -!!! question "Can new API keys be created instead?" - - This is generally possible. - However, as part of the set up you will need to get a `google-services.json` file. - When this file is retrieved, Firebase automatically creates corresponding API keys. - -Go to the [API Credentials in Google Cloud](https://console.cloud.google.com/apis/credentials) and select the corresponding Firebase project. - -##### Browser key - -1. The browser key should have a name like "Browser key (auto created by Firebase)" - -1. Click on its name to edit it - -1. Under "Application restrictions", choose "Websites" - -1. Add the following websites at a minimum to allow mobile app users to access this project - - - `app://localhost` - - `http://localhost` - - `https://.firebaseapp.com` - - You should also add the base URL of your registration and web app to this list. - -1. Under "API Restrictions", choose "Restrict key" - -1. Choose the following APIs - - - *FCM Registration API* - - *Firebase Realtime Database Management API* - - *Identity Toolkit API* - -1. Click "Save" - -##### Android key - -1. The Android API key should have a name like "Android key (auto created by Firebase)" -1. Click on its name to edit it -1. Under "API Restrictions", choose "Restrict key" -1. Choose the following APIs - - *FCM Registration API* - - *Firebase Realtime Database Management API* - - *Identity Toolkit API* - - *Firebase Installations API* -1. Click "Save" - -It is also possible to restrict the key further to a specific Android app. - -##### iOS key - -The iOS key gets generated when [registering an iOS app](../development/local-dev-setup.md#mobile-app-client-configuration). -This key, named "iOS key (auto created by Firebase)", is not needed and can be deleted. +This means that API keys were already created for you which you need for the web and mobile apps. diff --git a/mkdocs.yml b/mkdocs.yml index f144009..09ae04e 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -47,6 +47,7 @@ nav: - Generate Self Signed Certificates: development/guides/self_signed_certificates.md - Install: - Deploying the Opal Solution: install/index.md + - Firebase project setup: install/set-up-firebase-project.md - Hospital Integration: install/integration.md # Configuration From 86599666c8fe680671ecdd2e1399cf0a0b6fff91 Mon Sep 17 00:00:00 2001 From: Matthias Schoettle Date: Tue, 16 Dec 2025 16:11:28 -0500 Subject: [PATCH 2/4] fix broken links --- docs/install/firebase-project-setup.md | 4 ++-- docs/install/index.md | 2 +- mkdocs.yml | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/install/firebase-project-setup.md b/docs/install/firebase-project-setup.md index 538889a..6a672c0 100644 --- a/docs/install/firebase-project-setup.md +++ b/docs/install/firebase-project-setup.md @@ -60,7 +60,7 @@ Retrieve the client configuration for browser and Android apps: 1. Click on "Project Settings" -1. In the "General" tab, under "Your Apps", click the "\" icon +1. In the "General" tab, under "Your Apps", click the "< />" icon 1. Choose an app nickname, such as "Opal Local" @@ -178,5 +178,5 @@ It is also possible to restrict the key further to a specific Android app. #### iOS key -The iOS key gets generated when [registering an iOS app](../development/local-dev-setup.md#mobile-app-client-configuration). +The iOS key gets generated when [registering an iOS app](#mobile-app-client-configuration). This key, named "iOS key (auto created by Firebase)", is not needed and can be deleted. diff --git a/docs/install/index.md b/docs/install/index.md index 932f667..991cc11 100644 --- a/docs/install/index.md +++ b/docs/install/index.md @@ -118,5 +118,5 @@ Please follow the instructions in the [`deploy-pie`](https://github.com/opalmeda ### Requirements -We assume that you already [set up your Firebase project](#create-and-set-up-a-new-firebase-project) and [retrieved Firebase client configurations](../development/local-dev-setup.md#retrieve-the-firebase-project-configurations). +We assume that you already [set up your Firebase project](./firebase-project-setup.md) and [retrieved Firebase client configurations](./firebase-project-setup.md#retrieve-the-firebase-project-configurations). This means that API keys were already created for you which you need for the web and mobile apps. diff --git a/mkdocs.yml b/mkdocs.yml index 09ae04e..9f68609 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -47,7 +47,7 @@ nav: - Generate Self Signed Certificates: development/guides/self_signed_certificates.md - Install: - Deploying the Opal Solution: install/index.md - - Firebase project setup: install/set-up-firebase-project.md + - Firebase project setup: install/firebase-project-setup.md - Hospital Integration: install/integration.md # Configuration From 34d42b98f46f2465dd696f73ae621586c0bf2aa2 Mon Sep 17 00:00:00 2001 From: Matthias Schoettle Date: Tue, 16 Dec 2025 16:12:26 -0500 Subject: [PATCH 3/4] add missing link --- docs/install/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/install/index.md b/docs/install/index.md index 991cc11..4f7d6ea 100644 --- a/docs/install/index.md +++ b/docs/install/index.md @@ -49,7 +49,7 @@ In addition, you need a Firebase project. #### Create and set up a new Firebase project -If you don't have a dedicated Firebase project yet, follow the steps to [set up a Firebase project]. +If you don't have a dedicated Firebase project yet, follow the steps to [set up a Firebase project](./firebase-project-setup.md). Please also ensure that you restrict the permissions of the Firebase service account and API keys. #### Retrieve the Apple Push Notification certificates From 123da0b13f5d92cf8dbdf85b0b710793d418f42e Mon Sep 17 00:00:00 2001 From: Matthias Schoettle Date: Tue, 16 Dec 2025 16:18:37 -0500 Subject: [PATCH 4/4] small fixes --- docs/development/local-dev-setup.md | 1 + docs/install/index.md | 1 + 2 files changed, 2 insertions(+) diff --git a/docs/development/local-dev-setup.md b/docs/development/local-dev-setup.md index 650fe6c..3ae538f 100644 --- a/docs/development/local-dev-setup.md +++ b/docs/development/local-dev-setup.md @@ -47,6 +47,7 @@ The user applications [communicate via Firebase](architecture/index.md#communica You need your own Firebase project so that your local app can communicate with the backend components. Follow the [instructions on how to set up a Firebase project](../install/firebase-project-setup.md). + Note that the instructions on restricting permissions are optional for development. ### Set up the legacy databases diff --git a/docs/install/index.md b/docs/install/index.md index 4f7d6ea..1d7bf08 100644 --- a/docs/install/index.md +++ b/docs/install/index.md @@ -50,6 +50,7 @@ In addition, you need a Firebase project. #### Create and set up a new Firebase project If you don't have a dedicated Firebase project yet, follow the steps to [set up a Firebase project](./firebase-project-setup.md). + Please also ensure that you restrict the permissions of the Firebase service account and API keys. #### Retrieve the Apple Push Notification certificates