Overview

A core component of most user journeys through Trinsic is the final redirect back to your application or website.

If you use Hosted Provider Sessions, every Session is redirect-based; if using Direct Provider Sessions, any session with a CaptureRedirect result-collection method is redirect-based.

Handling these redirects correctly and securely is critical for any integration with Trinsic.

---

Quick Guide

1. When a Session is redirect-based, the user will come back to your Session's redirectUrl with a set of Success Parameters or Failure Parameters.
   1. Sessions are redirect-based if they are either A) Hosted Provider Sessions or B) Direct Provider Sessions with a collectionMethod of CaptureRedirect.
2. Success Parameters:
   1. sessionId, redirectToken, and postRedirectAction
   2. Check sessionId against the Session you actually created
   3. Send redirectToken to Trinsic when calling GetSessionResults
   4. postRedirectAction is always either fetch or poll
      1. If fetch, results are available immediately.
      2. If poll, results are not yet available. Poll GetSessionResults.
3. Failure Parameters:
   1. sessionId and redirectReason
   2. redirectReason contains a reason the user was redirected back
      1. SessionFailed means the session failed at some point during the user's interaction with Trinsic or the Provider.
         1. Call Trinsic's API to fetch the Session and inspect its error code for further information.
      2. See below for other possible values

---

Redirect Scenarios

There are three general scenarios in which a user will be redirected back to your application:

1) On Success or Pending

When a Session is successful, the user is redirected back with a set of Success Parameters.

If using Direct Provider Sessions, it is possible that the user is redirected back before a Session is finalized (e.g. because the Provider has not yet finished processing). In this case, Trinsic returns the user with a set of Success Parameters, even though the Session is incomplete. The Session must still be polled until it finalizes or until a time limit set by you is reached.

If using Hosted Provider Sessions, Trinsic performs any necessary polling using the Trinsic UI. Sessions are always complete before the user is redirected back to you in this mode.

You will always receive a redirectToken and a sessionId.

2) On Session Failure

If a user's journey ends with a Session-ending failure (a user refusing consent; a digital signature failing to validate; a Provider being unreachable; etc.) then the user is redirected back with a set of Failure Parameters.

The redirectReason for this scenario will always be SessionFailed.

3) On Non-Session-Ending Failure

If a user's journey ends in a non-Session-ending way, they will be redirected back to your application with a set of Failure Parameters.

For example: if an individual visits an expired or already-used Session launchUrl, Trinsic will immediately redirect them back to your redirectUrl. However, the Session itself will not necessarily fail.

The redirectReason for this scenario will never be SessionFailed.

---

Redirect Parameters

When a user is redirected back to your application, Trinsic will append either a set of Success Parameters or Failure Parameters to the redirectUrl configured during Session creation.

Success / Pending Parameters

These parameters are appended to your Redirect URL when a Session is successful, as well as for Direct Provider Sessions which require post-redirect polling. Every parameter is always present.

Failure Parameters

These parameters are appended to your Redirect URL for all failure conditions (i.e., when a user is not being redirected for a Success reason).

Handling redirectToken

The redirectToken parameter, appended to your Redirect URL on Session success, helps secure the redirect chain against phishing attacks. It's an encrypted, opaque string that only Trinsic can create or decrypt.

Supply the redirectToken when calling GetSessionResults. If valid, the Session's results will unlock, and the redirectToken will not be required for future calls to GetSessionResults for that Session.

Redirect Reasons

Below are all the possible values of the redirectReason parameter. New values may be added to this list over time; unknown values should be handled by your integration (e.g., by defaulting to SessionFailed).

---

Binding User Sessions

redirectToken helps secure the redirect chain at the point where the user is coming back from Trinsic to your application. However, it could be the case (such as during a phishing attack) that the individual who requests a launchUrl to verify themselves while on your application is a different person than the individual who actually visits the launchUrl and performs the verification with Trinsic.

The degree to which these hypothetical attacks can be mitigated depends on a mixture of the Providers involved, your security posture, and the nature of your product.

Ideally, you should re-authenticate the user when they return to your application, requiring them to log in if they do not still have their session cookies. Ensure that the user who is visiting the Redirect URL for a Session is the same as the user who requested the Session's creation.

If your application does not have user authentication or long-term accounts, another possible mitigation is to recontextualize the user with the nature of the verification, and have them positively assert that they wish to share their identity data for the stated purpose.