Identity configuration, permissions, and integrations

This page answers three production questions: which code reads a setting, what happens when it is absent, and how to prove that a real adapter has replaced the placeholder. A Host that starts from configuration is not necessarily commercially ready.

1. Registration order

Register Identity application services before Infrastructure adapters. TryAdd defaults allow later concrete registrations to replace them; incorrect order can leave a Null or Unavailable implementation active.

// 1. CoreRuntime registers Identity policy, enhanced-MFA entry, and fail-closed defaults.
services.AddBitzOrcasCoreRuntime(configuration);

// 2. With both database and RabbitMQ configuration, register generated stores,
// notification delivery, and federation. API Shell keeps CoreRuntime defaults.
services.AddBitzOrcasPersistenceAdapters(configuration);

// 3. Authentication schemes and API pipeline consume the closed Identity service graph.
services.AddBitzOrcasAuthentication(configuration, environment);
services.AddBitzOrcasApiPipeline(configuration);

AddBitzOrcasCoreRuntime calls AddBitzOrcasPlatformIdentity and AddBitzOrcasMfaConnectors; the production branch of AddBitzOrcasPersistenceAdapters registers notification connectors and AddBitzOrcasIdentityFederationConnectors. When creating a Host, copy the verified composition relationship rather than calling internal extensions twice.

2. Password settings

2.1 Password client encryption Identity:Password:Cipher

Bound type: PasswordCipherOptions (PasswordCipherOptions.SectionName).

The product baseline requires RSA-OAEP-SHA256 client encryption with no plaintext password fallback. Omitting the section uses the defaults below; login still works because the SDK calls GET /api/auth/cipher-key and encrypts.

{
  "Identity": {
    "Password": {
      "RequireDigit": true,
      "RequireLowercase": true,
      "RequireUppercase": true,
      "RequireNonAlphanumeric": true,
      "RequiredLength": 12,
      "RequiredUniqueChars": 6,
      "BCrypt": {
        "WorkFactor": 12
      },
      "Expiry": {
        "PasswordExpiryDays": 90,
        "PasswordExpiryWarningDays": 7
      },
      "History": {
        "PasswordHistoryCount": 5
      },
      "Cipher": {
        "KeySize": 2048,
        "RotationHours": 24,
        "GracePeriodMinutes": 10,
        "MaxClockSkewSeconds": 120,
        "NonceTtlSeconds": 120
      }
    }
  }
}

Validation vs runtime clamp (do not confuse)

So if someone sets RotationHours: 8760 (one year) expecting fewer rotations, the host still starts, but rotation is capped at 720h (30 days). Treat this doc and the source Math.Clamp(..., 1, 24 * 30) as source of truth — not “whatever is written in appsettings”.

Key lifecycle and cipher-key response

Ops notes and current boundaries

• Horizontal scale / multi-instance: when both ICacheStore and ICipherKeyMaterialProtector are available, the current + previous snapshot is shared in distributed cache. Instance B can decrypt ciphertext encrypted with a public key served by instance A. Every instance must share the same ASP.NET Core Data Protection key ring; otherwise private-key unprotection fails as KeyExpired.
• Fallback mode: if either the cache or protector is absent, the service logs a Warning and uses an in-process ring. Cross-node requests can then still return KeyExpired. Fix production composition; use sticky sessions only as a temporary mitigation. The SDK’s single refresh retry absorbs a race but is not a scaling design.
• Nonce storage prefers ICacheStore (e.g. Redis). Without it, the process falls back to an in-memory dictionary and logs a Warning — multi-instance replay protection is single-node only; use Redis in production.
• Algorithm is fixed RSA-OAEP + SHA-256; payload/flow details: login security.
• Raising KeySize (3072/4096) increases CPU and ciphertext size; load-test before shipping.
• Large RotationHours (near 720) lengthens single-key exposure; very small values increase KeyExpired and SDK retries. Default 24 fits most deployments.
• GracePeriodMinutes should cover “client cached public key → submit” latency and stay well below the rotation interval; multi-hour grace weakens rotation benefits.
• Error codes: Identity.Cipher.KeyExpired, DecryptFailed, ClockSkewExceeded, ReplayDetected, EncryptedPasswordRequired, PayloadInvalid.

