Firebase Server Configuration

Purpose and audience

This page is for BankLingo platform administrators and backend engineers configuring Firebase Cloud Messaging for a tenant. Mobile and web developers should use the separate FCM Frontend Integration page.

Do not share Firebase Admin service-account credentials with a frontend team. The frontend receives only its platform client configuration:

• Android: google-services.json
• iOS: GoogleService-Info.plist

These client files are not Firebase Admin credentials and must not be stored in Firebase:CredentialsJson.

Delivery architecture

For each user notification, BankLingo independently:

1. Persists the notification for inbox/history.
2. Attempts SignalR delivery to active connections.
3. Attempts FCM delivery when the tenant has enabled and correctly configured Firebase.

FCM is additive. Missing, disabled, or invalid Firebase configuration does not prevent persistence or SignalR delivery.

Create or select a Firebase project

1. Create or select the Firebase project intended for the tenant's mobile application.
2. Register the Android and/or Apple applications.
3. Add the platform client configuration files to the corresponding mobile builds.
4. Enable the FCM HTTP v1 API.
5. For Apple applications, configure the correct APNs authentication key and push capability.
6. From Firebase Console > Project settings > Service accounts, generate an Admin SDK private key for backend delivery.

BankLingo uses the Firebase Admin SDK. Each Firebase client is isolated by tenant, project, and credential fingerprint.

Tenant configuration keys

The backend reads every Firebase value through ITenantConfigurationService after the tenant context is established:

Tenant key	Required	Sensitive	Purpose
Firebase:Enabled	Yes	No	BankLingo rollout switch. Missing or false disables FCM for the tenant.
Firebase:ProjectId	When enabled	No	Firebase project receiving the messages.
Firebase:CredentialsJson	When enabled	Yes	Complete Firebase Admin service-account JSON document.

No Firebase server value should be placed in appsettings.json, a filesystem path, source control, a mobile application, or a web client.

Obtain the values

Tenant key	Source
Firebase:Enabled	Set by the BankLingo tenant administrator. Begin with false and enable only after server and mobile validation.
Firebase:ProjectId	Firebase Console > Project settings > General > Project ID. It must also match project_id in the Admin credential.
Firebase:CredentialsJson	Firebase Console > Project settings > Service accounts > Firebase Admin SDK > Generate new private key. Store the entire downloaded document, not its filename.

The account generating the key must have permission to manage service-account keys for the Firebase/Google Cloud project. Transfer the downloaded file through the approved secret-management process and remove unsecured working copies.

The required credential shape is:

{
  "type": "service_account",
  "project_id": "<firebase-project-id>",
  "private_key_id": "<redacted>",
  "private_key": "-----BEGIN PRIVATE KEY-----\n<redacted>\n-----END PRIVATE KEY-----\n",
  "client_email": "<service-account>@<firebase-project-id>.iam.gserviceaccount.com"
}

The backend rejects an Android google-services.json, malformed JSON, a document without the required service-account fields, or credentials whose project_id differs from Firebase:ProjectId.

Store the tenant values

An administrator with Settings.ManageSecureCredentials uses the standard back-office command endpoint:

POST /api/bpm/cmd

Create the sensitive credential using CreateSecureCredentialCommand. Replace the placeholder with the entire service-account document serialized as a JSON string:

{
  "cmd": "CreateSecureCredentialCommand",
  "data": "{\"key\":\"Firebase:CredentialsJson\",\"dataValue\":\"<JSON-encoded service-account document>\",\"description\":\"Firebase Admin service-account credential\",\"isSensitive\":true}"
}

Create Firebase:ProjectId and Firebase:Enabled using the same command with isSensitive:false. Use UpdateSecureCredentialCommand and the existing credential ID when changing a value; do not create duplicate keys.

After creation or update, reload tenant configuration:

{
  "cmd": "SyncSecureCredentialCommand",
  "data": "{}"
}

Firebase:CredentialsJson must be stored with IsSensitive=true. ITenantConfigurationService decrypts it before Firebase initialisation. Never paste a real credential into documentation, tickets, chat, logs, test fixtures, or source control.

Safe rollout

1. Store Firebase:ProjectId and the sensitive Admin credential.
2. Keep Firebase:Enabled=false.
3. Install a mobile build belonging to the same Firebase project.
4. Authenticate on a verified device and register its FCM token.
5. Enable Firebase for the tenant.
6. Send a controlled test notification and verify persistence, SignalR, foreground FCM, background FCM, and terminated-app behavior.
7. Confirm that disabling Firebase still leaves persistence and SignalR unchanged.

Credential replacement does not require an application restart: a changed credential fingerprint selects a new tenant-specific Firebase client.

Delivery decision table

User/application state	Firebase configuration	Persisted	SignalR	FCM
Connected	Missing, disabled, or invalid	Yes	Attempted	No
Connected with an active installation	Enabled and valid	Yes	Attempted	Attempted
Backgrounded, closed, or logged out with an active installation	Enabled and valid	Yes	No active connection	Attempted
Backgrounded, closed, or logged out	Missing, disabled, or invalid	Yes	No active connection	No
SignalR fails	Enabled and valid	Yes	Failed	Still attempted
FCM fails	Any	Yes	Unaffected	Failed

Firebase accepting a message does not prove that the operating system displayed it. User settings, focus modes, battery policies, and platform delivery rules can suppress presentation.

Registration cleanup

Condition	Cleanup behavior
Normal logout	Keep the mapping so logged-out generic push remains possible.
Explicit notification opt-out	The mobile app calls UnregisterPushInstallationCommand.
Verified profile/device switch	The next registration reassigns the installation and deactivates conflicting mappings.
Profile suspension, deactivation, or blacklist	Profile-status handling revokes mappings; sending also checks active status.
FCM reports a permanently invalid token	The sender deactivates the registration.
Temporary Firebase or network failure	The mapping remains active for a later attempt.
Application uninstall	No authenticated callback is guaranteed; cleanup normally occurs after FCM rejects a later send.

Backend security requirements

• Grant service accounts only the permissions required to send FCM messages.
• Keep each credential associated with the correct tenant and Firebase project.
• Mark the credential value sensitive and restrict management permissions.
• Rotate compromised or expiring credentials immediately.
• Never log the service-account document or an FCM registration token.
• Keep lock-screen title/body text generic; place navigation hints, not trusted authorisation data, in the FCM data map.
• Always enforce tenant/profile ownership when the client retrieves or acts on the referenced resource.

Backend release checklist

• FCM HTTP v1 is enabled.
• The Firebase project ID and service-account project_id match.
• The Admin credential is stored as a sensitive tenant value.
• No Firebase Admin JSON is present in configuration files or source control.
• Android and Apple builds belong to the intended Firebase project.
• Apple APNs keys and environments are configured for the intended bundle identifier.
• Disabled, invalid-credential, transient-error, and permanently-invalid-token behavior has been tested.
• SignalR and persistence remain operational when FCM is disabled.

Firebase administrator references

• Add the Firebase Admin SDK to a server
• Send messages with the Firebase Admin SDK
• Firebase service-account guidance