Embedding the Integration Install Only

How does Integration Install Only work?

Pandium offers the option to embed a secure, fully managed integration setup UI into your marketplace or partner marketplaces. This first-time-user-experience (FTUX) flow presents itself via a page where users can log-in and authenticate to different systems, configure their integration settings, and sync schedules—all within a UI that you can customize.

This page is displayed in an iframe within your web app, sitting behind your company’s login.

This can be useful for creating a dedicated area within your site where you control which connectors or integrations users can access. It provides a simple way to integrate with Pandium's advanced integration management platform while retaining your custom marketplace styling. This is a good option for those who wish to utilize more of Pandium's native integration options, with minimal additional developer support, but maintain a fully native and custom Marketplace experience.

How to Embed the Integration Install Flow

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

Each integration that you are surfacing to your users will need to direct to a specific URL where your users can authenticate. The URLs will look like the below:

https://imp.pandium.com/<account>/tenants/create/<integration_id>?tenant=<jwt_token> if using a production Pandium account.

https://imp.sandbox.pandium.com/<account>/tenants/create/<integration_id>?tenant=<jwt_token> if using a sandbox Pandium account.

In these URLs, the organization name is your unique company name, which can be found in the URL while logged into the Integration Hub URL, e.g. https:/imp.sandbox.pandium.com/yourcompanyname?tenant=, and the specific Connector name being used, which can be found in integration the object via our API.

Additionally, within the JWT, each connection will need to have fields defined in the 'xti' field in your JWT. as seen below in the example with a connector named 'gwt' and integration named 'gwt2hs':

"xti": {
    connector_name: "gwt",
    integration_name: "gwt2hs",
}

For Auth Dialog to function, the JWT will require a token parameter on your side for your organization's connector, so that when users connect, they are able to authenticate into your system.

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": [
       "val1",
       "listVal"
       ]
     "connector_name": "gwt",
     "integration_name": "gwt2hs",
     "token": "your token"
   }
 },
 "sub": "test-pandium-com"
}

Signature

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

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.

A Complete Example

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
    .eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ
    .SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c