Engine:Identity

Engine:Identity configures the host-agnostic identity capability. Only consumed when Engine:Identity:Enabled=true and at least one module declares Capability.Identity.

Full schema

1
{
2
  "Engine": {
3
    "Identity": {
4
      "Enabled": true,
5
      "Provider": "Bearer",                       // "Bearer" | "Cookie" | "None"
6
      "Authority": "https://login.acme.example/",
7
      "Audience":  "https://api.acme.example",
8
      "RequireHttpsMetadata": true,
9
      "ClockSkew": "00:05:00",                    // TimeSpan
10
      "TokenValidation": {
11
        "ValidateIssuer":   true,
12
        "ValidateAudience": true,
13
        "ValidateLifetime": true,
14
        "ValidIssuers":     [ "https://login.acme.example/" ],
15
        "ValidAudiences":   [ "https://api.acme.example" ],
16
        "NameClaimType":    "sub",                // claim to use as principal name
17
        "RoleClaimType":    "roles"               // claim that carries role array
18
      },
19
      "ClaimMapping": {
20
        "TenantId":        "tenant_id",
21
        "UserId":          "sub",
22
        "Email":           "email",
23
        "DisplayName":     "name"
24
      },
25
      "Cookie": {
26
        "Name":            ".AcmeStore.Auth",
27
        "LoginPath":       "/auth/login",
28
        "LogoutPath":      "/auth/logout",
29
        "ExpireTimeSpan":  "08:00:00",
30
        "SlidingExpiration": true
31
      },
32
      "Scopes": {
33
        "RequireAllForApi": false,                // OR vs AND scope matching
34
        "DefaultDenied":    true                   // unmatched scopes = denied
35
      }
36
    }
37
  }
38
}

Each option in detail

`Enabled`

Type	Default
boolean	`false`

Master switch. When false:

Modules declaring Capability.Identity fail composition.
WithRequireScope / WithRequireRole decorators on behaviors become no-ops.
Principal is the anonymous user (IUserContext.IsAnonymous == true).

Set true to wire the identity capability. Requires Cephalon.Identity + a host-side adapter (Cephalon.Identity.AspNetCore).

`Provider`

Type	Default	Allowed values
enum string	`"None"`	`"Bearer"`, `"Cookie"`, `"None"`

Authentication scheme.

Value	Use case
`"Bearer"`	Most common. JWT bearer tokens from an OIDC IdP (Auth0, Okta, Azure AD, Cognito, Keycloak).
`"Cookie"`	Browser-driven login with server-side cookies. Used for traditional web apps.
`"None"`	Wire identity primitives without authentication (e.g. for tests that fake the principal).

1
{ "Engine": { "Identity": { "Enabled": true, "Provider": "Bearer", "Authority": "…" } } }

`Authority` (Bearer)

Type	Default
URL string	none

The OIDC authority URL. The discovery document at <Authority>/.well-known/openid-configuration is fetched at startup to learn the signing keys, issuer, and supported algorithms.

Examples:

1
{ "Authority": "https://login.acme.example/" }                                  // self-hosted Keycloak
2
{ "Authority": "https://acme.auth0.com/" }                                      // Auth0
3
{ "Authority": "https://login.microsoftonline.com/<tenant-id>/v2.0" }           // Azure AD
4
{ "Authority": "https://cognito-idp.us-east-1.amazonaws.com/<pool-id>" }        // AWS Cognito

Limits:

The authority must serve a valid OIDC discovery document.
Discovery is cached for the host lifetime; rotate keys by restarting (or use the IdP’s standard JWKS rotation, which is auto-refreshed).

`Audience` (Bearer)

Type	Default
string or array	none

The expected aud claim on incoming JWTs. Tokens with a non-matching audience are rejected.

1
{ "Audience": "https://api.acme.example" }
2
{ "Audience": ["https://api.acme.example", "https://internal-api.acme.example"] }

`RequireHttpsMetadata`

Type	Default
boolean	`true`

Whether the authority URL must be HTTPS. Always true in production. Only set false for local dev against an http://localhost IdP.

`ClockSkew`

Type	Default
TimeSpan string	`"00:05:00"` (5 min)

Allowed clock skew between the IdP and the host. Tokens just-expired by less than ClockSkew are still accepted.

1
{ "ClockSkew": "00:01:00" }   // 1 min — strict
2
{ "ClockSkew": "00:10:00" }   // 10 min — relaxed

Tip: keep this small (1–5 min) in production. Larger values widen the window of replay attacks.

`TokenValidation` (Bearer)

Fine-grained token validation. Mostly safe to leave at defaults; override only when you know why.

Option	Default	Description
`ValidateIssuer`	`true`	Reject tokens whose `iss` claim isn’t in `ValidIssuers`.
`ValidateAudience`	`true`	Reject tokens whose `aud` claim isn’t in `ValidAudiences`.
`ValidateLifetime`	`true`	Reject expired tokens (with `ClockSkew` grace).
`ValidIssuers`	`[Authority]`	Allowlist of acceptable issuers. Defaults to `Authority` if not set.
`ValidAudiences`	`[Audience]`	Allowlist of acceptable audiences.
`NameClaimType`	`"sub"`	Which claim becomes `IUserContext.UserId`.
`RoleClaimType`	`"roles"`	Which claim carries the role array. Some IdPs use `"role"` or a namespaced URI.

Example: multi-tenant SaaS with one IdP per tenant:

1
{
2
  "TokenValidation": {
3
    "ValidIssuers": [
4
      "https://tenant-a.auth.acme.example/",
5
      "https://tenant-b.auth.acme.example/"
6
    ]
7
  }
8
}

Example: legacy app with non-standard claims:

