When PingFederate is configured as an 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 Agent API is a PHP object that provides access to functionality for writing an OpenToken to a given HTTP response.

The Agent Toolkit for PHP makes use of Namespaces, which enable the Agent API to be auto-loaded with other applications. For more information on auto-loading, see Autoloading Classes in the PHP documentation.

Note: The sample code in this guide assumes that the Agent APIs are already loaded.

The following is sample code for auto-loading. Other auto-loading frameworks such as Zend can be used instead.


Instantiating the agent object is done simply by invoking a constructor, as in the example below:

   use pingidentity\opentoken\agent;
   $myagent = new Agent();

When the agent object is instantiated, it uses the config.php file to find the configuration data generated when the OpenToken Adapter was configured. This configuration data includes the name of the cookie that the agent object will write, as well as the key to use when encrypting a new OpenToken. If the file specified in config.php is not found, the agent constructor will throw an exception.

The writeTokenToHTTPResponse method takes an array of attributes and encodes them into an OpenToken, which is then written to the HTTP response.

Note: The array of attributes parameter must contain a key named “subject” in order for a valid token to be generated.

If any errors are encountered while creating the token or writing it out to the response, the lastError attribute of the agent instance will contain a message with a description of the error.