Provider Setup

Everything you need before writing a single line of code. This page walks you through getting every credential the Identity Broker needs — step by step, for each provider.

---

The complete credentials checklist

Credential	Where it comes from	Required?
TokenEncryptionKey	You generate it (random string)	Always
Auth0:Domain + ClientId + ClientSecret	Auth0 Dashboard	If using Auth0
AzureAd:TenantId + ClientId + ClientSecret	Azure Portal	If using Azure AD
Google:ClientId + ClientSecret	Google Cloud Console	If using Google
Okta:Domain + ClientId + ClientSecret	Okta Admin Console	If using Okta
Redis connection string	Your Redis host (local, Azure, or cloud)	Only if running multiple servers

---

1. TokenEncryptionKey — always required

This is a random string you create yourself. It encrypts the session cookie. No sign-up needed.

Generate one now:

# Linux / macOS
openssl rand -base64 32

# Windows PowerShell
[Convert]::ToBase64String((1..32 | ForEach-Object { Get-Random -Max 256 }))

Copy the output (looks like K7h2mN9p...). That is your key. Store it as an environment variable — never in appsettings.json.

# Linux / macOS
export PrimusAuth__Security__TokenEncryptionKey="paste-your-generated-key-here"

# Windows PowerShell
$env:PrimusAuth__Security__TokenEncryptionKey = "paste-your-generated-key-here"

warning

Use the same key on every server. If you have two servers with different keys, users logged in on server A cannot access server B.

---

2. Auth0 credentials

Step 1 — Create a free Auth0 account

Go to auth0.com → Sign Up (free tier is sufficient for development).

Step 2 — Create an Application

1. In the Auth0 Dashboard, click Applications → Applications in the left nav.
2. Click Create Application.
3. Give it a name (e.g. My App).
4. Select Regular Web Application → click Create.

Must be "Regular Web Application"

Selecting SPA, Native, or Machine to Machine will cause a 403 Forbidden error. The broker is a server-side component and requires a server-side app type.

Step 3 — Configure Callback URLs

In the Settings tab of your new app, scroll to Application URIs and fill in:

Field	Value
Allowed Callback URLs	http://localhost:5000/api/auth/auth0/callback
Allowed Logout URLs	http://localhost:5000
Allowed Web Origins	http://localhost:5000

Click Save Changes.

Step 4 — Copy your credentials

Still in the Settings tab, scroll to the top:

Dashboard field	Config key
Domain	Auth0:Domain
Client ID	Auth0:ClientId
Client Secret	Auth0:ClientSecret

Step 5 — Set environment variables

export Auth0__Domain="your-tenant.us.auth0.com"
export Auth0__ClientId="your-client-id"
export Auth0__ClientSecret="your-client-secret"
export PrimusAuth__Security__TokenEncryptionKey="your-generated-key"

$env:Auth0__Domain = "your-tenant.us.auth0.com"
$env:Auth0__ClientId = "your-client-id"
$env:Auth0__ClientSecret = "your-client-secret"
$env:PrimusAuth__Security__TokenEncryptionKey = "your-generated-key"

---

3. Azure AD credentials

Step 1 — Log in to Azure Portal

Go to portal.azure.com. A free account works.

Step 2 — Register an App

1. Search for Microsoft Entra ID in the top search bar.
2. Click App registrations → New registration.
3. Give it a name.
4. Under Supported account types, choose:
   • Single tenant — only your org's users can log in
   • Multitenant — users from any Microsoft org can log in
5. Click Register.

Step 3 — Add the redirect URI

1. Go to Authentication → Add a platform → Web.
2. Enter: http://localhost:5000/api/auth/azure/callback
3. Click Save.

Step 4 — Create a client secret

1. Go to Certificates & secrets → New client secret.
2. Give it a description and expiry → Add.
3. Copy the Value immediately — it is only shown once.

Step 5 — Copy your credentials

Azure Portal location	Config key
Overview → Application (client) ID	AzureAd:ClientId
Overview → Directory (tenant) ID	AzureAd:TenantId
Certificates & secrets → Value	AzureAd:ClientSecret

Step 6 — Set environment variables

export AzureAd__TenantId="your-tenant-id"
export AzureAd__ClientId="your-client-id"
export AzureAd__ClientSecret="your-client-secret"
export PrimusAuth__Security__TokenEncryptionKey="your-generated-key"

$env:AzureAd__TenantId = "your-tenant-id"
$env:AzureAd__ClientId = "your-client-id"
$env:AzureAd__ClientSecret = "your-client-secret"
$env:PrimusAuth__Security__TokenEncryptionKey = "your-generated-key"

---

4. Google credentials

Step 1 — Create a Google Cloud project

Go to console.cloud.google.com → New Project → give it a name → Create.

Step 2 — Enable Google Identity

1. In the left nav, go to APIs & Services → Credentials.
2. Click Configure Consent Screen → choose External → fill in App name and your email → Save.

Step 3 — Create OAuth credentials

1. Click Create Credentials → OAuth client ID.
2. Choose Web application.
3. Under Authorized redirect URIs, add: http://localhost:5000/api/auth/google/callback
4. Click Create.

Step 4 — Copy your credentials

A popup shows your credentials:

