Artifact-Message Persistence and Retrieval Service
PingFederate’s Artifact-Message Persistence and Retrieval Service keeps track of one-time keys and associated data compliant with SAML and OAuth 2.0 standards.
The following standards require PingFederate to relay data to partners using a reference-style data transportation model and to guarantee that the reference keys are valid for one-time use only.
- SAML artifact binding
-
PingFederate sends an artifact to the partner when transmitting SAML-outbound messages using the artifact binding. Later, 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 a code to the client based on 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.
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 keeps track of the key and the associated data until the partner contacts the PingFederate server to exchange the key for the data.
Group RPC-based retrieval
When multiple PingFederate servers are deployed to form a cluster, the keys and their data are saved in the server that creates them. Because they are not replicated to other PingFederate servers, it is possible for a key resolution request to arrive at a server that does not contain the requested data. To handle this scenario, the Artifact-Message Persistence and Retrieval Service uses a group Remote Procedure Call (RPC) retrieval approach, where the server handling the key resolution request determines the data-hosting server based on the key value and contacts the appropriate 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. NOTE: The Artifact-Message Persistence and Retrieval Service also supports a local memory approach for SAML 2.0. This approach is only suitable in clustered environments where the OAuth 2.0 authorization code grant type and the Reference ID Adapter are not in use.
When PingFederate is in clustered mode, the service proxy selects a group RPC-based implementation, which takes advantage of node indexing but not the preferred-nodes concept. Sticky-session load-balancing strategies are not effective when the key request 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, you can configure the RPC time-out in the <pf_install>/pingfederate/server/default/conf/cluster-artifact.conf file.
SAML 2.0 indexing (local memory)
A SAML 2.0 federation entitycan 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.
With this approach, partners must know about each of your backend 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. |
For example, if you have four servers in a cluster, the list might look like this:
<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 0 in standalone mode).
Partners also need direct access to each ARS endpoint, which can complicate your configuration of load balancers, proxies, and firewalls. This approach 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 <pf_install>/pingfederate/server/default/conf/service-points.conf file and change the implementation for the artifact.store service point to the class name org.sourceid.saml20.service.impl.localmemory.ArtifactPersistenceServiceMapImpl.