The App Directory is a public listing of all apps that your users can create integrations with. This app listing is hosted by Integry. Learn all the details about App Directory here. This article is about how the Single Sign-On (SSO) is implemented with app directory.
By default, the App Directory is public, so anyone can view the list of apps and their details without being logged into your app. However, once they click on the Install button to set up any integration, they need to be logged into your app.
The way this authentication process works is that when the user clicks on the setup link for an integration, they will be redirected to your app’s login page (e.g., MySaaS.com/login). Over here, the user will have to log in.
Once the user logs in, your app will redirect back to the App Directory with user information for their identification and authorization. This user information is encrypted to ensure maximum security.
The content of the user information and the encryption details are discussed below, with the overall flow of this authentication process.
Implementing SSO for App Directory in your application
1. User login
When a user clicks to set up an integration, they will be redirected to your login URL (as provided in the App Directory settings page). We will pass source=appdir as a URL parameter which you can use to perform the next step.
2. Implement Redirect
Once the user logs in, they should be redirected to the App Directory’s Authentication endpoint mysaas.integry.io/auth (or apps.mysaas.io/auth for a custom domain, the subdomain you set is up to you), carrying the user payload via JWT as a ?token URL parameter.
The payload contains the following information:
app_key: your app identifier
user_id: the user’s ID in your system
hash: a combination of user_id and app secret. See this link for documentation on how to generate this
api_key: API Key of the user we’ll make to make API calls on the user’s behalf
user_name (optional): Name of the user
user_profile_pic: a URL of the user’s profile image (square, 128x128 max)
The App Directory will use the above information to render the user experience. This information needs to be passed using JWT, details on that below:
JWT is a very simple way of taking Json and encrypting it. The resulting hashed token can then be safely passed around over a URL or in a POST body. Thus the name: JSON Web Token.
In order to generate a JWT, use the algo HS256 and type JWT along with the secret provided to you via the App Directory admin. Pass that to mysaas.integry.io/auth?token (or apps.mysaas.com/auth?token for a custom domain).
4. Back at the App Directory
Once the App Directory receives the token, it is decrypted and unpacked. A user session is created with a cookie with a 30-day expiry. You can invalidate the session by revoking the API Key, please keep in mind, this will also stop app integrations for the user as well. The user can also manually log out by clicking a link in the App Directory UI. Next time, the user will not need to re-login as long as the cookie hasn’t expired.
As the user will now be identified, they will be able to make integrations. They will also be able to see personalized data like a list of their integrations, or the status and stats of their integrations.