Single Sign-On (SSO) with Integration Marketplace – Integry

Integration Marketplace

The Integration Marketplace is a public listing of all apps that your end-users can create integrations with. This app listing is hosted by Integry. Learn all the details about Integration Marketplace here. This article is about how the Single Sign-On (SSO) is implemented with Integration Marketplace.

By default, the Integration Marketplace is public, so anyone can view the list of apps and Guided Flows without being logged into your app. However, to start the integration setup process, they need to be logged into your app first. Before setting up an integration, your end-users can learn about the details of the integration on the Flow Detail Page.

In the above image, you can see Tatango's Integration Marketplace where the end-user can click on Setup to go to the Flow Detail page of any app or Guided Flows.

On the Flow Detail Page, they can learn about the details of the integration and click on Use Flow to begin the integration setup process. In this example, the end-user needs to be logged into Tatango to proceed further.

Single sign-on(SSO)

Single sign-on is an authentication method that enables you to securely authenticate with multiple apps by using only one set of credentials. You can implement SSO to your Marketplace to make the end-user's experience seamless when using your apps and services.

Authentication Process

The authentication process works the following way:

Case 1:

If your end-user visits your Marketplace and is not signed into your app, the authentication process works the following way:

The end-user visits your Marketplace and starts the setup process for a Flow.
If they are not signed into your app, they are redirected to your app’s login page (e.g., MySaaS.com/login) where they have to login to continue.
After a successful sign-in, your app redirects the end-user to the Integration Marketplace with their information for identification and authorization at Integry's authentication endpoint. As soon as the end-user is verified, they're redirected to the Flow setup page where they can continue the integration setup process.

Case 2:

If your end-user visits your Marketplace and is already signed into your app, the authentication process works the following way:

The end-user visits your Marketplace but hasn't signed in to your Marketplace.
They click on sign-in or Use Flow and they're redirected to your app's login page.
Since they're already signed into your app, so you have to verify the end-user information and redirect them back to the Marketplace with SSO response.

The content of the end-user information is discussed below, with the overall flow of this authentication process.

Implementing SSO for Integration Marketplace in Your Application

End-user login

When an end-user begins to set up an integration on your Marketplace, they will be redirected to your login URL (as provided in the Integration Marketplace Settings page below).

You can append a query parameter like source=appdir to your Login URL. This will enable you to know where the login request is originating from (in this case, the source is your Marketplace).

Implement Redirect

As the end-user enters their credentials on your app's login page, verify them before redirecting them to your Marketplace.

When redirecting the end-user back to the Marketplace, you need to attach a token query parameter in the request. Thetoken query parameter must be a JSON Web Token (JWT). Following are the contents of the JWT:

Header: The header contains the information about the type of the token, which is JWT, and the algorithm that is used to encode the JSON object. In this case, we suggest you use HS256 Hash.
Payload: This is the encoded version of the JSON object.
Signature: The client server (your application) needs to sign the JWT using the App Secret - to verify the source of the JWT. The signature of the JWT should be similar to the App Secret of your workspace app (where your Marketplace deployment resides) in Integry.

Note: Contact Integry to get the App Secret and App Key of your Marketplace deployment. Once you have the necessary information, generate a JWT.

The payload of the JWT should contain the following information:

app_key: This is our app's identifier
user_id: This is the end-user’s ID in your system
hash: This is a combination of user_id and APP_SECRET. See this link for documentation on how to generate this
api_key: This is the API Key of your app which Integry uses to perform certain operations on your app on behalf of the end-user
user_name (optional): Name of the end-user
user_profile_pic: A URL of the end-user’s profile image (square, 128x128 max)
iat: The timestamp when the JWT was issued
exp: The expiry timestamp of the JWT

The Integration Marketplace will use the above information to render the end-user experience. Once your application (i.e., the client server) generates a JWT using the above mentioned payload and signs it using the App Key, you need to send this token to Integry. Pass the JWT to the Marketplace's authentication endpoint, mysaas.integry.io/auth?token (or apps.mysaas.com/auth?token for a custom domain).

At the authentication end-point, Integry will assign a key to the JWT and if the key matches with the JWT's signature (assigned by your application), the token will be verified. As a result, the end-user is allowed access to the Marketplace and its Flows.

Note: You can pass the JSON encoded string (JWT) in the URL or POST body to Integry's authentication endpoint, depending upon your configuration.

Back at the Integration Marketplace

After verifying the signature of the JWT, an authentication session is created for the end-user at the authentication end-point. The authentication session is saved at Integry's API for three days and is used to verify the end-users whenever they revisit the Marketplace.

You can invalidate the session by revoking the API Key, however, keep in mind that this will stop the app integrations for your end-users as well.

The end-user can also manually log out by clicking Sign out in the Integration Marketplace UI, shown above.

Next time, the end-user will not need to re-login as long as the cookie hasn’t expired. As the end-user will now be identified, they will be able to setup integrations at your Marketplace.

They will also be able to see personalized data like a list of their integrations, or the status and stats of their integrations in the Integration View, shown above.