Embedding the In-App Marketplace

How Does the In-App Marketplace Work?

The Pandium In-App Marketplace product offering is designed to be displayed in an iframe within a web app that sits behind your company's login. In order to maintain the security of your user's data, we suggest that you stand up a backend service that redirects to the Pandium In-App Marketplace with your user's information encoded in a JSON Web Token (JWT).

This single sign-on (SSO) mechanism that allows your site to pass information about your users to Pandium and tells Pandium that the user has been authenticated. Pandium uses that information to securely display your users’ specific integration configurations without an extra login.

Note: The Marketplace and related features are not included in the Pandium Lite offering.

How to Embed the Marketplace

Prerequisites

Before your site can be enabled for SSO via JWT with Pandium, you will need to reach out to the Pandium support and exchange the below:

• A shared secret supplied by Pandium. This is used to sign the JWT, and helps Pandium ensure the requests come from you and you alone.

• If embedding a Pandium Marketplace in your application, we'll also need the domain of the application that will serve as the iframe's parent. Pandium needs this for CORS purposes.

  • Note: If you are using a Sandbox or PoC environment, we will not need the domain.

Getting Started

Your application will need to direct your users to a url that looks similar to the below:

https:/imp.pandium.io/<account>?tenant=<signed_jwt_token> if using a production Pandium account.

https:/imp.sandbox.pandium.com/<account>?tenant=<signed_jwt_token> for Sandbox Pandium accounts.

https:/imp.demo.pandium.com/<account>?tenant=<signed_jwt_token> for Pandium trial accounts (PoCs).

Pandium customers typically embedded this URL as an iframe in their applications or pop-out to a new tab or window.

The account name is a version of your company name, and will either be provided to you, or, if you have already received your login information from Pandium for your In-App Marketplace, you can find it in the url, e.g. https:/imp.sandbox.pandium.com/yourcompanyname?tenant=.

With this, Pandium will take the token and display a list of all integrations that the user can install. You can also deep link to user's installed integrations, or a specific integration in the marketplace.

Framework of a Sample Backend Service in Python

import time
import uuid

import falcon
from jwt import encode


class PandiumSSOJWTEndpoint:
    def __init__(self, config):
        self.config = config

    def on_get(self, req: falcon.Request):

        payload = {
            'iat': int(time.time()),
            'jti': str(uuid.uuid4()),
            'external_id': '',  # Not Required. Add this if the unique id you use for your user is not the same as email address
            'meta': '',  # Not Required. Free form object to associate with your user in Pandium
            'sub': '',  # Required. Email address of your user. Pandium uses this to link our tenant to your user's account in your system
        }

        jwt = encode(payload, self.config['PANDIUM_SHARED_SECRET'], algorithm='HS256')
        sso_url = f"https://{self.config['PANDIUM_SUB_DOMAIN']}.go.pandium.com/?tenant={jwt}"

        raise falcon.HTTPTemporaryRedirect(sso_url)


app = falcon.API()
app.add_route('/pandium-sso', PandiumSSOJWTEndpoint({'PANDIUM_SHARED_SECRET': '', 'PANDIUM_SUB_DOMAIN': ''}))

Creating the Signed JSON Web token

You will need to build a JWT containing the users’ data in a backend service.

JWTs are made of 3 parts separated by a period (.). Each piece is base64Url encoded which then gets assembled to look like below:

<base64url-encoded header>.<base64url-encoded payload>.<baseurl-encoded signature>

Header:

Pandium currently supports the following header:

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

The base64url-encoded version of the above is below:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9

{
 "iat": 1621521641,
 "jti": "1cfa7dbf-8110-4237-ad22-410608791b7d",
 "ti": {
   "udn": "Pandium Test",
   "ufn": "Important Person",
   "uem": "[e-mail]",
   "ili": [
     "new-id",
     "something-different"
   ],
   "aid": "",
   "adn": "",
   "xti": {
     "extraProp": "extra value",
     "extraList": [
       "bla",
       "listVal"
     ]
   }
 },
 "sub": "test-pandium-com"
}

Signature:

The JWT signature is produced by concatenating the Base64url encoded header with the Base64url encoded claims, and then signing using the shared secret using HMAC with SHA-256.

HMAC-SHA256(base64url-encoded(header) + "." + base64url-encoded(payload)), <shared secret>)

A Complete Example.

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
    .eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ
    .SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c