Securing URL Redirects and API Interactions

Overview

When integrating with AlphaTrust® e-Sign, your application may receive redirects or data from various sources, such as Custom Workflow Action URLs, Subscription Event URLs or POST bodies, or ClientReturnUrl (used when redirecting to a downstream system after exiting the application). These interactions often include query string parameters or POST body data that allow you to make API calls to AlphaTrust® e-Sign to retrieve or update data. However, users could potentially modify these parameters (e.g., IDs) to access unauthorized data, posing a security risk.

To mitigate this, AlphaTrust includes a ps_securitytoken parameter in redirect URLs or POST bodies. This short-lived security token can be passed to the GetTransactionTokenData() web service method to retrieve a TransactionTokenDataModel object containing the authentic parameter values directly from AlphaTrust. This ensures the parameters have not been tampered with, allowing you to safely query or update data in your application.

Use Cases

The ps_securitytoken is applicable in the following scenarios:

• Custom Workflow Action URLs: URLs triggered during a workflow to perform custom actions, such as updating transaction data.
• Subscription Event URLs or POST Bodies: Data sent to your application via webhooks or event notifications, including transaction or participant details.
• ClientReturnUrl: Redirect URLs used when a user exits the AlphaTrust application and is sent to a downstream system, often after authentication or transaction completion (e.g., in Authentication Only mode, see Authentication Only).

Securing Interactions with ps_securitytoken

When your application receives a redirect URL or POST body from AlphaTrust, it may include parameters like TransID, DocID, SigID, or PartID. To prevent unauthorized access, always validate these parameters using the ps_securitytoken included in the request.

Steps

1. Extract the Security Token: Retrieve the ps_securitytoken from the query string (for URLs) or POST body (for Subscription Events).
2. Call GetTransactionTokenData(): Pass the token to the GetTransactionTokenData() method to retrieve the TransactionTokenDataModel object.
3. Verify Parameters: Compare the parameters in the TransactionTokenDataModel with those in the URL or POST body to ensure they match.
4. Proceed with API Calls: Use the verified parameters to make secure API calls or update your application state.

Example Query String

A redirect URL from AlphaTrust (e.g., a Custom Workflow Action or ClientReturnUrl) might look like this:

?ps_action=CUSTOM&ps_actno=1&ps_actstep=1&TransID=1000261829&DocID=1000467602&SigID=1000681444&at=E8CFF493453046170EA384F625F214A66463B1D3&PartID=1000154729&pat=0D8DB3C997E3A719330448A0BAB16D0C4CF19ED6&ps_securitytoken=7394fd62-dc98-45a1-9c13-7bdd7bfc7aba&ps_r=4484327

The ps_securitytoken (7394fd62-dc98-45a1-9c13-7bdd7bfc7aba) is passed to GetTransactionTokenData() to retrieve verified parameter values, such as TransID, DocID, and PartID.

Example POST Body (Subscription Event)

A Subscription Event POST body might include:

{
    "TransID": "1000261829",
    "PartID": "1000154729",
    "ps_securitytoken": "7394fd62-dc98-45a1-9c13-7bdd7bfc7aba"
}

Use the ps_securitytoken to validate the accompanying data.

Token Expiration

Example: Validating the Security Token

Below is a C# example demonstrating how to validate the ps_securitytoken using the GetTransactionTokenData() method:

private TransactionTokenDataModel GetSecurityTokenData()
{
    var token = Request.QueryString["ps_securitytoken"];
    var req = new TransactionTokenDataRequestModel();
    req.SecurityToken = token;
    var results = sc.GetTransactionTokenData(sa, req);
    if (results.IsSuccessful.Value)
    {
        return results.TokenData;
    }
    else
    {
        // Handle error
        return null;
    }
}

Explanation

• Extract Token: Retrieves the ps_securitytoken from the query string (or POST body, depending on the context).
• API Call: Passes the token to GetTransactionTokenData() with a TransactionTokenDataRequestModel.
• Result Handling: Returns the TransactionTokenDataModel if successful, which contains verified parameters, or handles errors if the token is invalid or expired.

Best Practices

• Validate Immediately: Call GetTransactionTokenData() as soon as the redirect or POST request is received to verify parameters before processing.
• Store Token Data: Cache the TransactionTokenDataModel data in your application to avoid repeated API calls, especially for long user interactions.
• Use HTTPS: Ensure all redirect URLs and POST endpoints use HTTPS to protect the ps_securitytoken and other sensitive data.
• Handle Errors Gracefully: Implement fallback logic for expired or invalid tokens, such as redirecting the user to re-authenticate (see Authentication Only).
• Combine with Authentication: For redirects involving user authentication (e.g., ClientReturnUrl after Authentication Only), ensure the token aligns with the authentication method used (see Authentication Methods).

Related Topics

• Authentication Only
• Authentication Methods
• Two-Factor Authentication
• Pass-Through Authentication