California Consumer Privacy Act (CCPA) Authorized Agent Onboarding Tool

This web application automates some manual parts of onbaording a member into Consumer Reports' Authorized Agent program, including; collecting member information, confirming email and phone, and signing a Power of Attorney.

Application Flow Diagrams

For a an overview of how messages flow through this application see docs/application-flow.md.

Development workflow

Dependencies:

• Docker version 19 or later

After setting up the environment variables as described below, run the following command:

$ docker-compose up --build

This will create a web server listening on port 5000. You may access it by visiting http://localhost:5000 in a web browser.

By default, third-party services are simulated by a local server during development. Developers who wish to interact with one or more authentic third-party service may do so by modifying the environment variables documented below.

Automated functional tests

To execute the automated functional tests, switch the environmental variables as described in .env-example, initialize a development environment, and run the following command:

$ docker exec -it ccpa-authorized-agent_fake-api_1 npm test

Third Party Services

This application integrates with three third party services for email, SMS, and electronic signing:

Email

This app currently uses mailgun for transactional emails. In order to set up mailgun for local development, sign up for a test account, grab a set of API credentials, and add them to a .env file in the root of this directory. More instructions on that below. In production, you can use use the workflow outlined in the Deployment workflow below. TODO explain how to swap for a different service.

SMS

This app currently uses twillio for transactional text messages. In order to set up twillio for local development, sign up for an account and add them to the .env file in the root of this directory. More instructions on that below. In production, you can also use use the workflow outlined in the Deployment workflow below. TODO explain how to swap for a different service.

E signing

We are currently using DocuSign's "power form" feature, which let's you upload a PDF, and get a reusable link to have peoplel sign a contract with unique identities. This app currently points at a Power of Attorney (PoA) "Power Form" in which is pre-loaded into the DocuSign account of the owner of this repository. In order to change or update the PoA, log into DocuSign, create a new template, add the fields you require a user to fill out and turn it into a powerform by clicking the "use powerform" option next to that contract. Click through and ignore the email-to-sign message, because this app doesn't use it (this app sends it's own email to start the signing process). Once the contract is a "Power Form", it will give you reusable signing URL. Take that URL and paste it into the authorization email template in this repo: src/webapp/views/member/authorization-email.mustache. There are a number of configurations available in Docusign that you can customize, including reminder emails, and the message that displays when a user is signing the form.

If you're looking for a starting point you can use the example PoA, which is based on Consumer Reports' authorized agent program which we are keeping a copy of in markdown in the src/webapp/documents/authorization.md. To swap out to a different e-signing service, create a reusable form link using that different service, and replace it in the above template. In the future this project may create its own signing tool, which would replace outside signing services with a home rolled or open source e signing solution using one of California's Acceptable Technologies.

Okta

We are currently using Express OIDC modeled on Okta's example integration which can be configured against a test account for local development.

If you are looking for help bootstrapping the Okta integration you can find a document titled "Setting up Okta credentials in CCPA-Authorized Agent" in the Access Agent folder in Google Drive, or follow the tutorial in the example integration linked above.

In lieu of cargo-cult credentials, note that DEBUG_NO_OKTA can be added to the .env file to disable Okta authentication for local development. Practice care in production and know that there aren't integration tests for this at the moment. See PR #4 for details on the integration, as well as the Environment Variables below.

Environment variables

Before you can start the app, you must set up the environment variables. This will allow you to specify which Twilio or Mailgun accounts you would like to use.

• Duplicate .env-example and rename it to .env
• Replace the placeholder values with real values. To use the same Twilio and Mailgun as production, you can retrieve the values from Heroku. Go to the settings page in Heroku and click "reveal config vars."

All required environment variables are described below:

