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

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) skip MFA — the external identity provider handles it.

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

By default, Authagonal uses a no-op email service that silently discards all emails. To enable email delivery, register an IEmailService implementation before calling AddAuthagonal().

The built-in EmailService uses Resend. To use it, register it explicitly:

services.AddSingleton<IEmailService, EmailService>();
services.AddAuthagonal(configuration);

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

Cluster

Authagonal instances automatically form a cluster to share rate limit state. Clustering is enabled by default with zero configuration.

Zero-config (default): Instances discover each other via UDP multicast. Works in Kubernetes, Docker Compose, or any shared network.

Multicast disabled (e.g., some cloud VPCs):

{
  "Cluster": {
    "InternalUrl": "http://authagonal-auth.svc.cluster.local:8080",
    "Secret": "shared-secret-here"
  }
}

Clustering fully disabled:

{
  "Cluster": {
    "Enabled": false
  }
}

See Scaling for more details on how distributed rate limiting works.

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 per-IP rate limits are enforced across all instances via the cluster gossip protocol:

When clustering is enabled, these limits are consolidated across all instances. When disabled, each instance enforces its own limit independently.

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"]
    }
  ]
}