PingFederate + SAML in .NET Framework and .NET Core

What Usually Goes Wrong

• Metadata and endpoint mismatch between SP and IdP.
• Certificate rollover not handled in validation logic.
• Audience/Recipient mismatch in assertion checks.
• Clock skew causing intermittent token rejection.
• Different middleware behavior in .NET Framework vs .NET Core.

How The Flow Works

In this flow, your app is the Service Provider (SP) and PingFederate is the Identity Provider (IdP). The app sends the user to PingFederate for sign-in, receives a SAML response at Assertion Consumer Service (ACS), validates the response, and then creates a local auth session.

What I Actually Faced

I started in an older .NET Framework codebase, and the first problem was not SAML itself. It was the framework version and the lack of a clean path to wire SSO without turning the code into a mess. OAuth examples were easy to find; SAML on my stack was not.

• I upgraded the application from .NET Framework 4.0 to 4.8.1 to support a modern SAML approach cleanly.
• I used Sustainsys.Saml2 because it matched the application style and reduced custom plumbing.
• The real work was making the ACS, entity ID, and proxy headers line up in the deployed environment.

After that change, the integration became something I could actually maintain and troubleshoot without guessing.

Code I Added to Make It Maintainable

The key was to keep the SAML plumbing away from controllers and keep the claims mapping predictable.

public sealed class SamlOptions
{
    public string EntityId { get; set; } = "";
    public string AcsUrl { get; set; } = "";
    public string IdpMetadataUrl { get; set; } = "";
}

public static class ClaimMap
{
    public static ClaimsIdentity Map(ClaimsIdentity identity)
    {
        var email = identity.FindFirst(ClaimTypes.Email)?.Value ?? "";
        var name = identity.FindFirst(ClaimTypes.Name)?.Value ?? "";
        identity.AddClaim(new Claim("app_email", email));
        identity.AddClaim(new Claim("app_name", name));
        return identity;
    }
}

[HttpPost]
[AllowAnonymous]
public IActionResult Acs()
{
    // Validate the SAML response with the middleware, then create the local auth cookie.
    // The app should only continue after the claim set has been normalized.
    return RedirectToAction("Index", "Home");
}

Simple Analogy

Think of the app as a gated office building. PingFederate is the receptionist at the front desk. The user shows ID, the receptionist checks it, and then hands back a stamped visitor badge. The app only lets the user in after it sees that badge and matches it to the right person.

How The Flow Feels To A User

• The user clicks the app and gets redirected to PingFederate.
• PingFederate checks the login and creates a trusted identity assertion.
• The browser posts that assertion back to your ACS endpoint.
• Your app verifies the proof and creates its own session cookie.
• The user lands back in the app already signed in.

Checklist Before Coding

MVC Mapping: SAML Config to App Flow

Teams often understand SAML settings better when they map each item to a concrete app touchpoint. Use this as a debugging bridge between PingFederate config and MVC behavior.

// Practical MVC flow anchors (conceptual)
// 1) Login endpoint -> triggers SAML challenge
// 2) ACS/callback endpoint -> validates SAML response
// 3) Claims mapping step -> canonical internal claims
// 4) Authorization checks -> controllers/policies use canonical claims only

Real Scenario: SSO Works in Dev but Fails After Deployment

Users click the app, get redirected to PingFederate, and authenticate successfully. The browser comes back to the app, but the deployed environment keeps looping back to login or returns an ACS error.

• Confirm the external URL used by the browser matches the ACS configuration.
• Verify forwarded headers preserve host and scheme behind the proxy.
• Check that the current IdP signing certificate is the one your app trusts.
• Inspect the transformed claims before authorization runs.

The fix is usually not in the login page. It is in the trust chain between browser, proxy, ACS endpoint, and claims mapping.

.NET Framework Notes

• Most teams use OWIN + Sustainsys.Saml2 (or equivalent).
• Ensure cookie auth middleware precedes SAML middleware correctly.
• Watch for old TLS defaults in legacy runtime hosts.

// Typical OWIN order (simplified)
app.UseCookieAuthentication(cookieOptions);
app.UseSaml2Authentication(samlOptions);

MVC Login and Logout Flow (Practical)

Login Flow (SP-initiated)

1. User opens a protected MVC route (for example /orders).
2. MVC auth middleware challenges unauthenticated request to SAML scheme.
3. App sends AuthnRequest to PingFederate.
4. User signs in on PingFederate and returns to MVC ACS endpoint.
5. MVC validates SAML response and issues local auth cookie.
6. User is redirected back to original return URL.

Logout Flow (SP-initiated)

1. User clicks logout in MVC app.
2. App clears local auth cookie/session.
3. App optionally sends SLO request to PingFederate (if configured).
4. PingFederate closes IdP session and returns to post-logout URL.

// MVC intent (simplified)
// Login challenge
return new ChallengeResult("Saml2", new AuthenticationProperties { RedirectUri = returnUrl });

// Logout
await HttpContext.SignOutAsync("Cookies");
await HttpContext.SignOutAsync("Saml2");

.NET Core Notes

• Use ASP.NET Core authentication schemes with explicit default challenge scheme.
• Forwarded headers are critical behind reverse proxy/load balancer.
• Ensure callback/ACS URL uses external host, not internal container host.

