Domain Allowlist

The Domain Allowlist feature restricts which email domains can authenticate through Primus Auth Broker. When enabled, any login attempt from an email address whose domain is not in the allowlist is blocked before a session cookie is issued — the exact response depends on the provider (see Behaviour by Provider below).

Configuration

Add a DomainAllowlist section to your PrimusAuth configuration block:

{
  "PrimusAuth": {
    "DomainAllowlist": {
      "Enabled": true,
      "AllowedDomains": [
        "acme.com",
        "acme.io",
        "partner.org"
      ]
    }
  }
}

Field	Type	Default	Allowed values	Description
Enabled	bool	false	true | false	Optional. Activates domain allowlist enforcement. When false (the default), all email domains are permitted.
AllowedDomains	string[]	[]	Array of domain strings	Case-insensitive list of permitted email domains (e.g. ["acme.com", "partner.org"]). Ignored when Enabled is false.

Behaviour by Provider

Provider	Where enforced	On block
Local (email + password)	After credential validation, before session cookie	HTTP 403 JSON {error: "..."}
OIDC (Azure AD, Auth0, Google, Okta)	Inside OnTokenValidated before JIT provisioning	Redirects to ErrorRedirect?error=... — or HTTP 500 HTML page if ErrorRedirect is not configured
SAML (Entra ID, Okta, Google Workspace, ADFS, Auth0, and any SAML 2.0 IdP)	Inside OnSigningIn before session creation	Redirects to ErrorRedirect?error=domain_not_allowed — or / if ErrorRedirect is not configured

Blocking happens before any session cookie is issued, ensuring no partial state leaks.

Environment Variable Override

ASP.NET Core maps __ to : so all config keys work as environment variables (e.g. PrimusAuth__DomainAllowlist__Enabled=true, PrimusAuth__DomainAllowlist__AllowedDomains__0=acme.com).

Example: Allowing Only Corporate Domains

{
  "PrimusAuth": {
    "DomainAllowlist": {
      "Enabled": true,
      "AllowedDomains": ["mycompany.com"]
    }
  }
}

With this config, alice@mycompany.com can authenticate. A local login attempt by bob@gmail.com returns HTTP 403 immediately after credential validation. An OIDC or SAML login attempt by bob@gmail.com is redirected to the configured ErrorRedirect URL with ?error=... appended — or to / if no ErrorRedirect is set.

Disabling the Feature

Set Enabled to false (the default) to allow all email domains:

{
  "PrimusAuth": {
    "DomainAllowlist": {
      "Enabled": false
    }
  }
}

Notes

• Domain matching is case-insensitive (ACME.COM equals acme.com).
• Subdomains are not matched automatically. Add sub.acme.com explicitly if required.
• The allowlist is read once at application startup and registered as a singleton. Changes to configuration take effect only after restarting the application.

---

Next Steps

• Integration Guide — complete setup walkthrough from install to first authenticated request
• Bot Protection & Rate Limiting — complement domain restrictions with IP-based rate limiting
• Advanced Configuration — custom stores, HA clustering, and data protection
• Webhooks — receive events when blocked logins are attempted