Auth0

Integration Guide

---

Step 1: Install the package

dotnet add package PrimusSaaS.Identity.Validator

---

Step 2: Create an API in Auth0

Your .NET app needs to know which Auth0 API it is protecting. This step creates that API resource.

1. Log in to manage.auth0.com
2. Go to Applications → APIs → click + Create API
3. Fill in:
   • Name: anything (e.g. My API)
   • Identifier: a URI you invent (e.g. https://my-api) — this becomes your Audiences value in appsettings
   • Signing Algorithm: RS256
4. Click Create

---

Step 3: Create an Application in Auth0

This is the "client" that will request tokens to call your API.

1. Go to Applications → Applications → click + Create Application
2. Fill in:
   • Name: anything (e.g. Backend Service)
   • Application Type: Machine to Machine Applications
3. Click Create
4. In the dialog that appears, select the API you just created and click Authorize

---

Step 4: Find your config values

Go to your new Application → Settings tab → Basic Information section. The values you need are all on this one screen.

appsettings.json key	Auth0 field name	Where it is	How to use it
Authority	Domain	Settings → Basic Information	Prefix with https:// and end with / → https://dev-abc123.us.auth0.com/
Issuer	Domain	Same field as above	Exactly the same value as Authority
Audiences	Identifier	The value you typed when creating the API in Step 2	Copy it exactly as-is
(token only) client_id	Client ID	Settings → Basic Information	Copy as-is
(token only) client_secret	Client Secret	Settings → Basic Information	Click the copy icon next to the hidden value

The trailing / at the end of the Domain URL is required — omitting it causes a 401 even when everything else is correct.

---

Step 5: Configure appsettings.json

{
  "PrimusIdentity": {
    "Issuers": [
      {
        "Name": "Auth0",
        "Type": "Auth0",
        "Authority": "https://YOUR-DOMAIN.auth0.com/",
        "Issuer": "https://YOUR-DOMAIN.auth0.com/",
        "Audiences": [ "https://your-api-identifier" ]
      }
    ]
  }
}

Replace YOUR-DOMAIN with the Domain from Step 4, and your-api-identifier with the Identifier from Step 2.

Auth0 issuer fields

Key	Type	Required	What it is	Where to get it
Name	string	Yes	A friendly label for this issuer — appears in logs only, never validated against the token.	You make it up.
Type	string	Yes	Tells the SDK which provider this is.	Must be exactly "Auth0".
Authority	string	Yes	The base URL of your Auth0 tenant. The SDK uses this to automatically fetch Auth0's public signing keys so it can verify token signatures — you do not need to manage keys manually.	Auth0 dashboard → your Application → Settings → Basic Information → Domain field. Prefix with https:// and add a trailing /.
Issuer	string	Yes	The value that Auth0 stamps in every token it issues as the iss (issuer) claim. Your app checks that this matches.	Same value as Authority.
Audiences	string[]	Yes	The API(s) this token is allowed to access. It is an array because a single token can be valid for more than one API — for example a token issued for both https://api-v1 and https://api-v2. In practice, for most setups you will have exactly one entry.	The Identifier you typed when creating the API in Step 2. Must match character-for-character.

RequireHttpsMetadata, ValidateLifetime, ClockSkew

These apply to all providers and are documented once in the Configuration Reference.

---

Step 6: Update Program.cs

using PrimusSaaS.Identity.Validator;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddPrimusIdentity(opts =>
    builder.Configuration.GetSection("PrimusIdentity").Bind(opts));
builder.Services.AddAuthorization();

var app = builder.Build();
app.UseAuthentication();
app.UseAuthorization();

// Protected endpoint — returns 401 if no valid JWT is present
app.MapGet("/auth0", () => Results.Ok(new { validated = true }))
   .RequireAuthorization();

app.Run();

---

Step 7: Get a token and test

Use the form below to fetch a real Auth0 access token. Enter your credentials from Step 4 — use a test application only, never paste production secrets into a web form.

Once you have a token, run your app and test it.

Run the app:

dotnet run --urls "http://localhost:5001"

Call the protected endpoint:

Invoke-RestMethod "http://localhost:5001/auth0" -Headers @{ Authorization = "Bearer $token" }

Expected: { "validated": true }

Confirm it blocks unauthenticated requests:

try { Invoke-RestMethod "http://localhost:5001/auth0" } catch { $_.Exception.Response.StatusCode }

Expected: Unauthorized