.NET Integration Kit

IdP single sign-on integration

When PingFederate is configured as an identity provider (IdP), it must identify a user before issuing a SAML assertion. When using the OpenToken Adapter, PingFederate reads a cookie, query parameter, or form post data parameter containing an OpenToken to identify the user. The application that initiates the SSO flow is responsible for writing that OpenToken. Use the Agent class from the .NET 8 OpenToken Agent to write an OpenToken to the ASP.NET Core HttpResponse.

Writing attributes

The writeToken method accepts a System.Collections.IDictionary collection of attributes and encodes them into an OpenToken, which is then written to the HTTP response.

The collection of attributes must contain a key named subject.

If any errors are encountered while creating or writing the token to the HTTP response, a TokenException is returned.

The following code snippet shows how to write an OpenToken in an ASP.NET Core 8 controller:

using opentoken;
using opentoken.util;

// Instantiate the agent using the agent-config.txt downloaded from PingFederate
Agent agent = new Agent("<PATH_TO_FILE>/agent-config.txt");

IDictionary<string, string> userInfo = new Dictionary<string,
string>();

// Add the authenticated user's ID as the token subject
userInfo.Add(Agent.TOKEN_SUBJECT, userId);
// Build the PingFederate resume URL from the incoming request
string? resumePath = Request.Query["resume"];
string returnUrl = "https://<PingFederate-host>:9031" + resumePath;
try
{
    UrlHelper urlHelper = new UrlHelper(returnUrl);
    agent.WriteToken(userInfo, Response, urlHelper, false);
    returnUrl = urlHelper.ToString();
    Response.Redirect(returnUrl, true);
}
catch (TokenException e)
{
    // Handle exception
}

In ASP.NET Core 8, query parameters are accessed using Request.Query["resume"] rather than Request["resume"] as in the legacy .NET Framework integration.

Passing multi-value attributes

The .NET 8 OpenToken Agent supports multi-value attributes. Each value appears in its own <AttributeValue> element in the SAML 2.0 assertion, or as a JSON array value in OAuth-based protocols. Pass multi-value attributes using the opentoken.MultiStringDictionary collection.

The following code snippet shows how to pass multi-value attributes:

using opentoken;
using opentoken.util;

Agent agent = new Agent("<PATH_TO_FILE>/agent-config.txt");

MultiStringDictionary userInfo = new MultiStringDictionary();

// Add the authenticated user's ID as the token subject
userInfo.Add(Agent.TOKEN_SUBJECT, userId);

// Add an attribute with multiple values
userInfo.Add("GROUP", "Administrators");
userInfo.Add("GROUP", "Users");

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

try
{
    UrlHelper urlHelper = new UrlHelper(returnUrl);
    agent.WriteToken(userInfo, Response, urlHelper, false);
    returnUrl = urlHelper.ToString();
    Response.Redirect(returnUrl, true);
}
catch (TokenException e)
{
    // Handle exception
}