Name	Purpose
DEBUG	controls the verbosity of the application's logging output; refer to the documentation for the open source Node module debug for details on the semantics of this value
HTTP_SESSION_KEY	the encryption key to use for session information stored in HTTP cookies (The application uses HTTP cookies to persist information between requests. This includes a flag describing whether the user has previously been authenticated as an administrator.)
NODE_ENV	controls the use of various runtime optimizations such as HTML template caching; set to development to disable all optimization; set to production to enable all optimizations.
PORT	specifies the TCP port on which the application's HTTP server will listen for incoming requests
DATABASE_URL	the location of the PostgreSQL database; takes the form postgres://username:password@host:port/database
PUBLIC_ADDRESS	the URL where the application is publicly-accessible; used to generate links for responses to identity challenges
MAILGUN_API_KEY	access credential provided by the Mailgun service; used to verify new members' e-mail addresses
MAILGUN_MESSAGING_DOMAIN	access credential provided by the Mailgun service; used to verify new members' e-mail addressed
MAILGUN_SENDER	address from which e-mail messages should be sent to members
MAILGUN_SERVICE_DOMAIN	domain to use in contacting the Mailgun service; varies by region
TWILIO_SERVICE_ID	an ID referring to a single sign up form for SMS verification
TWILIO_SID	credential required by Twilio
TWILIO_AUTH_TOKEN	credential required by Twilio
TWILIO_SERVICE_DOMAIN	the domain used for Twilio's API. Can be overridden for testing.
REVOKE_EMAIL_RECIPIENT	the email address to use when a member revokes their authorization
DEBUG_NO_OKTA	Disable Okta authentication paths
OKTA_DOMAIN	Okta "organization URL"
OKTA_CLIENT_ID	"public" half of Okta OIDC token pair
OKTA_CLIENT_SECRET	"private" half of Okta OIDC token pair
OKTA_USER_PROFILE_TOKEN	An Okta API token which is used to populate a request-body user object in Express Middleware

Deployment workflow

Dependencies:

• Docker version 19 or later
• Heroku CLI

1. Create a Heroku app and database

   $ heroku login
   $ heroku apps:create ccpa-authorized-agent
   $ heroku config:set --app ccpa-authorized-agent NODE_ENV=production
   $ heroku config:set --app ccpa-authorized-agent HTTP_SESSION_KEY=some_hard_to_guess_value_f@ds9
   $ heroku config:set --app ccpa-authorized-agent PUBLIC_ADDRESS=https://ccpa-authorized-agent.herokuapp.com
   $ heroku config:set --app ccpa-authorized-agent MAILGUN_API_KEY=xxx_key_xxx
   $ heroku config:set --app ccpa-authorized-agent MAILGUN_MESSAGING_DOMAIN=xxx_domain_xxx
   $ heroku config:set --app ccpa-authorized-agent MAILGUN_SENDER=robot@example.com
   $ heroku config:set --app ccpa-authorized-agent MAILGUN_SERVICE_DOMAIN=https://api.mailgun.net
   
   # Heroku-provided PostgreSQL database requires SSL
   $ heroku config:set --app ccpa-authorized-agent PGSSLMODE=require
   # Heroku-provided PostgreSQL uses self-signed certificate
   $ heroku config:set --app ccpa-authorized-agent NODE_TLS_REJECT_UNAUTHORIZED=0
   
   # Configure Okta credentials
   $ heroku config:set --app ccpa-authorized-agent OKTA_DOMAIN=consumer.okta.com
   $ heroku config:set --app ccpa-authorized-agent OKTA_CLIENT_ID=provide-this
   $ heroku config:set --app ccpa-authorized-agent OKTA_CLIENT_SECRET=provide-this
   $ heroku config:set --app ccpa-authorized-agent OKTA_USER_PROFILE_TOKEN=provide-this
   
   $ heroku addons:create --app ccpa-authorized-agent heroku-postgresql:hobby-dev
   

2. Deploy the application code

   $ heroku container:login
   $ heroku container:push web --app ccpa-authorized-agent
   $ heroku container:release web --app ccpa-authorized-agent
   

Code of Conduct

This project follows the code of conduct in CODE_OF_Conduct.md in the in the root of this project.

License

Copyright (c) 2021 Bocoup and Consumer Reports
Licensed under the MIT Expat license.