.NET Integration Kit

IdP single sign-on integration

When PingFederate is configured as an identity provider (IdP), it needs to be able to identify a user prior to issuing a SAML assertion for that user. When using the OpenToken Adapter with PingFederate, this means that the PingFederate server attempts to read a cookie or query parameter containing an OpenToken and then use the values within to identify the user. The application that starts the SSO must include an OpenToken so that PingFederate can identify the user. Use the Agent API to write an OpenToken. The API is a .NET object that provides access to functionality for writing an OpenToken to a given HTTP response.

Writing attributes

The writeToken method takes 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 thrown.

The following code snippet shows the writeToken method:

IDictionary userInfo = new Dictionary<String, String>();
// Add userId for the logged on user as the token subject
userInfo.Add(Agent.TOKEN_SUBJECT, <userId>);
String returnUrl = "https://<PingFederate DNS>:9031" + Request["resume"];
. . . .
try {
   UrlHelper urlHelper = new UrlHelper(returnUrl);
   agent.WriteToken(userInfo,Response,urlHelper,false);
   returnUrl = urlHelper.ToString();
}
catch(TokenException e) {
  // Handle exception
}

Passing multi-value attributes

The Agent Toolkit for .NET supports passing multi-value attributes to PingFederate. Each attribute appears in its own discrete <AttributeValue> element in the SAML 2.0 assertion or as a JSON array value in OAuth-based protocols. Multi-value attributes are passed using the opentoken.MultiStringDictionary collection.

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

MultiStringDictionary userInfo = new MultiStringDictionary();
// Add userId for the logged on user as the token subject
userInfo.Add(Agent.TOKEN_SUBJECT, <userId>);

// Add an attribute GROUP with multiple values
userInfo.Add("GROUP", "Administrators");
userInfo.Add("GROUP", "Users");
String returnUrl = "https://<PingFederate DNS>:9031" + Request["resume"];
. . . .
try {
   UrlHelper urlHelper = new UrlHelper(returnUrl);
   agent.WriteToken(userInfo,Response,urlHelper,false);
   returnUrl = urlHelper.ToString();
}
catch(TokenException e) {
   // Handle exception
}