Configuration

Authagonal is configured via appsettings.json or environment variables. Environment variables use __ as the section separator (e.g., Storage__ConnectionString).

Required Settings

Storage can be configured one of two ways, supply either Storage:ConnectionString or Storage:TableServiceUri (the managed-identity path, preferred in production).

Storage

Authentication

Data Protection

ASP.NET Core Data Protection keys (which encrypt the session cookie) must be shared across instances, see Scaling. Persistence options, in precedence order:

On the AWS backend, pass an S3 client + bucket to AddAuthagonalAwsStorage to persist the key ring to S3, see Installation → AWS backend.

Cache and Timeouts

Background Services

Clients

Clients are defined in the Clients array and seeded on startup. Each client can have:

{
  "Clients": [
    {
      "ClientId": "my-app",
      "ClientName": "My Application",
      "ClientSecretHashes": ["sha256-hash-here"],
      "AllowedGrantTypes": ["authorization_code"],
      "RedirectUris": ["https://app.example.com/callback"],
      "PostLogoutRedirectUris": ["https://app.example.com"],
      "AllowedScopes": ["openid", "profile", "email", "custom-scope"],
      "AllowedCorsOrigins": ["https://app.example.com"],
      "RequirePkce": true,
      "RequireClientSecret": false,
      "AllowOfflineAccess": true,
      "AlwaysIncludeUserClaimsInIdToken": false,
      "AccessTokenLifetimeSeconds": 1800,
      "IdentityTokenLifetimeSeconds": 300,
      "AuthorizationCodeLifetimeSeconds": 300,
      "AbsoluteRefreshTokenLifetimeSeconds": 2592000,
      "SlidingRefreshTokenLifetimeSeconds": 1296000,
      "RefreshTokenUsage": "OneTime",
      "MfaPolicy": "Enabled",
      "RequireConsent": false,
      "BackChannelLogoutUri": "https://app.example.com/logout-callback",
      "ProvisioningApps": ["my-backend"]
    }
  ]
}

Grant Types

Refresh Token Usage

Provisioning Apps

The ProvisioningApps array references app IDs defined in the ProvisioningApps configuration section. When a user authorizes through this client, they are provisioned into those apps via TCC. See Provisioning for details.

Provisioning Apps

Define downstream applications that users should be provisioned into:

{
  "ProvisioningApps": {
    "my-backend": {
      "CallbackUrl": "https://api.example.com/provisioning",
      "ApiKey": "secret-api-key"
    },
    "analytics": {
      "CallbackUrl": "https://analytics.example.com/provisioning",
      "ApiKey": "another-key"
    }
  }
}

See Provisioning for the full TCC protocol specification.

MFA Policy

Multi-factor authentication is enforced per-client via the MfaPolicy property:

{
  "Clients": [
    {
      "ClientId": "secure-app",
      "MfaPolicy": "Required"
    }
  ]
}

When MfaPolicy is Required and the user hasn’t enrolled MFA, login returns { mfaSetupRequired: true, setupToken: "..." }. The setup token authenticates the user to the MFA setup endpoints (via X-MFA-Setup-Token header) so they can enroll before getting a cookie session.

Federated logins (SAML/OIDC) honour the MFA policy too: an MFA-enrolled user is routed through the MFA challenge after the external IdP authenticates them, and Required forces enrollment for federated users without MFA.

IAuthHook Override

The IAuthHook.ResolveMfaPolicyAsync method can override the client policy per-user:

public Task<MfaPolicy> ResolveMfaPolicyAsync(
    string userId, string email, MfaPolicy clientPolicy,
    string clientId, CancellationToken ct)
{
    // Force MFA for admin users regardless of client setting
    if (email.EndsWith("@admin.example.com"))
        return Task.FromResult(MfaPolicy.Required);

    return Task.FromResult(clientPolicy);
}

Password Policy

Customize password strength requirements:

{
  "PasswordPolicy": {
    "MinLength": 10,
    "MinUniqueChars": 3,
    "RequireUppercase": true,
    "RequireLowercase": true,
    "RequireDigit": true,
    "RequireSpecialChar": false
  }
}

The policy is enforced on password reset and admin user registration. The login UI fetches the active policy from GET /api/auth/password-policy to display requirements dynamically.

SAML Providers

Define SAML identity providers in configuration. These are seeded on startup:

{
  "SamlProviders": [
    {
      "ConnectionId": "azure-ad",
      "ConnectionName": "Azure AD",
      "EntityId": "https://auth.example.com",
      "MetadataLocation": "https://login.microsoftonline.com/{tenant}/FederationMetadata/2007-06/FederationMetadata.xml",
      "AllowedDomains": ["example.com", "example.org"]
    }
  ]
}