Benchmark login throughput and CPU on production-sized hardware before raising BCrypt cost. Do not lower it below security policy for throughput, and do not double it without capacity evidence.

3. JWT base settings

A single Secret is acceptable for development. Production should prefer SigningKeys with Kid, allowing issuance from the active key and validation with grace-period keys.

{
  "Jwt": {
    "Issuer": "https://identity.example.com",
    "Audience": "bitzorcas-api",
    "AccessTokenExpirationMinutes": 15,
    "RefreshTokenExpirationDays": 7,
    "SigningKeys": [
      {
        "Kid": "identity-2026-q3",
        "Secret": "secret-injected-by-managed-key-provider-at-runtime",
        "ActiveFrom": "2026-07-01T00:00:00Z",
        "ActiveTo": null
      }
    ],
    "Rotation": {
      "Enabled": true,
      "RotationIntervalDays": 90,
      "GracePeriodDays": 7,
      "CronExpression": "0 0 2 * * ?"
    }
  }
}

The Secret above is a placeholder. Never commit a real key. NullJwtKeyRotationSink only records rotation; managed-key persistence requires a production IJwtKeyRotationSink.

4. Frontend notification links

FrontendLinkBuilder reads Frontend:BaseUrl and the route dictionary. The default BaseUrl is http://localhost:6800 and is local-development only.

{
  "Frontend": {
    "BaseUrl": "https://portal.example.com",
    "Routes": {
      "ResetPassword": "/reset-password",
      "Activate": "/activate",
      "VerifyEmail": "/verify-email",
      "ConfirmPhone": "/confirm-phone"
    }
  }
}

BaseUrl must be HTTPS, fixed to a trusted host, and have no trailing slash. Routes are server configuration and must not accept an arbitrary ReturnUrl. Place notification tokens where the frontend can submit them immediately without exposing them to analytics, Referer, or logs.

5. Defaults and failure semantics

AddBitzOrcasPlatformIdentity registers:

• BCryptPasswordHasher, DefaultPasswordValidator, and JwtTokenService.
• LoginFlow, password-expiry, and password-history services.
• Built-in TotpMfaService.
• UnavailableAuthProvider for AzureAD, WeChat, WeCom, and DingTalk.
• UnavailableWeChatMiniProgramAuthService.
• NullEmailDeliveryPort and NullSmsDeliveryPort.
• NullLoginLogArchiveQueryPort and NullJwtKeyRotationSink.

Unavailable federation should return a stable unavailable error. Null delivery is best effort. Neither should make a readiness probe claim that the related business capability is ready.

6. Federation adapters

After AddBitzOrcasIdentityFederationConnectors, each adapter registers independently:

{
  "AzureAD": {
    "Enabled": true,
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "organization-tenant-id",
    "ClientId": "application-client-id",
    "ClientSecret": "injected-secret",
    "CallbackPath": "/api/callback/azuread",
    "Scopes": ["openid", "profile", "email"]
  }
}

Application and Contracts must not reference connector packages. Vendor SDKs, HttpClient, and error translation stay in Infrastructure. A successful external identity still enters local account, tenant, role, and session semantics.

6.1 Tenant-level Provider management

Static Host configuration loads protocol adapters. Tenant runtime parameters and credentials are managed through an API and take effect without a process restart. Code-registered Profiles define allowed fields, defaults, interaction, and required Adapter; the tenant-owned ExternalLoginProviderConfiguration aggregate references only a stable ProfileId.

The current Profile catalog is:

Social OAuth endpoints must be public HTTPS URLs with no UserInfo, query, or fragment. SAML has its own dynamic configuration, metadata validation, and runtime-snapshot lifecycle, so it is deliberately not duplicated in these four Profiles.

Management API and authorization

All four use cases require Manage on resource identity/externallogin, represented by permission identity.externallogin.manage. The frontend entry is the External Login sheet in Integration Center. It is a client of the management API, not a second configuration source of truth.

