name: auth0svc team: https://navinc.atlassian.net/wiki/spaces/FE/overview docs: https://git.nav.com/frontend/nav-website/-/blob/main/apps/auth0svc/README.md repo: https://git.nav.com/frontend/nav-website bugsnag: https://app.bugsnag.com/nav-inc/auth0svc/overview datatype: red procs: web: port: 3000 replicas: 3 type: http envcfg: global: OTEL_SERVICE_NAME: auth0svc

auth0svc

Overview

This service exists to be the gateway Auth0 will use to communicate with other services in Nav – namely Zuul and Allosaurus. Primarily, this service will be used to facilitate endpoints needed for our Custom Database Connection Action Scripts in Auth0. But this service may also be used to facilitate endpoints needed for any custom Auth0 rules we might create in the future.

As you can see in the Data Flow Diagram, this service does connect directly to both the Allosaurus and Zuul databases. When connecting with Allosaurus, we only do this in a readonly matter, and this is done directly since the query that is needed to be run (getting a userID/email for a user) would require us to create a new endpoint in Allo and create an Admin token separate from the Zuul user token. Connecting directly to the database instead of going through Allo required less work to be done to Allosaurus, especially since this will not be needed forever. With Zuul, however, we do write to the database. This is done only when triggering a password reset token, and we do this direct connection so we don't send redundent emails to the users. If we were to do it through Zuul, Auth0 and Zuul would send an email to the user, but if we handle it in this service, only Auth0 will send the email.

In the short term, Nav hopes to only need the Custom Database Connection until we can start transferring over users to Auth0 using Automatic Migration. The migration should be transparent to most of our users and will allow us to turn off the Custom Database Connection and remove the associated endpoints in this service once users are fully moved over to Auth0.

Getting Started

1. Install deps: pnpm install
2. Create your .env: cp .env.example .env - find any unfilled envs in vault or the configurations repo
3. Get a copy of certs/ from another project or dev and put it in the project directory (or try running bin/generate_dev_certificates)
4. Connect to the databases for Allo and Zuul (See Connecting to the Database below)
5. Run project in dev mode: pnpm run dev
6. Open Insomnia and make requests against http://localhost:3100 (make sure AUTH0_ACTION_SCRIPTS_API_KEY as set in .env is sent as the Authorization: Bearer <api-key> header)

Testing

Run pnpm test or pnpm test:watch to verify project setup and to start development. See scripts in package.json for more scripts.

Risk

Interfaces

• Allosaurus (internal) - provides personal information such as email and various identifiers
• Zuul (internal) - provides JWTs

Data Sensitivities

| Data Type | Integrity | Availability | Condifentiality | | ----------------- | --------- | ------------ | --------------- | | Login information | High | Moderate | High |

Known Risks

| Summary | Interest | Controls | Likelihood | Severity | Rating | Recommendations | | --------------------------------------- | --------------- | ---------------------- | ---------- | -------- | -------- | --------------- | | Data breach | Confidentiality | Not publicly accesible | Low | High | Low Risk | None | | Server outtage - infrastructure failure | Availability | Multiple pods | Low | Moderate | Low Risk | None |

Connecting to the Databases

This service does not maintain its own database, but instead uses both the Zuul and Allosaurus databases to get information Auth0 needs about our users for the Custom Database Connection. Follow along with this article on Using StrongDM to Access Databases. For development, use one of the hydra-int{1,2,3}-admin connections that are available in the StrongDM menu. Once connected through StrongDM, the default DB_ connection environment variables set in the .env.example file can be used to make queries against the databases.

Auth0 Custom Database Action Scripts

A custom database connection type allows us to configure action scripts in the Auth0 dashboard which contain custom code that is used when interfacing with our services. Each action script is essentially a named JavaScript function that is passed a number of parameters, with the name of the function and the parameters passed dependent on the script in question. We store copies of the action scripts as configured in the Auth0 dashboard in the auth0-scripts folder. Any changes made to the action scripts in the Auth0 dashboard should also be saved to this repo - and vise versa - so we can keep a history of the changes and make it easier for anyone who doesn't have access to the Auth0 dashboard to see what the action scripts are doing. Auth0 has documentation for Action Script Execution Best Practices.

We have configured the action scripts in Auth0 to map one-to-one with routes in this service. For example the login script (auth0-scripts/login.js) will call the /login route (routes/login.ts) of this service.

Configured Action Scripts in Auth0

Login

This script will be executed each time a user attempts to login. The two parameters: email and password, are used to validate the authenticity of the user.

Create

This script will be executed when the user signs up. The parameters: user.email and user.password, are used to create a record in the user store.

Verify

This script will be executed after a user that signed-up, and follows the "verification" link. The parameter: email is used to verify an account.

Nav does not send verification emails to verify a user owns an email address - so we always return true in this action script and do not have a /verify route in this service.

Change Password

This script will be executed when the user changes their password, the reset email was sent and the user follows the "change password" link. The parameters: email and newPassword are used to confirm the new password.

Get User

This script will be executed when the user changes their password to test if the user exists in the signup and password reset flows.

Delete

This script will be executed when a user is deleted from the Auth0 API or dashboard.

For the time being, Nav will not allow a user to be deleted through the Auth0 API or dashboard. If a user requests their data to be deleted, we will go through the same steps we do today, and then add one additional step to delete the user from Auth0 manually. Deleting a user from Auth0 should not remove them from Nav systems. Because of this, we do not have a /delete route in this service.

MFA

This script will be executed when the /mfa endpoint is hit (probably from the mobile app). This takes an email and password parameter and passes that on to Auth0. We also set some other things in the request body that are needed, as well as setting the force_mfa set to 'true' (this is set as a string, not a boolean) which forces Auth0 to return a 403 with the mfa_token. We then take that mfa_token and set it as the authorization header for the next Auth0 request, which will return an array of authenticators.

Add Authenticator

This script will be executed when the /add-authenticator endpoint is hit (probably from the mobile app). This takes the mfa_token and phone_number as parameters and passes that on to Auth0 (which will send a text to verify their phone number) and pass that information back to the mobile app, which will use the authenticator.oob_code to issue a challenge.

MFA-OOB

This script will be executed when the /mfa-oob endpoint is hit (probably from the mobile app). This takes the mfa_token, oob_code and binding_code as parameters and passes that on to Auth0 (which will log them in) and pass the credentials back to the mobile app.

Enroll Authenticator (via Auth0 Management API)

This script will be executed when the /management/enroll-authenticator endpoint is hit. This enrolls an authenticator(phone, email) in Auth0 using Auth0 Management API

AUTH0_ACTION_SCRIPTS_API_KEY rotation

This key is held in two places, Vault and Firebase Remote Config. If this key is rotated in any way, make sure it is updated in Vault AND in Firebase Remote Config. If they key is not rotated in Firebase Remote Config, MFA will break for Mobile.

Data Flow Diagram

The Data Flow Diagram for this service can be found in Lucid Chart here.

Monitoring & Alerts

Links for the different monitoring and alerts dashboards can be found in Confluence.