Engine External IdP Setup with Auth0 Quickstart

This quickstart guide walks administrators through connecting Auth0 as an External Identity Provider to the Niksphere Engine, enabling users to log in via Auth0 instead of (or alongside) the embedded local login form.

This procedure is identical for both Engine deployment models described in Engine Deployment Concept — Self-Hosted and Niksphere Cloud (Fully Managed). Only the Engine Base URL used throughout this guide differs between the two.

Prerequisites

Before starting, ensure you have:

• A running Niksphere Engine and its Engine Base URL:
  • Self-Hosted: the URL you configured and are running the Engine at, e.g. http://localhost:3000. See the Engine Installation & Setup Guide.
  • Niksphere Cloud (Fully Managed): the Engine URL shown for your environment in the Niksphere Cloud Portal, e.g. https://your-environment.niksphere.cloud.
• The Niksphere CLI (nik) installed and authenticated as an administrator against that Engine. See the CLI Installation & Setup Guide.
• A free Auth0 account. Sign up at auth0.com/signup if you don't have one yet.

TIP

Verify your CLI is authenticated against the target Engine before continuing:

nik env auth status

Step 1: Create an Auth0 Application

Niksphere delegates login to any standard OpenID Connect (OIDC) provider, so a plain Auth0 Regular Web Application is sufficient.

1. In the Auth0 Dashboard, go to Applications → Applications → Create Application.
2. Name it Niksphere Engine, select Regular Web Applications, and click Create.
3. Open the Settings tab of the new application and note down the following values:
   • Domain (e.g. dev-abc123.us.auth0.com)
   • Client ID
   • Client Secret

Step 2: Configure Allowed Callback & Logout URLs

The Niksphere Engine's IdP Broker exposes a fixed callback route at {Engine Base URL}/auth/external/callback, regardless of deployment model. Auth0 only redirects back to URLs it explicitly allows.

Still on the application's Settings tab, set:

Field	Value	Self-Hosted Example	Niksphere Cloud Example
Allowed Callback URLs	<Engine Base URL>/auth/external/callback	http://localhost:3000/auth/external/callback	https://your-environment.niksphere.cloud/auth/external/callback
Allowed Logout URLs	<Engine Base URL>	http://localhost:3000	https://your-environment.niksphere.cloud

using the Engine Base URL from the Prerequisites.

Scroll down and click Save Changes.

TIP

Self-Hosted only: the Engine Base URL is configured via NIKSPHERE_ENGINE_HTTP_BASE_URL (see the Engine Configuration Reference) and defaults to http://localhost:<port>. The callback path itself (/auth/external/callback) is fixed and cannot be changed on either deployment model.

Step 3: Register Auth0 as an External Identity Provider

Register the Auth0 application with Niksphere using the values noted in Step 1:

nik env idp external add "Auth0" `
  --issuer-url "https://YOUR_DOMAIN/" `
  --client-id "YOUR_CLIENT_ID" `
  --client-secret "YOUR_CLIENT_SECRET" `
  --auto-provision

nik env idp external add "Auth0" \
  --issuer-url "https://YOUR_DOMAIN/" \
  --client-id "YOUR_CLIENT_ID" \
  --client-secret "YOUR_CLIENT_SECRET" \
  --auto-provision

nik env idp external add "Auth0" \
  --issuer-url "https://YOUR_DOMAIN/" \
  --client-id "YOUR_CLIENT_ID" \
  --client-secret "YOUR_CLIENT_SECRET" \
  --auto-provision

Replace YOUR_DOMAIN, YOUR_CLIENT_ID, and YOUR_CLIENT_SECRET with the values from Step 1.

IMPORTANT

The --issuer-url must include the trailing slash (https://YOUR_DOMAIN/). Auth0 publishes its OIDC discovery document with a trailing slash in the issuer field, and Niksphere validates the issuer string for an exact match. Omitting the slash causes every login attempt to fail with an issuer mismatch error.

TIP

--auto-provision automatically creates a new Niksphere Actor the first time a given Auth0 user logs in. Without this flag, the user must already be provisioned and manually linked to an existing Actor beforehand.

Verification

Confirm the IdP was registered and is active:

nik env idp external list

Expected Response:

ID                                     NAME    ISSUER URL                     CLIENT ID    ACTIVE   AUTO-PROVISION
a1b2c3d4-...                           Auth0   https://YOUR_DOMAIN/           YOUR_CLIENT_ID   true     true

Now trigger a real login through Auth0 end-to-end:

1. Start a fresh CLI login against the Engine, using your Engine Base URL from the Prerequisites:

   nik env auth login <Engine Base URL>

2. Your browser opens the Niksphere login page. Below the local username/password form, click Login with Auth0.
3. Complete the Auth0 login (sign up a test user on the Auth0 login screen if you don't have one yet).
4. On success, the browser redirects back and the CLI prints:

   Successfully authenticated!

5. Verify the Actor was auto-provisioned:

   nik env actor list

   A new User Actor should appear, named after the Auth0 account's username or email.
6. Verify the external identity link (replace <actor-id> with the ID from the previous step):

   nik env actor identity list <actor-id>

   The External SSO Identities section should list an entry with the Auth0 IdP ID, the external subject, and the email address returned by Auth0.

Next Steps

• Authentication Concept: Understand how External SSO fits into the broader identity model in Engine Authentication & Identity Concept.
• CLI Reference: Explore all nik env idp external and nik env actor identity commands in the CLI Reference.
• Other Providers: The same flow applies to any standard OIDC provider (Microsoft Entra ID, Google Workspace, Keycloak, Okta) — only the Issuer URL, Client ID, and Client Secret change.