Skip to content

Commit dadc71c

Browse files
mschoettlemschoettle
authored
docs: add details for Firebase projects when deploying (#389)
* Service account creation with required roles/ * API key creation with * retrieval of Apple Push notification service certificate and private key
1 parent 4e933f5 commit dadc71c

File tree

3 files changed

+187
-5
lines changed

3 files changed

+187
-5
lines changed

‎.pre-commit-config.yaml‎

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -84,11 +84,17 @@ repos:
8484
- id: check-renovate
8585
args: ["--verbose"]
8686
additional_dependencies: ['json5']
87-
# requires: https://github.com/python-jsonschema/check-jsonschema/issues/341
8887
# - id: check-jsonschema
8988
# name: "Validate devcontainer"
9089
# files: ^\.devcontainer/.*\.json$
91-
# args: ["--schemafile", "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.schema.json"]
90+
# additional_dependencies: ['json5']
91+
# args: [
92+
# "--schemafile",
93+
# "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.schema.json",
94+
# "--force-filetype",
95+
# "json5",
96+
# "--verbose",
97+
# ]
9298
# waiting for custom YAML tags support: https://github.com/python-jsonschema/check-jsonschema/issues/489
9399
# - id: check-jsonschema
94100
# name: "Validate MkDocs file"

‎docs/development/local-dev-setup.md‎

Lines changed: 34 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -54,9 +54,9 @@ You need your own Firebase project so that your local app can communicate with t
5454
#### Create a new Firebase project
5555

5656
1. Open the [Firebase Console](https://console.firebase.google.com)
57-
1. Click on "+ Add project"
57+
1. Click on "Create a new Firebase project"
5858
1. Give it a relevant project name, such as "Opal Local"
59-
1. Uncheck "Enable Google Analytics for this project"
59+
1. Uncheck "Enable Google Analytics for this project" and other options that are proposed to you
6060
1. Click "Create project"
6161

6262
The "Authentication" and "Realtime Database" features are needed for communication between the apps and backend components.
@@ -89,15 +89,46 @@ See also the Firebase documentation on [Firebase Authentication](https://firebas
8989

9090
#### Retrieve the Firebase project configurations
9191

92-
Retrieve the client configuration:
92+
Retrieve the client configuration for browser and Android apps:
93+
94+
##### Browser client configuration
9395

9496
1. Click on the settings icon (gear) next to "Project Overview"
97+
9598
1. Click on "Project Settings"
99+
96100
1. In the "General" tab, under "Your Apps", click the "\</>" icon
101+
97102
1. Choose an app nickname, such as "Opal Local"
103+
104+
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.
105+
98106
1. Click "Register app"
107+
99108
1. Copy the code and save it somewhere for later
100109

110+
##### Mobile app client configuration
111+
112+
1. Go back to the "Project Settings" page
113+
1. In the "General" tab, under "Your Apps", click the Android icon
114+
1. Choose an Android package name
115+
1. Click "Register app"
116+
1. Download the `google-services.json` file and save it somewhere for later
117+
118+
!!! question "Do I also need to add an iOS app?"
119+
120+
You do not need to add it if you are only building the iOS app.
121+
The iOS app is reusing the `google-services.json` file during the build.
122+
123+
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.
124+
125+
1. Go back to the "Project Settings" page
126+
1. In the "General" tab, under "Your Apps", click the iOS icon
127+
1. Provide the Apple bundle ID of your app
128+
1. Click "Register app"
129+
130+
##### Service account
131+
101132
Retrieve the private key for the admin SDK:
102133

103134
1. Go back to the "Project Settings" page and click on the "Service accounts" tab

‎docs/install/index.md‎

Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,90 @@ The database server can also be run on a separate server:
3939

4040
Relationships between components on the same host are left out for brevity (except those making use of third-party components).
4141

42+
### Requirements
43+
44+
You need at least one machine on which to deploy the Opal PIE.
45+
This machine needs to have the [Docker Engine](https://docs.docker.com/engine/) and [Docker Compose](https://docs.docker.com/compose/) installed.
46+
A compatible container engine that also has support for compose can also be used.
47+
48+
In addition, you need a Firebase project.
49+
50+
#### Create and set up a new Firebase project
51+
52+
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).
53+
If you already have a dedicated Firebase project, ensure that you have done the following steps:
54+
55+
- [create a Realtime Database](../development/local-dev-setup.md#create-a-new-realtime-database)
56+
- [enable email and password authentication](../development/local-dev-setup.md#enable-email-and-password-authentication)
57+
- [retrieve Firebase configurations](../development/local-dev-setup.md#retrieve-the-firebase-project-configurations)
58+
59+
#### Restrict service account permissions
60+
61+
By default, Firebase creates a service account and API keys.
62+
The service account likely has more permissions than are needed.
63+
We recommend to restrict the permissions as much as possible.
64+
65+
Go to the [Service Accounts in Google Cloud](https://console.cloud.google.com/projectselector2/iam-admin/serviceaccounts) and select your Firebase project, then:
66+
67+
1. Click on the name of the service account that was created for you
68+
1. Go to "Permissions" and click on "Manage access"
69+
1. Update the assigned roles to match the following roles:
70+
- *Firebase Authentication Admin*
71+
- *Firebase Cloud Messaging Admin*
72+
- *Firebase Realtime Database Admin*
73+
- *Firebase Rules Admin*
74+
1. Click "Save"
75+
76+
#### Retrieve the Apple Push Notification certificates
77+
78+
!!! note
79+
80+
These instructions are specific to *macOS* as they require the *Keychain Access* utility.
81+
82+
While push notifications on Android are delivered via *Firebase Cloud Messaging*, on iOS the *Apple Push Notification Service* is used.
83+
84+
The following instructions assume that your iOS app has already been created in [App Store Connect](https://appstoreconnect.apple.com/apps) and therefore has an *App ID*.
85+
86+
!!! success "Preparation: Generate a *Certificate Signing Request*"
87+
88+
As a preparation, follow the instructions to [create a certificate signing request](https://developer.apple.com/help/account/certificates/create-a-certificate-signing-request).
89+
90+
Log in to your [Apple Developer Account](https://developer.apple.com/account) and do the following:
91+
92+
1. Under "Program resources" > "Certificates, IDs & Profiles", click "Certificates"
93+
1. Click the plus icon next to "Certificates"
94+
1. Under "Services", select "Apple Push Notification service SSL (Sandbox & Production)" and click "Continue"
95+
1. Select the App ID of your app and click "Continue"
96+
1. Upload your certificate signing request and click "Continue"
97+
1. Download your certificate
98+
99+
You now have a `.cer` file which needs to be imported to the keychain so it can be exported as a PKCS #12 archive:
100+
101+
1. Double-click the `.cer` file to add it to your keychain
102+
1. In *Keychain Access*, select the "login" keychain and look for the "Apple Push Services: `<appID>`" certificate
103+
1. Expand this certificate to reveal the private key entry
104+
1. Select both certificate and private key
105+
1. Right-click and select "Export 2 items..."
106+
1. Save the `.p12` file somewhere
107+
- Leave the password empty
108+
- Confirm the export with your password and selecting "Allow"
109+
110+
The `Certificates.p12` file contains both the certificate and private key.
111+
To separate them, run the following using the OpenSSL `pkcs12` command:
112+
113+
```console
114+
# export certificate
115+
openssl pkcs12 -in Certificates.p12 -clcerts -nokeys -legacy -out apn.crt
116+
# export private key
117+
openssl pkcs12 -in Certificates.p12 -nodes -nocerts -legacy -out apn.key
118+
```
119+
120+
!!! note "Note on OpenSSL version"
121+
122+
The above commands assume that you are using OpenSSL v3 which requires the `-legacy` flag.
123+
This is because older algorithms like the one used by keychain when exporting the certificates are disabled by default.
124+
If you are using OpenSSL v1.1, remove the `-legacy` flag from the commands.
125+
42126
### Automated deployment
43127

44128
We offer a semi-automated deployment via a [`copier`](https://copier.readthedocs.io/en/stable/) template.
@@ -52,3 +136,64 @@ Please follow the instructions in the [`deploy-pie`](https://github.com/opalmeda
52136

53137
```plantuml source="docs/install/diagrams/deployment_diagram_user.puml"
54138
```
139+
140+
### Requirements
141+
142+
#### Restrict Firebase API keys
143+
144+
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).
145+
This means that API keys were already created for you.
146+
By default, Firebase creates a service account and API keys with excessive permissions.
147+
148+
!!! question "Can new API keys be created instead?"
149+
150+
This is generally possible.
151+
However, as part of the set up you will need to get a `google-services.json` file.
152+
When this file is retrieved, Firebase automatically creates corresponding API keys.
153+
154+
Go to the [API Credentials in Google Cloud](https://console.cloud.google.com/apis/credentials) and select the corresponding Firebase project.
155+
156+
##### Browser key
157+
158+
1. The browser key should have a name like "Browser key (auto created by Firebase)"
159+
160+
1. Click on its name to edit it
161+
162+
1. Under "Application restrictions", choose "Websites"
163+
164+
1. Add the following websites at a minimum to allow mobile app users to access this project
165+
166+
- `app://localhost`
167+
- `http://localhost`
168+
- `https://<your-firebase-project-id>.firebaseapp.com`
169+
170+
You should also add the base URL of your registration and web app to this list.
171+
172+
1. Under "API Restrictions", choose "Restrict key"
173+
174+
1. Choose the following APIs
175+
176+
- *FCM Registration API*
177+
- *Firebase Realtime Database Management API*
178+
- *Identity Toolkit API*
179+
180+
1. Click "Save"
181+
182+
##### Android key
183+
184+
1. The Android API key should have a name like "Android key (auto created by Firebase)"
185+
1. Click on its name to edit it
186+
1. Under "API Restrictions", choose "Restrict key"
187+
1. Choose the following APIs
188+
- *FCM Registration API*
189+
- *Firebase Realtime Database Management API*
190+
- *Identity Toolkit API*
191+
- *Firebase Installations API*
192+
1. Click "Save"
193+
194+
It is also possible to restrict the key further to a specific Android app.
195+
196+
##### iOS key
197+
198+
The iOS key gets generated when [registering an iOS app](../development/local-dev-setup.md#mobile-app-client-configuration).
199+
This key, named "iOS key (auto created by Firebase)", is not needed and can be deleted.

0 commit comments

Comments
 (0)