OIDC Providers

Define OIDC identity providers in configuration. These are seeded on startup:

{
  "OidcProviders": [
    {
      "ConnectionId": "google",
      "ConnectionName": "Google",
      "MetadataLocation": "https://accounts.google.com/.well-known/openid-configuration",
      "ClientId": "your-client-id",
      "ClientSecret": "your-client-secret",
      "RedirectUrl": "https://auth.example.com/oidc/callback",
      "AllowedDomains": ["example.com"]
    }
  ]
}

Note: Providers can also be managed at runtime via the Admin API. Config-seeded providers are upserted on every startup, so config changes take effect on restart.

Secret Provider

Upstream OIDC client secrets and TOTP / MFA seeds can be stored in Azure Key Vault instead of in plaintext:

When configured, secret values that look like Key Vault references are resolved at runtime. Uses DefaultAzureCredential for authentication.

⚠️ Production: set SecretProvider:VaultUri. The default secret provider is plaintext. When SecretProvider:VaultUri is unset, upstream OIDC client secrets and TOTP / MFA seeds are written to Azure Table Storage in cleartext, and therefore appear in cleartext in any backup. For any production deployment, configure SecretProvider:VaultUri so these secrets are stored in Key Vault.

Admin API

⚠️ The admin API is enabled by default and is highly privileged. The admin scope grants full management and user impersonation, anyone holding a token with AdminApi:Scope can mint tokens for any user, manage clients, and read/write all configuration. Network-restrict the admin endpoints (the /api/v1/* admin routes), and tightly control who can be issued the admin scope. As a defence-in-depth measure the scope is reserved: it can never be granted to an OAuth client (see Admin API) and cannot be issued through the impersonation endpoint. Set AdminApi:Enabled = false entirely if the admin API is not used.

Consent

Per-client consent can be enabled with the RequireConsent property:

Users can view and revoke their consent grants at GET /consent/grants and DELETE /consent/grants/{clientId}.

Back-Channel Logout

Register a BackChannelLogoutUri on a client to receive OIDC Back-Channel Logout 1.0 notifications. When a user logs out, Authagonal sends a signed logout token (JWT) to each client’s registered URI.

{
  "Clients": [
    {
      "ClientId": "my-app",
      "BackChannelLogoutUri": "https://app.example.com/logout-callback"
    }
  ]
}

Email

The built-in email sender uses Resend and activates automatically when Email:ResendApiKey is configured, no service registration needed. To use a different provider, register your own IEmailService implementation before calling AddAuthagonal() (it takes precedence regardless of the Email:* keys).

⚠️ Without any email sender, self-registration is broken. When Email:ResendApiKey is unset and no custom IEmailService is registered, a no-op service silently discards all mail, verification and password-reset emails never arrive, and because login requires a confirmed email by default, self-registered users can never sign in. UseAuthagonal logs a warning at startup in this state. Escape hatch for dev/test: Auth:AutoConfirmEmailDomains auto-confirms registrations for the listed domains.

Emails to @example.com addresses are silently skipped (useful for testing).

Cluster

The clustering layer provides leader election (so leader-gated jobs like signing key rotation run on exactly one node) and a cross-node event bus, behind pluggable backends. The default is in-process: a single node is always its own leader, the right setting for single-node and local development, with zero configuration.

Multi-node deployments swap in a real backend via the configureClustering callback on AddAuthagonal / AddAuthagonalCore:

// Azure: leadership via a blob lease, event bus via a table log (Authagonal.AzureProvider)
builder.Services.AddAuthagonal(builder.Configuration,
    cluster => cluster.UseAzureStorage(blobServiceClient, tableServiceClient));

// AWS equivalent (Authagonal.AwsProvider)
builder.Services.AddAuthagonal(builder.Configuration,
    cluster => cluster.UseAwsDynamo(dynamoDb));

UseAzureStorageBus / UseAwsDynamoBus register the event bus only, keeping the in-process lease, for nodes that must receive cluster events but must never contend for leadership.

See Scaling for how leadership and the event bus behave across instances.

Forwarded Headers (trusted proxy)

Authagonal keys rate limiting and account lockout on the client IP, and only emits HSTS on HTTPS requests. Behind a reverse proxy / ingress, the real client IP and scheme arrive in the X-Forwarded-For / X-Forwarded-Proto headers. These settings control which proxy hops are trusted to set those values, so a caller can’t spoof X-Forwarded-For to forge the client IP.

{
  "ForwardedHeaders": {
    "ForwardLimit": 1,
    "KnownNetworks": ["10.244.0.0/16"],
    "KnownProxies": []
  }
}

⚠️ TLS-terminating proxy required. Authagonal must run behind a TLS-terminating reverse proxy. The session cookie uses SecurePolicy = SameAsRequest and HSTS (Strict-Transport-Security) is only emitted on HTTPS requests, so the proxy must forward X-Forwarded-Proto: https for cookies to be marked Secure and HSTS to be sent. Configure ForwardedHeaders:KnownNetworks / ForwardedHeaders:KnownProxies to your trusted proxy so the scheme and client IP cannot be spoofed.

Rate Limiting

Built-in rate limits protect the abuse-prone endpoints:

Limits are enforced in-process per node (behind the IRateLimiter seam), so with N instances the effective ceiling is N× the configured value. Treat these as a backstop and enforce the authoritative global limit at the edge (WAF / ingress / CDN). See Scaling.

CORS

CORS is configured dynamically. Origins from all registered clients’ AllowedCorsOrigins are automatically allowed, with a 60-minute cache.

HashiCorp Vault Transit

Authagonal can sign JWTs using HashiCorp Vault’s Transit secrets engine. Private keys never leave Vault, only the signing operation is delegated remotely. Public keys are cached locally for verification.

This is configured programmatically when hosting as a library. See Extensibility for details.

Full Example

{
  "Storage": {
    "TableServiceUri": "https://myaccount.table.core.windows.net/",
    "NameIndexesEnabled": true
  },
  "Issuer": "https://auth.example.com",
  "LoginAppUrl": "/login",
  "Auth": {
    "MaxFailedAttempts": 5,
    "LockoutDurationMinutes": 10,
    "MaxRegistrationsPerIp": 5,
    "RegistrationWindowMinutes": 60,
    "EmailVerificationExpiryHours": 24,
    "PasswordResetExpiryMinutes": 60,
    "Pbkdf2Iterations": 100000,
    "RefreshTokenReuseGraceSeconds": 0,
    "DynamicClientRegistrationEnabled": false,
    "SigningKeyLifetimeDays": 90
  },
  "SecretProvider": {
    "VaultUri": "https://my-vault.vault.azure.net/"
  },
  "ForwardedHeaders": {
    "ForwardLimit": 1,
    "KnownNetworks": ["10.244.0.0/16"]
  },
  "Cluster": {
    "Enabled": true,
    "Secret": "shared-secret-here"
  },
  "AdminApi": {
    "Enabled": true,
    "Scope": "authagonal-admin"
  },
  "Authentication": {
    "CookieLifetimeHours": 48
  },
  "PasswordPolicy": {
    "MinLength": 8,
    "RequireUppercase": true,
    "RequireLowercase": true,
    "RequireDigit": true,
    "RequireSpecialChar": true
  },
  "Email": {
    "ResendApiKey": "re_xxx",
    "SenderEmail": "noreply@example.com",
    "SenderName": "Example Auth"
  },
  "SamlProviders": [
    {
      "ConnectionId": "azure-ad",
      "ConnectionName": "Azure AD",
      "EntityId": "https://auth.example.com",
      "MetadataLocation": "https://login.microsoftonline.com/{tenant}/FederationMetadata/2007-06/FederationMetadata.xml",
      "AllowedDomains": ["example.com"]
    }
  ],
  "OidcProviders": [
    {
      "ConnectionId": "google",
      "ConnectionName": "Google",
      "MetadataLocation": "https://accounts.google.com/.well-known/openid-configuration",
      "ClientId": "...",
      "ClientSecret": "...",
      "RedirectUrl": "https://auth.example.com/oidc/callback",
      "AllowedDomains": ["gmail.com"]
    }
  ],
  "ProvisioningApps": {
    "backend": {
      "CallbackUrl": "https://api.example.com/provisioning",
      "ApiKey": "secret"
    }
  },
  "Clients": [
    {
      "ClientId": "web",
      "ClientName": "Web App",
      "AllowedGrantTypes": ["authorization_code"],
      "RedirectUris": ["https://app.example.com/callback"],
      "PostLogoutRedirectUris": ["https://app.example.com"],
      "AllowedScopes": ["openid", "profile", "email"],
      "AllowedCorsOrigins": ["https://app.example.com"],
      "RequirePkce": true,
      "RequireClientSecret": false,
      "AllowOfflineAccess": true,
      "MfaPolicy": "Enabled",
      "RequireConsent": false,
      "BackChannelLogoutUri": "https://app.example.com/logout-callback",
      "ProvisioningApps": ["backend"]
    }
  ]
}