1
{
2
  "TokenValidation": {
3
    "NameClaimType": "preferred_username",
4
    "RoleClaimType": "https://schemas.microsoft.com/ws/2008/06/identity/claims/role"
5
  }
6
}

`ClaimMapping`

Maps JWT claims to engine-level identity primitives. The engine exposes them via IUserContext.

Key	Default claim	What it populates
`TenantId`	`"tenant_id"`	`IUserContext.TenantId` — used by `Capability.Tenancy`
`UserId`	`"sub"`	`IUserContext.UserId`
`Email`	`"email"`	`IUserContext.Email`
`DisplayName`	`"name"`	`IUserContext.DisplayName`

Example: Auth0 multi-tenant setup using a namespaced claim:

1
{
2
  "ClaimMapping": {
3
    "TenantId": "https://acme.example/tenant_id",
4
    "Email": "https://acme.example/email"
5
  }
6
}

`Cookie` (Cookie provider)

When Provider="Cookie", configure cookie behaviour here.

Option	Default	Description
`Name`	`".AppCookie"`	Cookie name. Use a unique value per app to avoid collisions.
`LoginPath`	`"/Account/Login"`	Where to redirect unauthenticated users.
`LogoutPath`	`"/Account/Logout"`	Logout endpoint path.
`ExpireTimeSpan`	`"08:00:00"`	Cookie lifetime.
`SlidingExpiration`	`true`	Reset expiration on each request.

1
{
2
  "Cookie": {
3
    "Name": ".AcmeStore.Auth",
4
    "ExpireTimeSpan": "24:00:00",
5
    "SlidingExpiration": false
6
  }
7
}

`Scopes`

Policy for scope enforcement on behaviors decorated with WithRequireScope(...).

Option	Default	Description
`RequireAllForApi`	`false`	If `true`, all scopes listed in `WithRequireScope` must be present (AND). If `false`, any match (OR). Default is OR.
`DefaultDenied`	`true`	If no scope decorator is present, deny anonymous access. Set `false` to allow anonymous as the default.

Example: enforce all scopes on every behavior:

1
{ "Scopes": { "RequireAllForApi": true, "DefaultDenied": true } }

Common scenarios

Scenario 1: Bearer auth with Auth0

1
{
2
  "Engine": {
3
    "Identity": {
4
      "Enabled":  true,
5
      "Provider": "Bearer",
6
      "Authority": "https://acme.auth0.com/",
7
      "Audience":  "https://api.acme.example",
8
      "RequireHttpsMetadata": true
9
    }
10
  }
11
}

Scenario 2: Bearer auth with Azure AD (single-tenant)

1
{
2
  "Engine": {
3
    "Identity": {
4
      "Enabled":  true,
5
      "Provider": "Bearer",
6
      "Authority": "https://login.microsoftonline.com/<tenant-id>/v2.0",
7
      "Audience":  "<client-id>",
8
      "TokenValidation": {
9
        "NameClaimType": "preferred_username",
10
        "RoleClaimType": "roles"
11
      }
12
    }
13
  }
14
}

1
{
2
  "Engine": {
3
    "Identity": {
4
      "Enabled":  true,
5
      "Provider": "Cookie",
6
      "Cookie": {
7
        "Name": ".AcmeStore.Auth",
8
        "LoginPath": "/account/login",
9
        "ExpireTimeSpan": "12:00:00",
10
        "SlidingExpiration": true
11
      }
12
    }
13
  }
14
}

Scenario 4: Multi-tenant SaaS with per-tenant IdP

1
{
2
  "Engine": {
3
    "Identity": {
4
      "Enabled":  true,
5
      "Provider": "Bearer",
6
      "Authority": "https://login.acme.example/",      // tenancy-agnostic default
7
      "Audience":  "https://api.acme.example",
8
      "TokenValidation": {
9
        "ValidIssuers": [
10
          "https://acme.auth0.com/",
11
          "https://b2c.acme.example/",
12
          "https://login.microsoftonline.com/common/v2.0"
13
        ]
14
      },
15
      "ClaimMapping": { "TenantId": "tenant_id" }
16
    }
17
  }
18
}

Scenario 5: Test environment with anonymous + fake principal

1
{
2
  "Engine": {
3
    "Identity": {
4
      "Enabled":  true,
5
      "Provider": "None",
6
      "Scopes":   { "DefaultDenied": false }
7
    }
8
  }
9
}

In tests, register a fake IUserContext:

1
services.AddSingleton<IUserContext>(new FakeUserContext { UserId = "u1", TenantId = "t1" });

Environment-variable equivalents

Engine__Identity__Enabled=true
Engine__Identity__Provider=Bearer
Engine__Identity__Authority=https://login.acme.example/
Engine__Identity__Audience=https://api.acme.example
Engine__Identity__TokenValidation__NameClaimType=preferred_username
Engine__Identity__ClaimMapping__TenantId=tenant_id

Limits & gotchas

Provider can’t be switched at runtime. Restart the host. Capability registration is one-shot.
JWKS rotation is automatic but takes up to the IdP’s cache TTL (typically 24h) to pick up new keys. Force a rotation by restarting hosts.
Cookie auth + multi-tenant SaaS is hard. Use Bearer + IdP-managed tenancy. Cookies don’t carry custom claims across subdomains without Domain setting.
ClockSkew larger than ExpireTimeSpan of your tokens means tokens never expire from the host’s POV. Keep skew small.
Scopes:RequireAllForApi=true is a hard breaking change for existing apps — every endpoint must explicitly grant required scopes.

Engine:Identity

Full schema

Each option in detail

Enabled

Provider

Authority (Bearer)

Audience (Bearer)

RequireHttpsMetadata

ClockSkew

TokenValidation (Bearer)

ClaimMapping

Cookie (Cookie provider)

Scopes