Auth0 Reference Guide

Auth0 Reference Guide

What Auth0 Does

Auth0 is our Identity Provider (IdP). It handles:

• Storing and verifying passwords securely
• Issuing JWT access tokens
• Managing user identities

We never store passwords in our own database. Auth0 owns that.

---

How the JWT Works

When a user logs in, Auth0 issues a JWT (JSON Web Token). This token:

• Is signed with Auth0's private key using RS256
• Contains the user's Auth0 ID (sub), email, and any custom claims
• Expires after 24 hours
• Is verified by the API Gateway using Auth0's public JWKS keys

The token payload looks like this (decoded):

{
  "iss": "https://phishshield.us.auth0.com/",
  "sub": "auth0|abc123",
  "aud": ["https://phishshield-api"],
  "email": "user@example.com",
  "exp": 1234567890,
  "iat": 1234567890
}

---

Auth0 Applications We Have Set Up

Application	Type	Purpose
PhishShield Accounts Service	Regular Web App	Login and token issuance
PhishShield Management	Machine-to-Machine	Creating users via Management API

---

Auth0 Dashboard

URL: https://manage.auth0.com
Tenant: phishshield.us.auth0.com

Contact the backend lead for credentials.

---

Environment Variables

Variable	Where to get it
AUTH0_DOMAIN	Auth0 Dashboard → Settings
AUTH0_CLIENT_ID	Regular Web App → Settings
AUTH0_CLIENT_SECRET	Regular Web App → Settings
AUTH0_AUDIENCE	Auth0 Dashboard → APIs → Identifier
AUTH0_M2M_CLIENT_ID	M2M App → Settings
AUTH0_M2M_CLIENT_SECRET	M2M App → Settings

---

Free Tier Limits

• 25,000 Monthly Active Users
• 1,000 M2M tokens per month (we cache these — one per day)
• Unlimited logins

---

How JWT Validation Works in the Gateway

The gateway uses passport-jwt and jwks-rsa to validate tokens:

1. Frontend sends Authorization: Bearer <token> header
2. Gateway extracts the token
3. jwks-rsa fetches Auth0's public keys from
   https://phishshield.us.auth0.com/.well-known/jwks.json
4. The token signature is verified against the public key
5. The audience and issuer are checked
6. If valid, req.user is populated with the token payload
7. If invalid, a 401 is returned

This means no Auth0 API call is made during validation — it's all done locally using public key cryptography.

---

Adding Custom Claims (Roles)

To include roles in the JWT, you need an Auth0 Action. Go to:
Auth0 Dashboard → Actions → Flows → Login

Add a custom action:

exports.onExecutePostLogin = async (event, api) => {
  const namespace = 'https://phishshield/';
  if (event.authorization) {
    api.idToken.setCustomClaim(`${namespace}roles`, event.authorization.roles);
    api.accessToken.setCustomClaim(`${namespace}roles`, event.authorization.roles);
  }
};

This adds roles to the JWT which the gateway reads from
payload['https://phishshield/roles'].