Version: Current

Custom / Generic SAML IdP

Connect any SAML 2.0-compliant identity provider that does not have a dedicated Primus provider page.

Common use cases:

ADFS (Active Directory Federation Services) — Microsoft's on-premises federation server, widely used in large enterprise Windows environments
Shibboleth — open-source SAML federation software standard in universities and research institutions
PingFederate — enterprise identity federation by Ping Identity

Provider SAML support:

Azure AD, Okta, Google Workspace — SAML presets available (IdpType: AzureAd, Okta, GoogleWorkspace). Their individual provider pages include dedicated SAML setup guides.
Auth0 — SAML IS supported by Auth0 as an IdP, but has no preset. Use IdpType: Custom with Auth0's metadata URL (see example below).
ADFS, Shibboleth, PingFederate, and any other SAML 2.0 IdP — use IdpType: Custom.

Support includes SP-initiated SSO, IdP-initiated SSO, and JIT user provisioning through IPrimusAuthUserStore.

Step 1: Install the package

dotnet add package PrimusSaaS.Identity.Broker

Step 2: Configure Program.cs

using PrimusSaaS.Identity.Broker;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddPrimusAuthBroker(builder.Configuration, builder.Environment.IsDevelopment());
builder.Services.AddControllers();

var app = builder.Build();
app.UseAuthentication();
app.UseAuthorization();
app.UsePrimusCsrfProtection();
app.MapControllers();
app.MapPrimusAuthBroker();
app.Run();

Step 3: Configure appsettings.json

With a metadata URL

If your IdP exposes a publicly accessible metadata URL:

{
  "PrimusAuth": {
    "Saml": {
      "EntityId": "https://app.example.com",
      "IdentityProviders": [
        {
          "Scheme": "enterprise-sso",
          "DisplayName": "Corporate SSO",
          "IdpType": "Custom",
          "MetadataUrl": "https://adfs.company.com/FederationMetadata/2007-06/FederationMetadata.xml"
        }
      ]
    }
  }
}

Auth0 SAML

Auth0 supports SAML as an Identity Provider. Enable the SAML2 addon in your Auth0 application dashboard (Applications → your app → Addons → SAML2 Web App) and set the callback URL to https://app.example.com/api/auth/saml/auth0-saml/Acs.

{
  "Scheme": "auth0-saml",
  "DisplayName": "Auth0 SSO",
  "IdpType": "Custom",
  "MetadataUrl": "https://YOUR_DOMAIN.auth0.com/samlp/metadata/YOUR_CLIENT_ID"
}

Auth0 uses http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress for the email claim by default — no override needed unless you have a custom rule.

Manual config (no metadata URL available)

If the IdP can't serve a publicly accessible metadata document:

{
  "Scheme": "enterprise-sso",
  "DisplayName": "Corporate SSO",
  "IdpType": "Custom",
  "SingleSignOnUrl": "https://sso.company.com/saml/sso",
  "IdpEntityId": "https://sso.company.com",
  "SigningCertificateBase64": "MIIC...base64encodedDERcert...==",
  "EmailClaimType": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"
}

The SigningCertificateBase64 is the DER-encoded certificate (base64) exported from the IdP.

Step 4: Configure endpoints

After app.MapPrimusAuthBroker(), each configured SAML IdP exposes:

Endpoint	Description
`GET /api/auth/saml/{scheme}`	Returns SP metadata XML (used by IdP during setup)
`GET /api/auth/saml/{scheme}/SignIn`	Initiates SP-initiated SSO — redirects browser to IdP
`POST /api/auth/saml/{scheme}/Acs`	Assertion Consumer Service — handled automatically by Sustainsys.Saml2
`GET /api/auth/providers`	Lists all configured providers including SAML

For the enterprise-sso scheme above, the endpoints are:

GET /api/auth/saml/enterprise-sso/SignIn → redirects to the IdP login page (SP-initiated SSO)
GET /api/auth/saml/enterprise-sso → returns SP metadata XML — give this URL to your IdP during setup
POST /api/auth/saml/enterprise-sso/Acs → receives the SAML assertion post-authentication

Multiple SAML IdPs

You can register as many SAML IdPs as you need. Each needs a unique Scheme. All providers — Azure AD, Okta, Google Workspace, Auth0, ADFS, or any other — can coexist:

{
  "PrimusAuth": {
    "Saml": {
      "EntityId": "https://app.example.com",
      "IdentityProviders": [
        {
          "Scheme": "contoso",
          "DisplayName": "Contoso Corp (Azure AD)",
          "IdpType": "AzureAd",
          "AzureTenantId": "contoso-tenant-id"
        },
        {
          "Scheme": "fabrikam",
          "DisplayName": "Fabrikam Inc (Okta)",
          "IdpType": "Okta",
          "MetadataUrl": "https://fabrikam.okta.com/app/xyz/sso/saml/metadata"
        },
        {
          "Scheme": "auth0-saml",
          "DisplayName": "Auth0 SSO",
          "IdpType": "Custom",
          "MetadataUrl": "https://YOUR_DOMAIN.auth0.com/samlp/metadata/YOUR_CLIENT_ID"
        },
        {
          "Scheme": "corp-adfs",
          "DisplayName": "Corporate ADFS",
          "IdpType": "Custom",
          "MetadataUrl": "https://adfs.company.com/FederationMetadata/2007-06/FederationMetadata.xml"
        }
      ]
    }
  }
}