Parameters in a save request is the complete non-sensitive set. Secrets contains only values created or replaced in this request, while ClearedSecretKeys explicitly removes values. Existing credentials omitted from both are preserved. Reads return only ConfiguredSecretKeys; they never return credential values, SecretsJson, or its search hash. The persistence column uses the standard Data Protection sensitive-column pipeline. Runtime secrets do not enter responses, logs, exceptions, cache keys, or telemetry labels.

Before enabling a configuration, the service checks the Profile schema, required credentials, and whether a real Adapter is loaded. Stable readiness values are Ready, Disabled, Incomplete, AdapterUnavailable, and NotConfigured. A connection test uses saved configuration and returns only success, UTC time, latency, stable error code, and a redacted message.

Every public Provider listing, login initiation, callback, mini-program exchange, and connection test re-reads the current tenant’s authoritative Store; credentials are not cached. Rotation therefore takes effect immediately. Redirect flows also compare {configurationId}:{version} so a callback cannot continue under credentials changed after initiation. Explicit disable or delete removes the Provider from the public login list and does not fall back to legacy static configuration.

7. Enhanced MFA connector

Built-in TOTP remains available without the connector. With MFA:Enabled=true, AddBitzOrcasMfaConnectors adds email/SMS OTP, FIDO2, recovery codes, trusted devices, and risk-driven policy.

The default connector MfaCacheProvider is in process. A hosted service warns outside Development. Multi-instance production must replace it with Redis or another distributed implementation; otherwise a FIDO2 challenge generated on one instance may be verified on another and fail.

NullUserMfaConfigRepository is also a placeholder. When enhanced MFA is enabled, verify concrete user-MFA storage, email/SMS delivery, and challenge cache.

8. Notification adapters

Activation, password reset, email confirmation, and phone confirmation consume IEmailDeliveryPort or ISmsDeliveryPort. Map provider states to operating semantics:

The current Null port can let a call complete without delivery, so the GA gate must inspect the concrete implementation or run an end-to-end delivery probe.

9. Permission catalog

IdentityPermissions currently owns:

• Users: list, read, create, update, delete, enable, disable, lock, unlock.
• Roles: list, read, create, update, delete.
• Login logs: list, read.
• MFA: manage.
• Devices: list, manage.
• Sessions: list, manage.
• External login: manage.
• Organization units: list, read, create, update, delete.

Invitation, Admission, and Tenant commands also express resource authorization through ResourceDescriptor and AuthorizationAction. Catalog permissions and resource actions are complementary; neither alone is the full decision.

10. Sensitive configuration rules

• Host-level JWT and adapter-bootstrap credentials come from secret stores or environment injection; tenant external-login credentials enter only through the management API and the protected SecretsJson sensitive column.
• PlatformTenant.ConnectionString never enters normal configuration responses, logs, or audit detail.
• Password hashes, security stamps, raw tokens, and FIDO2 challenges are not structured-log fields.
• Configuration snapshots and diagnostic endpoints apply fixed masking rather than retaining prefixes and suffixes.
• Rotation leaves old keys for validation grace but never continues issuing with retired keys.

11. Startup verification

# Inspect option binding and default implementations.
rg -n "Bind\(|TryAdd|Unavailable|Null.*Port|NullJwt" \
  src/Platform/Identity/BitzOrcas.Identity.Application/Identity/DependencyInjection.cs

# Inspect actual connector conditions and replacement registrations.
rg -n "GetSection|GetValue|AddScoped<IExternalAuthProvider|MFA:Enabled" \
  src/Platform/Identity/BitzOrcas.Identity.Infrastructure -g '*.cs'

# Committed appsettings should not contain an apparent real secret.
rg -n '"(Secret|ClientSecret|AppSecret|Password)"\s*:\s*"[^$<{]' \
  src/Hosts -g 'appsettings*.json'

The last command is heuristic and requires review. It does not replace a secret scanner.

12. Production acceptance table

Identity overview · Login security · Testing and operations