Integrating the OpenToken agent into your .NET 8 application

To use the .NET Integration Kit, add a reference to opentoken-agent.dll in your ASP.NET Core 8 project and modify your application to use the Agent class.

The Agent class provides methods to read, write, and delete OpenToken directly from ASP.NET Core HttpRequest and HttpResponse objects.

Adding the reference

Add opentoken-agent.dll as a project reference or place it in your project’s dependencies. The assembly is built against net8.0 and is forward-compatible with .NET 9, and .NET 10 based on .NET’s backward compatibility guarantee. The assembly requires the Microsoft.AspNetCore.App framework reference.

Instantiating the reference

Instantiate the Agent by passing the path to your agent-config.txt configuration file, which is downloaded when you configure the OpenToken adapter in PingFederate. If the file isn’t found or is invalid, the constructor returns an IOException.

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

Alternatively, you can instantiate the Agent using a Stream or pre-built AgentConfiguration object fr programmatic configuration:

// From a stream
Agent agent = new Agent(configStream);

// From an AgentConfiguration object
AgentConfiguration config = new AgentConfiguration();
config.SetPassword("mypassword", Token.CipherSuite.AES_128_CBC);
Agent agent = new Agent(config);

Sample code

The following example shows how to write and read an OpenToken in an ASP.NET Core 8 controller:

Writing a token (IdP application)

using opentoken;
using opentoken.util;

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

var attributes = new MultiStringDictionary
{
    { "subject", username },
    { "email", userEmail }
};

// Build the PingFederate resume URL, write the OpenToken, and redirect
string redirectUrl = GetPingFederateBaseUrl().TrimEnd('/') + resumePath;

UrlHelper urlHelper = new UrlHelper(redirectUrl);
agent.WriteToken(attributes, Response, urlHelper, false);
Response.Redirect(urlHelper.ToString(), true);

Reading a token (SP application)

using opentoken;

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

Dictionary<string, string>? attributes = agent.ReadToken(Request);
if (attributes != null)
{
    string subject = attributes["subject"];
    // establish a session...
}
else
{
    // agent.LastError contains the reason
}

Deleting a token

agent.DeleteToken(Response);

The Agent class uses ASP.NET Core’s Microsoft.AspNetCore.Http.HttpRequest and HttpResponse types, not the legacy System.Web equivalents. Ensure your application targets net8.0 or later and references Microsoft.AspNetCore.App.