Each IdP gets its own login endpoint — e.g., GET /api/auth/saml/contoso, GET /api/auth/saml/auth0-saml, GET /api/auth/saml/corp-adfs.

User provisioning

SAML sign-ins use the same IPrimusAuthUserStore JIT provisioning as OIDC providers — one interface handles all login methods. The provider parameter passed to AutoProvisionUserAsync identifies how the user authenticated. For OIDC providers it is the provider name ("azure", "google", "auth0", "okta"). For SAML it is always "saml:" followed by the Scheme you configured — so Scheme: "azure-saml" produces provider = "saml:azure-saml" and Scheme: "enterprise-sso" produces provider = "saml:enterprise-sso".

builder.Services.AddScoped<IPrimusAuthUserStore, MyUserStore>();

// In MyUserStore:
public async Task<PrimusAuthUser?> AutoProvisionUserAsync(
    string email,
    string provider,  // "saml:azure-saml", "saml:okta-saml", etc.
    ClaimsPrincipal samlPrincipal,
    CancellationToken cancellationToken)
{
    if (provider.StartsWith("saml:"))
    {
        // SAML-specific provisioning — pull extra attributes from the assertion
        var department = samlPrincipal
            .FindFirst("http://schemas.xmlsoap.org/claims/Department")?.Value;

        return await _db.ProvisionUserAsync(email, department, cancellationToken);
    }
    return null;
}

Email claim mapping

By default, the broker looks for the SAML email attribute at:

http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress

This URI is the standard claim name used by ADFS and Azure AD SAML — it comes from the WS-Federation specification namespace and is used purely as a stable string identifier (no SOAP calls happen). Google Workspace SAML uses the attribute name email directly instead.

If your IdP uses a different attribute, override it per IdP:

{
  "Scheme": "adfs-sso",
  "EmailClaimType": "http://schemas.company.com/claims/email"
}

IdP-initiated SSO

All SAML IdPs are configured with AllowUnsolicitedAuthResponse: true by default, enabling IdP-initiated flows where the user clicks a tile in the IdP's portal without first visiting your app.

To disable IdP-initiated SSO for a specific IdP:

{
  "Scheme": "strict-saml",
  "AllowUnsolicitedAuthResponse": false
}

Configuration reference

Property	Required	Allowed values	Description
`PrimusAuth:Saml:EntityId`	Yes (if any SAML IdP is configured)	Any URL/URI, e.g. `https://app.example.com`	SP Entity ID — your app's base URL
`Scheme`	Yes	URL-safe string, e.g. `azure-saml`, `corp-sso`	Short key used in login and callback URLs. Must be unique per IdP.
`DisplayName`	Optional	Any string	Human-readable name shown in provider lists
`IdpType`	Optional	`Custom` (default), `AzureAd`, `Okta`, `GoogleWorkspace`	Pre-set that auto-resolves metadata URL and entity ID for well-known providers
`AzureTenantId`	Required if `IdpType: AzureAd`	Azure tenant GUID	Auto-resolves the generic Azure tenant federation metadata URL and default IdP entity ID.
`MetadataUrl`	Recommended	HTTPS URL	IdP federation metadata URL — auto-fetches and refreshes signing certificates. For Azure Enterprise Application SAML, use the explicit App Federation Metadata Url when tenant-level metadata is not sufficient.
`SingleSignOnUrl`	Required if no `MetadataUrl`	HTTPS URL	IdP SSO endpoint for manual config
`IdpEntityId`	Required if no `MetadataUrl`	URI string	IdP entity ID for manual config
`SigningCertificateBase64`	Optional, manual config only	Base64-encoded DER certificate	IdP signing certificate. Not needed when using `MetadataUrl`.
`EmailClaimType`	Optional	URI or attribute name	SAML attribute name for the user's email. Default: `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress`
`AllowUnsolicitedAuthResponse`	Optional	`true` / `false`	Allow IdP-initiated SSO (unsolicited assertions). Default: `true`

For Azure specifically, AzureTenantId is enough for many setups because the broker can derive the tenant metadata URL internally. If Azure SAML certificate validation does not line up with that generic metadata, set MetadataUrl explicitly to the App Federation Metadata Url from the Azure Enterprise Application.

Next Steps

Integration Guide — complete setup walkthrough from install to first authenticated request
Endpoint Reference — complete request and response shapes for SAML and all other endpoints
MFA Deep Dive — add multi-factor authentication on top of SAML SSO
Database Setup — persist provisioned SAML users with EF Core

Step 1: Install the package​

Step 2: Configure Program.cs​

Step 3: Configure appsettings.json​

With a metadata URL​

Auth0 SAML​

Manual config (no metadata URL available)​

Step 4: Configure endpoints​

Multiple SAML IdPs​

User provisioning​

Email claim mapping​

IdP-initiated SSO​

Configuration reference​

Next Steps​