Free trial

OneSpan Sign Developers: OAuth Event Notification for Salesforce – Part 2

eSignature developers
Duo Liang,
OneSpan-BlogImage-OAuth-Event-Notification-for-Salesforce-Part2.jpg

In the recent release, OneSpan Sign introduced a new callback service which implements the Salesforce OAuth 2.0 Refresh Token Flow, and it’s now possible to set up a callback listener in Salesforce! In part 1 of this blog series, we demonstrated how to create a connected application in Salesforce and to retrieve a working refresh token.

Picking up where we left off, in this blog, we will showcase how to validate, revoke, and rotate the refresh token and how to supply the refresh token to OneSpan Sign via API. Let’s get started! 

Test Your Refresh Token

By the end of the previous blog, we followed the steps to retrieve a refresh token. Before supplying it to OneSpan Sign, we can perform a quick test at the local, by building a URL out of below template and opening it in a browser:

https://login.salesforce.com/services/oauth2/token?client_id={your_client_id}&grant_type=refresh_token&refresh_token={the_refresh_token}

This Salesforce API renews the session followed by the OAuth 2.0 Refresh Token Flow, which is similar to the call OneSpan Sign service utilizes behind the scene. A valid refresh token returns an access token which appears as such:

4-7-1

Refresh Token Rotation

Under the default security policy, the refresh token will be valid until revoked. Hence it’s important to rotate the refresh token often or alternatively update the OAuth policy settings, to prevent any potential security risks. 

In order to revoke current refresh token, build below link and open it in your browser:

https://login.salesforce.com/services/oauth2/revoke?token={your_refresh_token}

The browser won’t return anything, but you can verify the revocation by reproducing above section.

Alternatively, you can update the OAuth policy settings if you followed below distinct steps:

  • In lightning experience, Navigate to setup and search “App Manager”
  • Find the connected app we registered, expand the dropdown, and choose “Manage” 
  • Hit the “Edit Policies” button and find the “OAuth Policies” section

 4-7-2

Once the refresh token was revoked or expired, retrieve the latest refresh token, update it via OneSpan Sign service (covered in below section) and perform smoke tests to avoid impacting your business due to down time. 

Update OneSpan Sign Callback Service

Once you have fully configured the connected app and exposed a callback endpoint, you must update the OneSpan Sign callback service with your configurations. This is done using the following API calls:

HTTP Request

POST /api/callback/connectors/salesforceOauth2

HTTP Headers

Content-Type: application/json
Accept: application/json
Authorization: Basic api_key

Example Payload

{
  "url": "https://yourdomain.salesforce.com/services/apexrest/oss/callback",
  "events": ["PACKAGE_COMPLETE","PACKAGE_DECLINE"],
  "key": "eyJob3N0IjoibG9naW4uc2FsZXNmb3JjZS5jb20iLCJjbGllbnRfaWQiOiIzTVZHOWRaSm94eHhSeXFpcGpHY2lYbzU2MUZnIiwicmVmcmVzaF90b2tlbiI6IjVBZXA4NjF2eHh4UTYzeHE3MG85dXNEeiJ9"
}

Note:

  • “url” points to the callback URL. We will demonstrate how to expose a Salesforce REST endpoint in next blog.
  • You can add any callback events listed in the “Setting Up Callback Notifications” guide.
  • “key” is a base64 encoded structure following below format:

 

{"host":"login.salesforce.com","client_id":"3MVG9dZJoxxxRyqipjGciXo561Fg","refresh_token":"5Aep861vxxxQ63xq70o9usDz"}
  • The “host” refers to either “test.salesforce.com” (SFDC sandbox) or “login.salesforce.com” (SFDC production/developer). It’s not a full URL (without “https://”) and doesn’t refer to your own domain.

Afterwards, you can check the current callback settings with a GET call:

HTTP Request

GET /api/callback/connectors/salesforceOauth2

HTTP Headers

Content-Type: application/json
Accept: application/json
Authorization: Basic api_key

It’s important to be aware that you can define multiple callback settings at the same time - default callback (with Basic authentication), Salesforce callback settings (salesforceOauth2), or other connectors’ settings like SharePoint or Dynamics. However, which callback listener will receive notification determines by the “origin” data in your package JSON. 

Take current version (11.40) for example, if a transaction is created from sender portal or equivalently carries “data” > “origin” : “OSS” in transaction JSON, once an event of interest triggers, the callback framework will deliver the notification to the Salesforce listener, which is registered as “salesforceOauth2”.

There it is. Through today’s blog, you should be able to retrieve, validate, and revoke a refresh token and supply it to OneSpan Sign via callback service API. In next blog, we will finish up this series and demonstrate you a sample integration to Salesforce, where we will implement an Apex Web Services working as a callback listener, and test through the whole integration process. Just stay tuned! 

If you have any questions regarding this blog or anything else concerning the integration of OneSpan Sign into your application, visit the Developer Community Forums. Your feedback matters to us!

OneSpan Developer Community

OneSpan Developer Community

Join the OneSpan Developer Community! Forums, blogs, documentation, SDK downloads, and more.

Join Today
Duo Liang
Duo Liang

Duo Liang is a Technical Evangelist and Partner Integrations Developer at OneSpan where he creates and maintains integration guides and code shares, helps customers and partners integrate OneSpan products into their applications, and builds integrations within third party platforms.

Go To Top
Share