// Example intent (simplified)
services.AddAuthentication(options =>
{
    options.DefaultScheme = "Cookies";
    options.DefaultChallengeScheme = "Saml2";
});

High-Value Troubleshooting Sequence

1. Capture browser trace: redirect chain and final ACS POST.
2. Verify SAML response signature and certificate thumbprint.
3. Check Audience, Recipient, and InResponseTo.
4. Validate server clock sync (NTP) and acceptable clock skew.
5. Check relay state and return URL validation logic.

Common SSO Errors and Meaning

Common MVC Issue Scenarios (and Fix Direction)

Identity vs UserIdentity, Token Size, and Cookie Chunking

In many real projects, teams unintentionally duplicate claims across different identity objects (for example, base identity + user identity) or include multiple token payloads carrying similar data. This inflates auth cookie size and introduces random sign-in failures.

What Happens in Practice

• Too many claims are copied from SAML assertion into local auth ticket.
• App stores role/group claims at full source volume instead of app-scoped subsets.
• Additional custom claims are appended in post-auth events, duplicating values.

Symptoms

• Intermittent login loops after successful IdP authentication.
• 400 Bad Request due to header/cookie size limits.
• User works in one browser/network but fails behind some proxies or WAF policies.

Where Token Chunking Helps

Cookie chunking splits large auth cookies into multiple smaller cookies so they can be transported within browser/server limits. It helps transport, but it does not solve root cause claim bloat.

• Use chunking to improve compatibility with large auth tickets.
• Still reduce claims to minimum required set for authorization.
• Prefer reference/session storage model when claim volume is high.

Recommended Pattern

1. Map only essential claims from SAML response.
2. Normalize roles/groups into compact app-specific permissions.
3. Avoid duplicating same values in multiple identities/claim types.
4. Enable chunking if needed, then monitor cookie count/size in browser dev tools.

// Conceptual goal
// 1) keep essential claims only
// 2) enable cookie manager/chunking in auth middleware when required
// 3) validate total response header size across proxy + app stack

Same User Claim, Different Names (Claim Alias Conflicts)

Another common issue is receiving the same user attribute under different claim names. For example, one environment sends email, another sends mail, and a third sends http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress. The value is the same, but app logic can break if it expects only one key.

Typical Conflicting Aliases

• User ID: sub, nameidentifier, uid, custom employee id claim.
• Email: email, mail, emailaddress.
• Display Name: name, given_name + family_name, custom full name claim.
• Roles/Groups: role, groups, custom entitlement claims.

Why It Causes Problems

• Authorization rules check one claim name while token contains another alias.
• Duplicate user profile fields are populated from different sources with inconsistent precedence.
• Different environments behave differently even with “same” SSO configuration.

Recommended Fix Pattern

1. Create a canonical internal claim model (single names your app uses).
2. Map external aliases to canonical claims in one centralized transformation step.
3. Drop redundant aliases after mapping to avoid ambiguity.
4. Use canonical claims only in authorization policies and business logic.

// Conceptual mapping example
// external aliases -> canonical
// mail/email/emailaddress -> app_email
// sub/nameidentifier/uid -> app_user_id
// role/groups -> app_roles

End-to-End Token and Session Lifecycle (Client -> Server -> PingFederate)

This is the practical flow teams should align on so everyone understands where authentication state lives and how it moves.

1) User Authenticates at PingFederate

• User is redirected to PingFederate login.
• PingFederate returns a signed SAML response to your app ACS endpoint.
• App validates signature, audience, recipient, expiry, and correlation.

2) Server Creates Local Auth Session

• After successful SAML validation, app creates local authenticated principal.
• App issues an auth cookie/session ticket to browser.
• This cookie is usually encrypted/signed by server middleware.

3) Client Stores and Sends Session State

• Browser stores auth cookie (subject to domain/path/SameSite/secure flags).
• On next request, browser automatically sends cookie in request headers.
• No fresh SAML roundtrip is needed while local session is valid.

4) Server Validates Cookie on Every Request

• Server decrypts/validates cookie signature.
• Server rebuilds user identity and claims for authorization checks.
• If invalid/expired/malformed, server challenges again to PingFederate.

5) Where It Commonly Breaks

• Cookie too large (claim bloat, duplicate identities, many groups).
• Cookie flags mismatch (SameSite/secure/domain), causing “not sent” behavior.
• Different claim aliases across environments causing logic mismatch.
• Clock skew and cert rollover issues causing token rejection.

6) How PingFederate-Centric Governance Solves It

• Standardize attribute mapping in PingFederate so each user attribute has one meaning.
• Minimize assertion payload to only required app claims.
• Use stable canonical claim transformation in app middleware.
• Enable chunking only as transport support, not as primary fix for bad claim design.
• Document cert rollover and token-lifetime policy as operational runbook.

// Practical ownership model
// PingFederate: identity proof + canonical attribute release
// App middleware: strict validation + claim normalization
// Browser: transport of session cookie only
// App authorization: depends on canonical internal claims

Delivery Hardening Tips

• Monitor IdP cert expiry and test rollover before deadline.
• Log SAML correlation IDs (without logging sensitive assertion payloads).
• Keep a runbook for emergency fallback auth and rapid rollback.
• Automate smoke test for SSO flow after each deployment.