SP single sign-on integration using account linking

If a service provider (SP)’s single sign-on (SSO) implementation employs account linking, the flow of events differs from standard SSO because the user must authenticate to the SP application the first time SSO is initiated. Learn more in Key concepts in the PingFederate documentation.

PingFederate and the OpenToken Adapter support this by redirecting the user to a configured Account Link Service where the user authenticates locally. Upon successful authentication, the user’s browser is redirected back to PingFederate with an OpenToken, which PingFederate uses to establish an account link for the user. For subsequent SSO requests, PingFederate uses that account link to identify the user. It then creates an OpenToken and sends it to the application’s Authentication Service.

PingFederate receives an assertion under either the SAML 2.0, OpenID Connect, or WS-Federation protocol.
If this is the user’s first SSO to this SP, PingFederate redirects the browser to the application’s Account Link Service. Upon successful authentication, an OpenToken containing the user’s identity is created, and the browser is redirected back to PingFederate, which establishes a persistent account link for that user.
For this and all subsequent SSO requests, PingFederate retrieves the local user ID from its account link data store, generates an OpenToken via the SP adapter, and redirects the browser to the application’s Authentication Service.
The Authentication Service reads the OpenToken, establishes a session for the user, and redirects to the target resource.

Linking accounts

When PingFederate redirects the browser to the Account Link Service, a resume query parameter is included in the request. The Account Link Service must authenticate the user locally, write an OpenToken containing the user’s identity, and redirect back to PingFederate using the resume path.

The token is delivered to PingFederate based on the transport mode configured in agent-config.txt:

Cookie: When use-cookie=true, the token is written as a cookie on the response.
Query parameter: When use-cookie=false, the token is appended to the redirect URL as a query parameter, and Response.Redirect is called.

The following code snippet shows how to handle an account linking request in an ASP.NET Core 8 controller:

using opentoken;
using opentoken.util;


// User has authenticated locally — build the attributes to send back to PingFederate
var attributesToSend = new MultiStringDictionary
{
    { Agent.TOKEN_SUBJECT, userId }
};


// Add any additional attributes required by the SP adapter's
// extended contract


attributesToSend.Add("email", userEmail);


// Build the PingFederate resume URL
string? resumePath = Request.Query["resume"];
string returnUrl = "https://<PingFederate-host>:9031" + resumePath;


try
{
    Agent agent = new Agent("<PATH_TO_FILE>/agent-config.txt");
    UrlHelper urlHelper = new UrlHelper(returnUrl);
    agent.WriteToken(attributesToSend, Response, urlHelper, false);
    returnUrl = urlHelper.ToString();
    Response.Redirect(returnUrl, true);
}
catch (TokenException e)
{
    // Handle exception
}

In ASP.NET Core 8, the resume query parameter is accessed using Request.Query["resume"] rather than Request["resume"] as in the legacy .NET Framework integration. The WriteToken call delivers the token to PingFederate either as a query parameter appended to the redirect URL (when use-cookie=false) or as a cookie (when use-cookie=true), as configured in agent-config.txt.

.NET Integration Kit

SP single sign-on integration using account linking

Linking accounts