.NET Integration Kit

SP single sign-on integration

When PingFederate is configured as a service provider (SP), it receives an inbound SAML assertion, extracts the user attributes, and encodes them into an OpenToken that is delivered to the target application using a form POST (default), a query parameter, or a cookie depending on the Transport Mode configured in the SP adapter instance. The application reads the OpenToken using the Agent class from the .NET 8 OpenToken Agent to establish the user’s session.

Reading attributes

The readToken method inspects the incoming HttpRequest for an OpenToken, decrypts and parses it, and returns a Dictionary<string, string> of attributes.

The transport mode is determined automatically from the agent-config.txt file downloaded from PingFederate:

Cookie

When use-cookie=true, the agent reads the token from the cookie.

Query parameter or form POST

When use-cookie=false, the agent first checks the query string, then falls back to the POST form body. No code change is needed between these two modes.

If no token is present, the method returns null. If the token is present but can’t be decoded, PingFederate returns a TokenException. The Agent.LastError property provides a description of the error when null is returned.

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

using opentoken;

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

try
{
    Dictionary<string, string>? userInfo = agent.ReadToken(Request);
    if (userInfo != null)
    {
        string username = userInfo[Agent.TOKEN_SUBJECT];
        // Establish user session...
    }
    else
    {
        // No token present — agent.LastError contains the reason
    }
}
catch (TokenException e)
{
    // Handle token decoding error
}

Receiving multi-value attributes

The Agent Toolkit for .NET supports receiving multi-value attributes from PingFederate. Multi-value attributes are passed using the opentoken.MultiStringDictionary collection.

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

try {
   MultiStringDictionary userInfo =
    agent.ReadTokenMultiStringDictionary(Request);
   if(userInfo != null) {
      String username = userInfo[Agent.TOKEN_SUBJECT][0];
      List<String> groups = userInfo["GROUP"];
   }
}
catch(TokenException e) {
   // Handle exception
}