Integrating Pangea Audit and Embargo with RedwoodJS
Quickview
Description | Integrate Pangea Secure Audit Log and Embargo into the authentication flow of the RedwoodJS Sample App |
Language(s) | TypeScript |
Pangea SDK | Javascript/Node.js |
Overview
Learn how to integrate Pangea's Secure Audit Log and Embargo services into RedwoodJS' native login flow. In this tutorial, you'll ensure compliance with frameworks like HIPAA, SOX, and others by logging critical authentication activities - logins, password changes, and account creation. Further, you'll learn how to use the Embargo service to block account creation and access to a user attempting to log in from an embargoed country.
Requirements
This walkthrough uses the RedwoodJS sample app, built in the RedwoodJS tutorial, as a starting point for integrating Pangea. It assumes that you have been through steps 1 through 4 of the excellent RedwoodJS tutorial. If you prefer to skip the RedwoodJS tutorial, the RedwoodJS example app can be found here.
This tutorial is intended to be a step-by-step walkthrough, adding Pangea integration to the sample app. If you'd prefer to review a completed version of this integration, use this branch of the above repo.
Additionally, this tutorial assumes a basic understanding of how to enable, configure, and use Pangea services. To learn more about that, check out our getting started guide.
Note: This example will be in TypeScript (because I'm a rational human being). If you would prefer pure Javascript, some translation will be required.
Prerequisites
- A Pangea Account - sign up here
- An enabled Pangea Audit Service
- An enabled Pangea Embargo Service with the ITAR list enabled
- RedwoodJS (latest version)
- A RedwoodJS example App completed through step 4, section "Authentication," using dbAuth
Part 1 - Creating the Pangea Module
Now that you have a RedwoodJS blogging app, complete with Authentication, up and running, you must feel pretty awesome! Before we can start logging into Pangea Secure Audit Log, we need to create a Pangea module that can be imported throughout the rest of the RedwoodJS code.
Step 1: Install the Pangea SDK:
The first thing we need to do is install the Pangea Node.js SDK. You'll want to open your Terminal app and ensure you're in your Redwood Sample app root directory. Then run,
yarn workspace api add pangea-node-sdk
This will install the Pangea Javascript SDK in the API workspace of your Redwood project.
Step 2: Create Pangea environment variables
At the root of your RedwoodJS App, there will be a .env
file. Here you'll need to append the following variables to the end of the file:
PANGEA_AUDIT_TOKEN=<audit_token>
PANGEA_EMBARGO_TOKEN=<embargo_token>
PANGEA_DOMAIN=<pangea_domain>
Note: You'll need to replace the values in angle brackets with real values from your Pangea project.
You can find these variables in the Pangea Console on the overview section of their respective service. You can find the Pangea Domain (the same for both services) in the top-right of the <service>
overview dashboard. You can copy the token from the token listing at the bottom of the <service>
overview dashboard.
The variables ending in TOKEN
are the API Keys granting access to the respective Pangea APIs. Finally, the PANGEA_DOMAIN
will tell the SDK where to go to hit your Pangea service APIs (domain will change depending on CSP, Geo, and location selected).
Step 3: Create the Pangea Module
To create a Pangea module, you need to create a pangea.ts
file in the /\<project_root\>/api/src/lib
directory. We'll need to do a few things in this module to prepare it for inclusion in our other projects. First, we'll want to import AuditService
, EmbargoService
, and PangeaConfig
from pangea-node-sdk
.
Add the following to the first line in your new /<project_root>/api/src/lib/pangea.ts
file.
import { AuditService, EmbargoService, PangeaConfig } from "pangea-node-sdk";
Next, you'll want to load the configuration values added in Step 2 from your .env
file. You can add the following to your pangea.ts
file.
const DOMAIN = process.env.PANGEA_DOMAIN;
const auditToken = process.env.PANGEA_AUDIT_TOKEN;
const embargoToken = process.env.PANGEA_EMBARGO_TOKEN;
With the configuration values loaded, you'll now be able to create PangeaConfig
instances for both the Embargo and Audit Services.
const auditConfig = new PangeaConfig({
domain: DOMAIN,
});
const embargoConfig = new PangeaConfig({
domain: DOMAIN,
});
With the PangeaConfig
instances created, you need to create instances of the AuditService
and EmbargoService
, which will be what you use to call the Pangea APIs. To do this, you add:
const audit = new AuditService(auditToken, auditConfig);
const embargo = new EmbargoService(embargoToken, embargoConfig);
Lastly, you'll need to create a named export for when this pangea module is imported into other parts of your code. Do this by adding the following:
export { audit, embargo };
At this point, your Pangea.ts
code should look like as such:
/<project_root>/api/src/lib/pangea.ts
import { AuditService, EmbargoService, PangeaConfig } from "pangea-node-sdk";
const DOMAIN = process.env.PANGEA_DOMAIN;
const auditToken = process.env.PANGEA_AUDIT_TOKEN;
const embargoToken = process.env.PANGEA_EMBARGO_TOKEN;
const auditConfig = new PangeaConfig({
domain: DOMAIN,
});
const embargoConfig = new PangeaConfig({
domain: DOMAIN,
});
const audit = new AuditService(auditToken, auditConfig);
const embargo = new EmbargoService(embargoToken, embargoConfig);
export { audit, embargo };
Congratulations! You've created a Pangea module which will be the foundation for the rest of this tutorial. Not only that, you can use this module in any TypeScript project that you might be building. Even cooler - as Pangea creates new services, you can extend this file to include other services you might need in your project. Give yourself a giant pat on the back. Now comes the fun part!
Part 2 - Adding Secure Audit Log to the example app authN flow
You put in the work! You've got a brand-spankin' new pangea.ts
module; let's put it to work. In this Part, you'll add audit logging to the login, password change, and account creation processes. As mentioned, logging security operations like logins, password changes, and account creation can be critical for compliance frameworks like HIPAA, SOX, and SOC2. However, even if those frameworks are not applicable, logging these events can still be crucial in reconstructing and security breach or incident that may need further investigation.
Step 1: Import the pangea module
First things first, find the /\<project_root\>/api/src/functions/auth.ts
file. To add logging to the login process, you'll need to import your handy-dandy new pangea module. I recommend importing audit
and embargo
, as you'll be using embargo in Part 3. Add the following import to /\<project_root\>/api/src/functions/auth.ts
.
import { audit, embargo } from "src/lib/pangea";
Note that api
is not necessary in the import path. That's because RedwoodJS has already divided your project into workspaces, with api
being one of them.