Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

3 changes: 3 additions & 0 deletions scripts/.gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
node_modules/
.env
.env.local
Empty file added scripts/.npmrc
Empty file.
92 changes: 92 additions & 0 deletions scripts/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,92 @@
# Auth0 Tenant Bootstrap Script (iOS)

An interactive CLI that configures your Auth0 tenant with everything the
**AppUIComponents** sample app needs, then wires the app up locally by writing
`Auth0.plist` and registering the OAuth callback URL scheme. The script
discovers existing resources, builds a change plan, and only creates what's
missing — it never modifies configuration that is already correct.

## Table of Contents

- [Prerequisites](#prerequisites)
- [Usage](#usage)
- [What It Configures](#what-it-configures)
- [Auth0 CLI Scopes](#auth0-cli-scopes)
- [Manual Configuration](#manual-configuration)

## Prerequisites

1. **Node.js 20 or later** — [nodejs.org](https://nodejs.org/)
2. **Auth0 CLI** — [github.com/auth0/auth0-cli](https://github.com/auth0/auth0-cli)
3. **An Auth0 tenant** — sign up at [auth0.com/signup](https://auth0.com/signup)
if you don't have one. You can use an existing tenant; the script only adds
what's missing.

> ⚠️ **Note:** You do not need to log in to the Auth0 CLI beforehand. The script
> checks your CLI session and, if it is missing or expired, offers to log you in
> (requesting the [required scopes](#auth0-cli-scopes)) and switch to the
> requested tenant automatically.

## Usage

Run from the `scripts/` directory:

```bash
cd scripts
npm install
npm run auth0:bootstrap <your-tenant-domain>
```

The tenant domain argument is required (e.g. `my-tenant.us.auth0.com`) as a
safety measure to prevent accidentally configuring the wrong tenant.

The script guides you through:

1. **Pre-flight checks** — Node version, Auth0 CLI install, and CLI session.
If your session is expired it offers to log you in.
2. **Tenant validation** — confirms the provided domain matches your active CLI
tenant. On a mismatch it offers to `auth0 tenants use <tenant>` (switch) or
log in to it, then continues.
3. **Resource discovery** — scans the tenant and warns (softly) if the My
Account API is missing MFA scopes.
4. **Change plan review** — displays what will be created, updated, or skipped.
5. **Confirmation** — prompts for approval before applying any changes.
6. **Apply changes** — creates and configures the required Auth0 resources.
7. **Local wiring** — writes `AppUIComponents/Auth0.plist` and adds the `demo`
callback URL scheme to `AppUIComponents/Info.plist` (idempotent).

## What It Configures

| Resource | Details |
| -------------------------- | ----------------------------------------------------------------------------------------------- |
| **Native Application** | `iOS UI Components Demo` (`app_type: native`) with the `demo://…/callback` callback + refresh-token rotation, and a My Account API refresh-token policy |

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This table still says the callback is demo://…/callback
Can we update this row and the Info.plist bullet below (line 75-76) to say "the app's bundle identifier" instead of demo

| **My Account API** | Resource server at `https://{domain}/me/` (MFA / authentication-methods) |
| **Client Grant** | Native app authorized for the available My Account API scopes |
| **Database Connection** | `Username-Password-Authentication` enabled for the application |
| **Connection Profile** | `Universal Components Connection Profile` |
| **User Attribute Profile** | `Universal Components Profile` |
| **Admin Role** | `admin` role with the My Account API permissions |

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we add a row here for the new WebAuthn/Passkey MFA factor step (guardian-factors.mjs) and the passkey-enablement change to the Database Connection row (connections.mjs's PASSKEY_CONNECTION_OPTIONS)? Both are load-bearing for the passkey feature but aren't mentioned in this table.

| **Tenant Settings** | Identifier-first prompt and MFA customization in the post-login action |

Locally, it then writes:

- `AppUIComponents/Auth0.plist` — `Domain` and `ClientId` read by the SDK at
launch (`Auth0UniversalComponentsSDKInitializer`).
- `AppUIComponents/Info.plist` — a `CFBundleURLTypes` entry registering the
`demo` URL scheme so the login/logout callback returns to the app.

## Auth0 CLI Scopes

If the script triggers a login, it requests these scopes automatically. To
authenticate manually beforehand:

```bash
auth0 login --scopes "read:connection_profiles,create:connection_profiles,update:connection_profiles,read:user_attribute_profiles,create:user_attribute_profiles,update:user_attribute_profiles,read:client_grants,create:client_grants,update:client_grants,delete:client_grants,read:connections,create:connections,update:connections,read:clients,create:clients,update:clients,read:client_keys,read:roles,create:roles,update:roles,read:resource_servers,create:resource_servers,update:resource_servers,update:tenant_settings,update:prompts"

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This scope string doesn't match BOOTSTRAP_SCOPE_METADATA in validation.mjs anymore. It's missing read:connections_options / update:connections_options (passkey-on-connection, added in this PR) and read:guardian_factors / update:guardian_factors (WebAuthn factors, also added in this PR)

manual login using this exact command would silently fail to enable passkeys. It also still includes read:roles/create:roles/update:roles, but roles.mjs in this same PR made the admin-role check always SKIP ("System APIs may not be used"), so those are now dead. Could this be generated from BOOTSTRAP_SCOPES.join(",") instead of hand-maintained, so it can't drift again?

```

## Manual Configuration

If you prefer to configure the tenant by hand, follow **Option 2: Manual Setup**
in the [root README](../README.md#option-2-manual-setup), which covers creating
the native application, allowed callback URLs, `AppUIComponents/Auth0.plist`,
and the `Info.plist` URL scheme.
Loading
Loading