Authentication with Sales Access Tokens

Artykuł
05/08/2023

Overview

Sales Access Tokens offer an alternative method for creating user sessions needed to access the Display Services iframe. This document describes why Sales Access Tokens may be necessary to support your integration and how to integrate them into your application. Typically, native applications and mobile use cases require Sales Access Tokens in order to integrate successfully with Display Services.

Background

To use the Display Services iframe, users will need to have an authenticated session in cookie storage. When the iframe is embedded in a web application, it will automatically pick up the current session from the cookie store for the linkedin.com domain. If no valid session is found, a Sign In button will be presented within the iframe to allow users to sign in to their LinkedIn account.

While this works well within a desktop browser, completing the authentication process may be problematic if the iframe is embedded into a native desktop or mobile application because of the need to open a pop-up window and complete the sign in process through it. In many cases, opening a pop-up, or some of the JavaScript that enables the authentication flow, may be unavailable in the context of the native application, preventing sign in.

Sales Access Tokens were introduced to enable authenticated sessions in these scenarios. Sales Access Tokens can be requested using access tokens granted through a standard three-legged OAuth 2.0 flow. Once a Sales Access token is retrieved, it can be used to authenticate a user's client on their behalf by passing it into the iframe query string.

In this guide, we will walk you through the process of obtaining a Sales Access Token and using it in the Display Services iframe.

Obtaining Permission

In order to generate Sales Access Tokens, your application must be granted the r_sales_nav_display permission.

Obtaining OAuth 2.0 Access Tokens

An OAuth 2.0 access token with r_sales_nav_displayscope will be needed to generate Sales Access Token. Please see the Authorization Code Flow (3-legged OAuth) documentation to learn about how to request an OAuth 2.0 access token.

Obtaining Sales Access Tokens

Once you have an OAuth 2.0 access token, you can obtain a Sales Access Token from the /salesAccessTokens endpoint:

GET https://api.linkedin.com/v2/salesAccessTokens?q=viewerAndDeveloperApp HTTP/1.1
Authorization: Bearer {ACCESS_TOKEN}
X-Restli-Protocol-Version: 2.0.0

Note

A new Sales Access Token can be retrieved at any time, so long as the access token has not expired. Sales Access Tokens have a TTL of 45 minutes.

Storing OAuth 2.0 Tokens and Sales Access Tokens

Now that you have the user's OAuth 2.0 access token and Sales Access Token, you should store the tokens appropriately so that users won't go through the whole flow again next time to get new tokens.

When you are storing the tokens, you should make sure they are encrypted at rest. The OAuth 2.0 access tokens should not be passed to client side. In your datastore, the tokens should be associated with users or sessions so that you can serve same tokens when same users are accessing the integration.

Using the Sales Access Tokens

The Sales Navigator iframe and JS SDK can utilize Sales Access Tokens to provide users an authenticated session without having to log in through the iframe. This is accomplished by sending the Sales Access Token in the sat query parameter to the iframe or JS SDK. See the following example for iframe:

<!-- NOTE: line breaks are added for readability -->
<iframe
  src="https://www.linkedin.com/sales/widget/profile-matching?
     apiKey=YOUR_CLIENT_ID&
     profile=lead&
     firstName=Abraham&
     lastName=Lincoln&
     crmRecordId=3AFXT8CAAY&
     crmOrgId=HV1OX56I8B&
     modules=TopCard2&
     isInlineMode=true&
     version=2.1&
     sat=AIAAQB_AAIAAQAAAAAAAAAgAAAAJGRlOTQ1YmU5LWY1MTQtNDAy"
  width="500"
  height="660"
  frameborder="0"
  type="text/html"
>
</iframe>

Important

When using Sales Access Tokens, version 2.1 must be specified.
When using version 2.1, cookies will be ignored.
The session has the same TTL as the Sales Access Token used to create it. Please refer to Handling of Session/Token Expiry section to learn more about how to handle the limitation gracefully.

Implementing the Launch Experience

When the iframe is initialized with version=2.1 or above, users will be prompted to sign into the iframe if the sat parameter is empty or not included in the query string. After the user successfully signs in, a window.postMessage() event will be sent to the parent window. To listen to the event, you can use a standard event listener for a message event like below and obtain event data from data object:

window.addEventListener("message", function(event) {
  var origin = event.origin; // "https://www.linkedin.com"
  var message = event.data; // "{"message":"Sales Navigator Authentication Succeeded","type":"salesNavAuthSuccess"}"
});

If the origin value is "https://www.linkedin.com" and message value is "{"message":"Sales Navigator Authentication Succeeded","type":"salesNavAuthSuccess"}", handle this event and launch the authorization code grant flow, as described in the Obtaining OAuth 2.0 Access Tokens step. After the token is retrieved via your server-side exchange for the authorization code, you can redirect the client's iframe to a new iframe URL that contains the Sales Access Token.

Handling of Session/Token Expiry

When the Sales Access Token passed to the iframe is invalid/expired or the iframe session created by Sales Access Token has expired, the parent window of the iframe will be notified. Your application should fetch a new Sales Access Token using a valid OAuth 2.0 access token and reload the iframes with the new Sales Access Token.

The expiry event will be passed to parent window by window.postMessage() method. To listen to the event, you can use a standard event listener for a message event like below and obtain event data from data object:

window.addEventListener("message", function(event) {
  var origin = event.origin; // "https://www.linkedin.com"
  var message = event.data; // "{"message":"Sales Access Token denied.","type":"tokenError"}"
});

If the origin value is "https://www.linkedin.com" and message value is "{"message":"Sales Access Token denied.","type":"tokenError"}", reload the iframe with a new Sales Access Token to regain authenticated session.

Handling Token Refreshing

Standard OAuth 2.0 access tokens last 60 days. You can request a new OAuth 2.0 access token for a user by sending them through the Obtaining OAuth 2.0 Access Tokens step again if the user's OAuth 2.0 token has expired or become invalid. Refresh tokens are also available for extending access for up to 180 days after the initial grant. This functionality must be enabled for your application, if you are interested in using refresh tokens please reach out to developer support.

Sales Access Tokens have a TTL of 45 minutes. They will need to be refreshed regularly as described above. You can request a new Sales Access Token at any time with active OAuth 2.0 access token.

Note

There are a few suggestions for ensuring that a valid Sales Access Token is sent to initialize the iframe:

Store valid OAuth 2.0 access tokens and Sales Access Tokens and their TTL on server side
Reuse existing Sales Access Tokens if they are still valid and request new Sales Access Tokens when they are about to or already expired

Logout from authentication

Your users might want to logout from the authentication or switch to a different LinkedIn account within your product. In this case, your product should provide "logout" or "unlink" option for users after they have successfully authorized the authentication. The tokens stored on both client or server should be removed upon logout.