The following standards require PingFederate to relay data to partners via a reference-style data transportation model and to guarantee the reference keys are valid for one-time use only.
- SAML artifact binding
- When transmitting SAML outbound messages using the artifact binding, PingFederate sends to the partner an artifact. At a latter time, the partner returns to PingFederate to exchange the artifact for the actual message. If the request is valid, PingFederate delivers the message and invalidates the artifact.
- OAuth 2.0 authorization grant type
- When processing an authorization request from an OAuth client that uses the authorization code grant type, PingFederate returns to the client a code per specification. The client then includes that code in its token request to PingFederate to obtain an access token. If the request is valid, PingFederate delivers the access token and invalidates the code.
Additionally, the Reference ID Adapter from the Agentless Integration Kit also applies the same data transportation model and one-time-use restriction in its drop-off and pick-up operations.
In a standard environment, the PingFederate server saves the data in memory, generates a key for the data, and sends the key to the partner. The Artifact-Message Persistence and Retrieval Service keep tracks of the key and the associated data until the partner contacts the PingFederate server to exchange the key for the data.
When multiple PingFederate servers are deployed to form a cluster, the keys and their data are saved where they are generated. Because they are not replicated to other PingFederate servers, it is possible that a key resolution request can arrive at a server that does not hold the requested data. To handle this scenario, the Artifact-Message Persistence and Retrieval Service uses a group RPC retrieval approach, where the server handling the key resolution request determines the data-hosting server based on the key value and contacts such server to retrieve the requested data. This group RPC implementation is compatible with the SAML artifact binding, the OAuth 2.0 authorization code grant type, and the Reference ID Adapter. The Artifact-Message Persistence and Retrieval Service also supports a local memory approach for SAML 2.0; however, it is only suitable in clustered environments where the OAuth 2.0 authorization code grant type and the Reference ID Adapter are not in -use.
Group RPC-based retrieval
When PingFederate is in clustered mode, the service proxy selects a group RPC-based implementation. This RPC implementation takes advantage of node indexing but not the preferred-nodes concept because sticky-session load-balancing strategies are not effective when the request that results in the issuance of a key and its subsequent key resolution request can come from different locations.
Although this implementation does not take advantage of adaptive clustering or the preferred-nodes concept, it does have a configuration file, <pf_install>/pingfederate/server/default/conf/cluster-artifact.conf, in which the RPC time-out can be configured.
SAML 2.0 indexing (local memory)
Due to the implementation complexity involved in managing state with the artifact binding, the SAML 2.0 specification introduced the concept of indexed endpoints. A SAML 2.0 federation entity may support multiple artifact resolution services, each identified by a unique index number. Artifacts include this index, and a federation partner must send the artifact resolution request to the appropriate endpoint for that index. This means that servers do not need to share information concerning the artifact.
The downside to this approach is that partners must know about each of your back-end servers. Generally, this means providing partners with a list that includes multiple artifact-resolution service endpoints with the corresponding indices.
PingFederate does not automatically generate this information; an administrator must create it and send it to partners who are using the artifact binding.
<ArtifactResolutionService Binding="...” Location="https://node1/idp/ARS.ssaml2" index="1"/> <ArtifactResolutionService Binding="...” Location="https://node2/idp/ARS.ssaml2" index="2"/> <ArtifactResolutionService Binding="...” Location="https://node3/idp/ARS.ssaml2" index="3"/> <ArtifactResolutionService Binding="...” Location="https://node4/idp/ARS.ssaml2" index="4"/>
In this case, the index corresponds to the node index configured in the run.properties file on each individual server. This service encodes the node index in the artifact handle when running in a clustered mode (it will always use an index of zero in standalone mode).
Not only do partners need to know about each back-end server, they need direct access to each ARS endpoint. This may require more complicated configuration of load balancers, proxies, and firewalls. Another drawback to this approach is that it cannot be used for SAML 1.x, or with adapters that utilize PingFederate's artifact-data management.
To use this approach for SAML 2.0 federation deployments, edit the
hivemodule.xml file and change the implementation for the
ArtifactStore service point to the class name: