Auth0

Auth-svc validates JWTs issued by your identity provider, this guide covers how to setup Auth0 as your IDP.

If you want to use a different identity provider (eg, Okta, Keycloak), refer to the the custom JWT provider instructions in the auth-svc repository.

Create an Auth0 account and application

1. Sign up at auth0.com — the free tier is sufficient for development.

2. Go to Applications → Create Application.

   • Choose React Native as the application type.
   • Note down the Domain and Client ID.

3. Under your application's Settings, scroll to Advanced Settings → Grant Types and make sure Refresh Token is enabled.

Running the React Native boilerplate? It also needs two mobile callback URLs added to this application — see Configure callback URLs in the boilerplate's Auth0 page.

Create an API

1. Go to Applications → APIs → Create API.
2. Set a Name (e.g. auth-svc-api) and an Identifier — this is a logical name, not a real URL (e.g. silent-shard-boilerplate). The identifier becomes your AUTH0_AUDIENCE.
3. In the API's Settings tab, enable Allow Offline Access.
4. Under the Permissions tab, add the following custom scopes:

Scope	Description
write:backup	Create / update keyshare backups
read:backup	Retrieve keyshare backups
read:transactions	View transaction history
write:devices	Register / update devices
read:devices	View registered devices
write:face	Register face biometric
read:face	View face registration status
export:keyshare	Export a wallet's full private key
update:default_policy	Update a group's policy (admin only)

Enable RBAC and roles

The admin dashboard and ordinary users share one login flow. What separates them is the update:default_policy permission in the access token, which comes from an Auth0 role.

1. Turn on RBAC for the API

In your API's Settings tab, enable both:

• RBAC
• Add Permissions in the Access Token

Without the second toggle the permissions never reach the token, and auth-svc rejects every admin call.

2. Create the roles

Go to User Management -> Roles.

Role	Permissions
boilerplate-admin	update:default_policy
boilerplate-default	write:backup, read:backup, read:transactions, write:devices, read:devices, write:face, read:face

Assign boilerplate-admin to the people who administer policies. Everyone else gets boilerplate-default.

export:keyshare is deliberately in neither role. It authorizes reconstructing a wallet's full private key, so grant it narrowly — a dedicated role for the flow that performs keyshare export, rather than to every signed-in user. Add it to boilerplate-default only if export is a feature you intend all users to have.

3. Assign the default role automatically

Auth0 has no built-in default role, and a user with no role receives no scopes at all. New users therefore need a Post-Login Action to assign boilerplate-default.

3.1 M2M Application

An Action runs inside a machine-to-machine application. Create one, then under APIs -> Auth0 Management API -> Machine to Machine Applications, grant it: update:users, update:roles, create:role_members.

3.2 Action

Go to Actions -> Library -> Create Action -> Build from scratch, choose the Login / Post Login trigger, and use:

exports.onExecutePostLogin = async (event, api) => {
  const currentRoles = event.authorization?.roles ?? [];
  if (currentRoles.includes('boilerplate-default')) {
    return;
  }

  const ManagementClient = require('auth0').ManagementClient;
  const management = new ManagementClient({
    domain: event.secrets.DOMAIN,
    clientId: event.secrets.CLIENT_ID,
    clientSecret: event.secrets.CLIENT_SECRET
  });

  try {
    await management.users.assignRoles(
      { id: event.user.user_id },
      { roles: [event.secrets.DEFAULT_ROLE_ID] }
    );
  } catch (e) {
    console.log('Role assignment failed:', e);
  }
};

Add the dependency auth0 at version 4.37.1, and these secrets:

Secret	Value
DOMAIN	your Auth0 tenant domain
CLIENT_ID	client ID of the machine-to-machine application in step 3.2
CLIENT_SECRET	its client secret
DEFAULT_ROLE_ID	the role ID of boilerplate-default

3.3 Wiring

Finally, wire it in: Actions -> Triggers -> Post Login, drag the Action onto the line between the start and end nodes, and click Apply.

The Action runs after the first token is minted, so a brand-new user's first access token carries no permissions. The client should retry once; the next token is correct.

Create the admin dashboard application

The admin dashboard is a server-side web app, that needs its own Auth0 application.

1. Go to Applications -> Create Application, choose Regular Web Applications.

2. In Settings, set:

   • Allowed Callback URLs -- http://localhost:3000/auth/callback
   • Allowed Logout URLs -- http://localhost:3000

   These must match the dashboard's APP_BASE_URL exactly.

3. Under APIs, authorize this application for the API you created above.

4. Note the Domain, Client ID and Client Secret -- they become AUTH0_DOMAIN, ADMIN_DASHBOARD_AUTH0_CLIENT_ID and ADMIN_DASHBOARD_AUTH0_CLIENT_SECRET when you run the dashboard.

Environment variables

Variable	Value	Description
AUTH0_DOMAIN	your-tenant.auth0.com	Your Auth0 tenant domain
AUTH0_AUDIENCE	silent-shard-boilerplate	Must exactly match the API Identifier above
AUTH0_ALGORITHMS	RS256	JWT signing algorithm

AUTH0_AUDIENCE must exactly match the Identifier set in your Auth0 API. A mismatch causes all JWT verification to fail.