Links

Embedding the Marketplace

Single Sign-on via JSON Web Tokens

Single sign-on (SSO) is a 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. To provide the most seamless experience, we suggest you embed us via an iframe in your application.
A JSON Web Token (JWT) is a technique that can be used for single sign-on between your application and Pandium.

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 you will be embedding a Pandium Marketplace in your application (our recommended approach), then we will 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 environment, this will not be applicable.

Overview

Your application will need to direct your users to a url that looks like below: https:/imp.pandium.io/<account>?tenant=<signed_jwt_token> or https:/imp.sandbox.pandium.com/<account>?tenant=<signed_jwt_token> for sandbox.
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 and link from Pandium for you 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 either a list of all integrations that the user can install or if only one integration is present, then the tenant configuration for that integration.
Pandium customers usually embedded this URL as an iframe in their applications or pop-out to a new tab or window.

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>
Pandium currently only supports the following header:
{
"alg": "HS256",
"typ": "JWT"
}
The base64url-encoded version of the above is below:
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9

Payload:

The JWT payload is where your application will encode the pieces of information, or claims, about your user.
The table below provides a list and descriptions of the claims your JWT should contain.
Claims
type
Required
Description
iat
string
x
Time the token was generated. The value must be the number of seconds since UNIX epoch. If this is more then 1 minute Pandium will reject the token.
jti
string
x
A unique id for the token that is used to protect against replay attacks by making sure the token is used only once.
sub
string
x
Email of the Tenant being signed in. Pandium uses this to uniquely identify the user. If the user does not exist in Pandium, it will be created.
ti
object
The Tenant Info Object. This object is used to pass information about the end-customer user that you need to tell Pandium about.
The table below provides a list and descriptions of the properties of the object mentioned above.
Property
Type
required
Description
udn
string
The user's display name
ufn
string
The user's full name
uem
string
The user's email
ili
array(string)
An array of installed external integrations, whose ids match the ids of the integration tiles in the Marketplace, that are currently active, and would like to be shown as such in the Marketplace.
aid
string
Auditable user id (if different from sub)
adn
string
Auditable users display name (if different from sub)
xti
object
A place to store extra props that may be need to power your company's marketplace experience

Sample:

{
"iat": 1621521641,
"jti": "1cfa7dbf-8110-4237-ad22-410608791b7d",
"ti": {
"udn": "Pandium Test",
"ufn": "Important Person",
"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

Linking Legacy Integrations in the In-App Marketplace

If you have apps built already that link to existing "legacy" integrations, you may still want to show these in the embedded marketplace and allow your customers to link out to any installed instances of the app.
To support this, you would create an External Integration - instructions can be found here - and then under the external integration ID field in the JWT represented by ili, you would put the value you'll be passing into the JWT. If the customer has this integration installed, it will show when they view the marketplace; if they do not, then it will not show and the app will appear as normal.
In the external integration URL field on an external integration, you would paste the URL where the integration lives in your system.

Setting Different Marketplace Views

Depending on your marketplace setup, you may want to implement different views based on how you group your users and apps.
Through customizing a JWT, you could easily accomplish this. By defining specific users and apps by email and id within the xti (extra tenant information) field in the JWT, and adhering to some rules we’d implement on Pandium’s end to support those rules, you can achieve several options.
Below are a few relevant use cases for changing the marketplace view:
Showing Multiple App Types to A single User
For when you would like to only show certain integration to a user, you would reference the app id in the JWT and specify in a list which you would want to show or hide, e.g. a field that was ‘hidden_integrations’ and those apps would not show to specific user(s).
Showing Different Marketplaces By a User Group
Similar; you could define a group e.g. ‘user_group’ or ‘user_tier’ in the xti field, and list out the apps you’d want to display for that particular group.
Allowing/Disallowing Certain Integration Installs Based on User Group
Again, similar as before in the same xti field, but if you wanted to, you could define a user group and also add a prosperity such as ‘allowed_installs’ that would limit how many apps a user could install. If you have any additional use cases, please reach out to your TAM so we can work with you to support this functionality.
Note: The Marketplace and related features are not included in the Pandium Lite offering.