Popup field	Config key
Client ID	Google:ClientId
Client Secret	Google:ClientSecret

Step 5 — Set environment variables

export Google__ClientId="your-client-id.apps.googleusercontent.com"
export Google__ClientSecret="your-client-secret"
export PrimusAuth__Security__TokenEncryptionKey="your-generated-key"

$env:Google__ClientId = "your-client-id.apps.googleusercontent.com"
$env:Google__ClientSecret = "your-client-secret"
$env:PrimusAuth__Security__TokenEncryptionKey = "your-generated-key"

---

5. Okta credentials

Step 1 — Create a free Okta developer account

Go to developer.okta.com → Sign Up (free).

Step 2 — Create an Application

1. In the Okta Admin Console, go to Applications → Applications → Create App Integration.
2. Select OIDC - OpenID Connect → Web Application → Next.
3. Give it a name.
4. Under Sign-in redirect URIs, add: http://localhost:5000/api/auth/okta/callback
5. Click Save.

Step 3 — Copy your credentials

Okta location	Config key
Your Okta org URL (top of every page, e.g. https://dev-123456.okta.com)	Okta:Domain
App → General tab → Client ID	Okta:ClientId
App → General tab → Client Secret	Okta:ClientSecret

Step 4 — Set environment variables

export Okta__Domain="https://dev-123456.okta.com"
export Okta__ClientId="your-client-id"
export Okta__ClientSecret="your-client-secret"
export PrimusAuth__Security__TokenEncryptionKey="your-generated-key"

$env:Okta__Domain = "https://dev-123456.okta.com"
$env:Okta__ClientId = "your-client-id"
$env:Okta__ClientSecret = "your-client-secret"
$env:PrimusAuth__Security__TokenEncryptionKey = "your-generated-key"

---

6. Redis connection string — only needed for multiple servers

If you are running a single server (local dev, single-instance staging), skip this. The broker defaults to an in-memory rate limiter that works fine.

You only need Redis when you run 2 or more instances of your app (e.g. Kubernetes, multiple containers, Azure App Service with scale-out).

Option A — Local (free, no account)

Requires Docker.

docker run -d -p 6379:6379 redis:alpine

export REDIS_CONNECTION_STRING="localhost:6379"

Option B — Azure Cache for Redis

1. Go to portal.azure.com → search Azure Cache for Redis → Create.
2. Choose the C0 Basic tier (cheapest, sufficient for most apps).
3. After deployment, go to your cache → Access keys → copy Primary connection string.

Looks like: your-cache.redis.cache.windows.net:6380,password=abc123==,ssl=True,abortConnect=False

export REDIS_CONNECTION_STRING="your-cache.redis.cache.windows.net:6380,password=abc123==,ssl=True,abortConnect=False"

Option C — Redis Cloud (free tier)

1. Go to redis.io/try-free → sign up.
2. Create a free database → copy the Public endpoint and Password.

Looks like: redis-12345.c1.us-east-1-2.ec2.cloud.redislabs.com:12345,password=abc123

export REDIS_CONNECTION_STRING="redis-12345.c1.us-east-1-2.ec2.cloud.redislabs.com:12345,password=abc123"

Wire it up in Program.cs

using PrimusSaaS.Identity.Broker.Redis;
using StackExchange.Redis;

// Connect to Redis using the env var
builder.Services.AddSingleton<IConnectionMultiplexer>(
    ConnectionMultiplexer.Connect(
        builder.Configuration["REDIS_CONNECTION_STRING"] ?? "localhost:6379"
    ));

// Replace in-memory rate limiter with Redis-backed one
builder.Services.AddPrimusRedisRateLimiter(maxRequests: 10, windowSeconds: 60);

// Optional: store audit events in Redis too
builder.Services.AddPrimusRedisAuditSink();

---

Summary — full .env example

Create a file called .env in your project root (add it to .gitignore):

# --- Always required ---
PrimusAuth__Security__TokenEncryptionKey=your-32-char-generated-key

# --- Auth0 (if using Auth0) ---
Auth0__Domain=your-tenant.us.auth0.com
Auth0__ClientId=your-auth0-client-id
Auth0__ClientSecret=your-auth0-client-secret

# --- Azure AD (if using Azure AD) ---
AzureAd__TenantId=your-tenant-id
AzureAd__ClientId=your-azure-client-id
AzureAd__ClientSecret=your-azure-client-secret

# --- Google (if using Google) ---
Google__ClientId=your-google-client-id.apps.googleusercontent.com
Google__ClientSecret=your-google-client-secret

# --- Okta (if using Okta) ---
Okta__Domain=https://dev-123456.okta.com
Okta__ClientId=your-okta-client-id
Okta__ClientSecret=your-okta-client-secret

# --- Redis (only if running multiple servers) ---
REDIS_CONNECTION_STRING=localhost:6379

Never commit real secrets

.env must be in .gitignore. Only commit .env.example with placeholder values — never real credentials.

---

Next Steps

• Integration Guide — complete setup walkthrough from install to first authenticated request
• Provider pages — Azure AD, Auth0, Google, Okta, SAML 2.0
• Advanced Configuration — custom stores, HA clustering, and data protection keys
• Endpoint Reference — every /api/auth/* endpoint with request and response shapes