3. Install the Secure Audit Logging Extension
Overview
In this section, learn how to install, configure and invoke the Pangea Secure Audit Log Extension to leverage the Secure Audit Log . Once installed, the Extension will automatically log security-critical events emitted by Firebase and other Pangea Extensions. You will also learn how to log your custom app events by recording them in a Firebase Firestore Document. Using the Pangea Console Log Viewer you can cryptographically verify that records have not been modified, inserted, or deleted.
When your application utilizes Pangea's tamperproof logging service, log hashes are automatically published to an immutable public ledger or blockchain. Doing so provides irrefutable evidence of what events occurred in an application without exposing the logs' contents publicly. With the Secure Audit Log Extension, you can deliver the power of the blockchain to your users without writing a single line of code.
Prerequisites
- A free Firebase account with the Pay as you go billing plan enabled.
- A free Pangea account.
- Completed part 1. Configure a Starter Application of this multi-part tutorial OR a Firebase project with the Cloud Functions and Cloud Firestore services enabled.
- A Pangea Domain and Access Token with access rights to the Secure Audit Log service. To learn how to create an account and configure each service, visit the Getting Started guide.
Install and configure the Extension
Step 1: Click the Secure Audit Logging Extension install link, and select the Firebase project you'd like to deploy the Extension to:
Step 2: Accept the Early Access acknowledgement by clicking the Next button:
Step 3: Review the billing and usage details, and tap the Next button. If you have not done so already, you'll be presented with the option to upgrade your Firebase account to a pay-as-you-go plan, and you can do so by clicking the Upgrade project to continue button and following the instructions:
If upgrading your billing plan, you will be redirected to the Set up your billing profile section of Google Cloud Platform (GCP). After setting up your billing profile, you may need to restart the Extension install by clicking the install and repeating Step 1 and Step 2.
Step 4: Review the APIs and the resources that this Extension will create. If any required Firebase services are not yet enabled, tap the Enable button next to each required service and then click the Next button.
The Extension declares several functions to create Secure Audit Log entries:
fslog - listens for changes made to a Firestore collection. You can invoke this Extension to log custom events by writing to a document in a specified collection.
onmaliciousfiledetected - will be automatically invoked by the Known Malware Detection Extension installed in the previous section of this tutorial if you enabled the completed event.
onusercreated - will be automatically invoked when a user is created.
onuserdeleted - will be automatically invoked when a user is created.
onlogevent - listens for custom log events you can emit from your application code.
Step 5: In the Review access granted to this extension section, grant the extension permission to Firestore and Secrets Manager by clicking the Next button.
The Cloud datastore User permission will be used to read and write the responses of the Pangea Secure Audit Log service to a Firestore document. The Secret Manager Secret Accessor permission is required to store your Pangea Auth Token.
Step 5: In the final step, Configure extension, of the install process, you'll be asked to provide a few parameters, some of which are optional. The first two and what region you want to deploy the Extension and where your Pangea services are deployed, respectively. The Extension should be deployed as close to your Firebase Cloud Firestore, so ideally, the same region you used when you configured it. The Pangea service base Domain and Auth Token can be copied from Secure Audit Log Overview page of the Pangea Console. The Pangea Auth Token should be stored in Google Secret Manager. To do so, click the Create secret button next to its input field after entering the token value.
The Collection path and Input field name are the Firestore paths you want to write custom events to, and the Response output field name is the path to which the response of each request will be written to by the Extension.
You can use the default values for now and reconfigure your Extension later.
To complete the installation, click the Install extension button.
It may take Firebase 3-5 minutes to deploy your Extension. When it completes, you should see it listed under the Extensions section of your Firebase Console .
That's it! You now have Secure Audit Logging enabled in your Firebase app. Events emitted from other Pangea Extensions will automatically be recorded.
Test automatic logging of events from other Pangea Extensions
To test events automatically logged by the Known Malware Detection Extension, upload another malicious file to Cloud Storage. To do so, refer to the Test the Extension portion of the previous section, 2. Detect malicious Files uploaded to Cloud Storage of this tutorial and perform Step 1, Step 2, and Step 3.
If you have not done so already, make sure to delete the test file from your previous test.
Then, to view the event, navigate to the Pangea Console Log Viewer of the Pangea Console. You should see the event similar to:
Test automatic logging of Firebase Authentication events
This Secure Audit Logging Extension listens for and automatically logs when a new Firebase user is created or deleted. To test and view these events, perform the following steps:
Step 1: From Firebase Console , expand the Build category, select Authentication from the left-hand menu, and click the Add user button.
Step 2: Enter a Email and Password for your test user and click the Add user button in the Add an Email/Password user dialog box.
You do not need to use a valid email address. You will delete this user account in the next step.
Step 3: Expand the user options using the three-dot options menu button on the right-hand side of the user row you created in the previous step. Click the Delete account option, and when the Delete account dialog box is presented, confirm the delete by clicking the Delete button.
Step 4: Then, to view the User created and User deleted events, navigate back to the Pangea Console Log Viewer of the Pangea Console. You should see the event similar to:
Test logging custom events by writing to Firestore
When you installed the Secure Audit Logging Extension, you configured it to listen to changes to a specific Document in your application's Firestore database. To record your custom application events, such as user login attempts, registrations, or object access attempts, you can invoke the Pangea Secure Audit Log service by simply writing to the Document. In this section, you will test this functionality using the Firebase Console user interface. To do so, perform the following steps:
Step 1: From Firebase Console , expand the Build category and select Firestore Database from the left-hand menu.
Step 2: Select the Start collection option from the Panel View, and because you used the default collection name when installing the Secure Audit Logging Extension, enter 'audit' as the Collection ID and click the Next button.
The collection names are case-sensitive. Use all lowercase letters in the Collection ID field.
Step 3: To add the Document to the Collection, click the Auto-ID button to generate an ID for the Document; then again, because you used the default configuration parameters when you installed the Extension, enter 'log' as the Field value and set the Type to map.
A document with an auto-generated Document ID and single Field of type map should look similar to this:
Step 4: You can now map each of the Pangea Secure Audit Log API parameters to a Field of the 'log' map. Add the following Field : Value pairs, each of Type string:
message : Hello, World!
action : test
status : complete
source : firestore
target : audit-log-ext
actor : firebase-console
Then, to create the Document and trigger Secure Audit Log Service, click the Save button.
In a few moments, you should see a response field containing the Pangea service response added to the Document as a pier to the log field you created.
Then, to view the event, navigate back to the Pangea Console Log Viewer of the Pangea Console. You can expand the log entry by clicking on it to reveal the custom metadata fields. You should see an entry similar to the one below:
The Secure Audit Logging Extension will be invoked by any write operation to a Document in the Collection it is configured to observe. The Cloud Firestore Panel view is a great way to test the Extension by quickly creating and editing Firestore documents, but you may want to record auditable events from your application code. With the Secure Audit Logging Extension installed, you can do so from anywhere in your application that can write to Firestore.
Here is a quick example of how to create the same Document programmatically:
import {getFirestore} from "firebase-admin/firestore";
getFirestore().collection("audit").add({
log: {
message: "Hello, World!",
action: "test",
status: "complete",
source: "firestore",
target: "audit-log-ext",
actor: "firebase-console",
},
});
You can also send custom events to the extension using EventArc. Here is an example:
import {getEventarc} from "firebase-admin/eventarc";
getEventarc().channel().publish({
type: "firebase.extensions.pangea-audit-log.v1.log",
data: {
message: "Hello, World!",
action: "test",
status: "complete",
source: "target",
target: "audit-log-ext",
actor: "firebase-console",
},
});