# 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](https://developer.mozilla.org/en-US/docs/Web/HTTP/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](https://docs.pandium.com/reference/pandium-api).

Additionally, within the JWT, each connection will need to have fields defined in the '`xti`' field under the '`ti`’ property in your [JWT](https://docs.pandium.com/marketplaces/customizing-the-jwt), as seen below in the example with a connector named 'gwt' and integration named 'gwt2hs':

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

**For Auth Dialog to function, the JWT will require a token parameter on your side for&#x20;*****your organization's*****&#x20;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](https://tools.ietf.org/html/rfc4648#section-5) 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": "test@pandium.com",
   "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
```