Development considerations

The reference ID is a long hexadecimal string. Length is determined by the Reference Length setting in the Reference ID Adapter instance configuration. The default length is 30 bytes.

For example:

Each reference ID is specific to the instance of the Reference ID Adapter that issued it.

During the attribute pickup or drop-off processes, PingFederate returns any errors as HTTP status codes. For example when an incorrect client ID or password is provided, PingFederate returns a 401 HTTP error.

If an error occurs during an authentication attempt, then the authentication form should handle the error (that is, display a message to the user) and abort the sign on process. Your application will only receive a sign-in request from a user that was authenticated by the identity provider (IdP). Failed authentications are not redirected back to the application. Any errors received during the authentication process should be handled with the assumption that the user has already completed the authentication process at the IdP.

If your application presents an invalid reference ID to PingFederate, the Reference ID Adapter returns an empty set of attributes.

A given reference value can only be used once and expires after a set duration. This improves security by preventing "replay" attacks. The duration is determined by the Reference Duration field in the Reference ID Adapter instance configuration. The default duration is three seconds.

To prevent unexpected timeouts, make sure the clock is reasonably synchronized between the application server and the federation server. You can also adjust the value of the Reference Duration configuration setting can also be used to allow for a larger tolerance for time skew.

The IdP adapter should maintain a session for the user so that subsequent calls for authentication can re-use the existing sign-on session. This creates a single sign-on experience for the user.

The IdP adapter should honor the forceAuthn parameter to force the user to enter credentials even if the user has an existing session.

Deep linking (also called direct linking) is the ability to link to a page nested inside the protected content. This saves the user from having to navigate to the content from a generic landing page.

Your application receives a deep link in the TargetResource parameter. This parameter is included in the initial redirect to the sign-on URL.

Your application should honor this URL during the sign-on process by redirecting the user to the deep link after the application session is created. When recovering from a timeout or other scenario that might require re-authentication, your application should include the requested URL in the request.

Authorization includes determining whether the user has access to the application and what roles the user has when they are inside the application.

Your service provider application will only receive users that have already been authenticated. Your application should perform any authorization decisions before creating an application session.

Your application will receive an already authenticated user from a trusted identity provider that can contain additional attributes. This authenticated identity can be used to provision new accounts into the application store or update existing user profile information.