👍 Important: Ask customer success to enable the App for your store.

The JWT Customer Link for Single Sign-on (SSO) App allows dealers to integrate an external link into their store's menu. When this link is clicked, it will open with a JSON Web Token (JWT) appended to the URL. This JWT contains information about the user, enabling seamless sign-in to the external application. Additionally, dealers can display external content directly on their stores through a widget.

Key features

Seamless Integration: Easily add external links to your application's menu or embed external content using a widget.
Secure Authentication: Use JWTs signed with asymmetric cryptography for secure transmission of user data.
Single Sign-On (SSO): Enhance user experience by enabling SSO capabilities.
DIY Integration: It’s possible to get just the JWT token for custom uses.

Install from the App Store

To install the JWT Customer Link for Single Sign-on app from the App Store, the dealer will need to fill in the following fields:

URL for the link: This URL to be added to the menu and used as a backup if no URL is provided in a widget.
Default Link Label: The name of the menu item.
Show in the 'My account' menu: If ON, it will add a menu item to the 'My account' menu. Turn it off if you only want to use widgets.

After installation, a public key will be available along with the other app credentials. This key must be used to verify the JWT's signature.

JWT details

JWT Header

The JWT header will be:

{
  "typ": "JWT",
  "alg": "RS256"
}

JWT Payload

The JWT will include basic user and customer data, such as:

{
  "iat": 1717420251,
  "exp": 1717420311,
  "user": {
    "id": "1251512",
    "seller_reference": "evox"
  },
  "customer": {
    "id": "1797478",
    "account_number": "1111",
    "seller_reference": "evox"
  }
}

Note: If the external application requires additional data, we recommend using the data provided in the JWT to fetch the necessary details from our API.

JWT Signature

We use asymmetric cryptography, which means the JWT is signed with our private key, and a public key is provided to verify the signature. This ensures the token's authenticity.

The public key will be available in the app credentials after the app is installed.

Token expiration

The JWT token has a 1-minute expiration (indicated by the iat and exp fields). This short expiration time is designed to enhance security.

Example

Given a configured external link: https://externalapp.com/login

The full URL might look like:

https://externalapp.com/login?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3MTc0MjAyNTEsImV4cCI6MTcxNzQyMDMxMSwidXNlciI6eyJpZCI6Im51bGwiLCJzZWxsZXJfcmVmZXJlbmNlIjoiIn0sImN1c3RvbWVyIjp7ImlkIjoibnVsbCIsImFjY291bnRfbnVtYmVyIjoiIiwic2VsbGVyX3JlZmVyZW5jZSI6IiJ9fQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

Preparing your code

How your code should handle the JWT

Proper handling of the JWT token in your code is critical to ensure a secure and effective SSO experience.

Signature Verification: It is crucial that the external application verifies the JWT's signature using our public key. Failure to do so may compromise security.
Handling JWT Expiry: The external application must handle cases where the JWT has expired (after 1 minute from issuance).
User Sign-In: It is the external application responsibility to sign the user into the external website using the data provided in the JWT after completing steps 1 & 2.
Additional Data: If additional data is required, we recommend using the data provided in the JWT to fetch the necessary details from our EvolutionX API.

Your code session management

Your code will still need to manage the user session, session timeout, and logout issues as before. The JWT SSO will only enable you to skip the login UI/UX by relying on the JWT token to sign the user in to your application. You should consider your session management and test these scenarios:

Consider how long your session should last and how an expired session is handled.
A user logout in EvolutionX storefront will not effect your session. Consider if your user needs to be able to log out of your session and how you would offer that.
A user which has been signed in using the SSO JWT token may return again and again with new JWT token SSO requests. This can happen if they click the link again or refresh the page with the iframe widget. You should prepare your code to handle an existing session which is signing in with a token again.

Adding an external link to the menu

In the app configuration, if the Show in the 'My account' menu toggle is set to ON, logged-in users will see an item in the 'My account' menu named according to the Default Link Label. Clicking this item will redirect the user to the specified URL for the link.

Adding an external link through a widget

Adding the widget

Navigate to the Appearance > Layout on EvolutionX.

Choose the specific page where you wish to display the widget.
Select the "JWT Single Sign On" widget from the available options.
Position the widget in the desired location on the page by dragging and dropping it into place.

Note: The widget will only be visible to logged-in users.

Widget configuration

When configuring the widget, the dealer can fill:

Height in pixels: The height of the widget in pixels. This determines the vertical space the widget will occupy on the page, allowing the external content to be displayed correctly.
URL: The URL for the external link. If not provided, the URL from the app configuration will be used.
Title: A title for the external content. While not required, providing a title is beneficial for accessibility.

DIY Integration

Obtaining the JWT Token Directly

If you prefer to handle the JWT token directly within your application, you can call the JavaScript function generateJwt(). This function will return just the JWT token, allowing you to use the token for custom purposes.

Response Format

The function generateJwt() will provide a response in the following format:

{"token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpYXQiOjE3MjAwMTU1MjYsImV4cCI6MTcyMDAxNTU4NiwidXNlciI6eyJpZCI6MTI1MTUxMiwic2VsbGVyX3JlZmVyZW5jZSI6IiJ9LCJjdXN0b21lciI6eyJpZCI6MTc5NzQ3OCwiYWNjb3VudF9udW1iZXIiOiIxMTExIiwic2VsbGVyX3JlZmVyZW5jZSI6IiJ9fQ.2YIQxJVcYS2DoM2GAYr382pO6wj6EY0WtUBzDGq7uZU"}

This response includes a single field:

• token: A string representing the JWT token, which contains encoded user and customer data.

🎉 That's it, have a lovely day!