Admin Portal

Empower your customers to configure and manage Single Sign-On settings independently

The Admin Portal simplifies the process of connecting your application to the identity or directory providers used by enterprise organizations.

By offering a self-service portal for your customers, you can minimize the need for extensive back-and-forth communication. Scalekit hosts and manages the Admin Portal entirely, providing two flexible integration options — No-Code and Embedded portals

No-Code Admin Portal

A portal will show up for your customers to configure SSO settings by accessing a shareable link. This portal contains the configuration settings that lets your customers setup a connection to their identity provider.

To create and share a link for the Admin Portal, follow these steps:

Log in to your Scalekit Dashboard.
Navigate to the "Organizations" tab.
Select the organization you want to provide access to.
Click "Generate Link" to create a new, shareable Admin Portal link.

Example

https://your-app.scalekit.dev/magicLink/2cbe56de-eec4-41d2-abed-90a5b82286c4_p

The link expires in 7 days but can be revoked at any time from the dashboard for security purposes.You can share the link through communication channels such as email, Slack, or other preferred methods.

note

Be cautious when sharing the link, as anyone with access to it can view and update the organization's connection settings

Embedded Admin Portal

Users can do the connection setup right from your application by rendering Scalekit-hosted admin portal as a inline frame (iframe). This approach allows easy discovery & convenient access to the portal without the need for external links or separate portals.

Generate the embeddable portal link when page loads or refreshes and inject the src of the <iframe>, at your app's runtime. This ensure secure programmatic access.

Setup SDK

Node.js
Python
Go
Java

npm install @scalekit-sdk/node

pip install scalekit-sdk-python

go get -u github.com/scalekit-inc/scalekit-sdk-go

/* Gradle users - add the following to your dependencies in build file */
implementation "com.scalekit:scalekit-sdk-java:1.1.2"

<!-- Maven users - add the following to your `pom.xml` -->
<dependency>
    <groupId>com.scalekit</groupId>
    <artifactId>scalekit-sdk-java</artifactId>
    <version>1.1.2</version>
</dependency>

Use the Generate Portal Link API to create a unique, embeddable Admin Portal link specific to an organization.

Generate Portal Link

Node.js

import { Scalekit } from '@scalekit-sdk/node';

const scalekit = new Scalekit(
  process.env.ENVIRONMENT_URL,
  process.env.CLIENT_ID,
  process.env.CLIENT_SECRET,
);

async function generatePortalLink(orgID) {
  const link = await scalekit.organization.generatePortalLink(orgID);
  console.log(JSON.stringify(link, null, 2));
}

The API will return a JSON object containing the location property, which is the URL to the Admin Portal.

Generate Portal Link (Response Object)

{
  "id": "8930509d-68cf-4e2c-8c6d-94d2b5e2db43",
  "location": "https://random-subdomain.scalekit.dev/magicLink/8930509d-68cf-4e2c-8c6d-94d2b5e2db43",
  "expireTime": "2024-10-03T13:35:50.563013Z"
}

Access the location property and set it as the src attribute of an iframe in your web pages at runtime. Ensure your domain is listed as one of the Redirect URIs in the Scalekit Dashboard > API Config.

Render admin portal in iframe (example)

<body>
  <h1>Admin Portal (Embed)</h1>
  <iframe
    src="https://random-subdomain.scalekit.dev/magicLink/8930509d-68cf-4e2c-8c6d-94d2b5e2db43"
    width="100%"
    height="600px"
    frameborder="0"
    allow="clipboard-write"
  >
  </iframe>
</body>

For example, if your application has a "Settings" page for your users, this page can allow them to configure connection with their IdP right within from your app.

note

The programmatically generated link is designed for one-time use and expires after 1 minute. Once activated in iframe, the IT admin can configure SSO for an extended period. The session remains active until the setup is complete.
The embedded portal session times out after 6 hours, requiring administrators to complete the configuration within this period.

UI Events

Listen to the browser events emitted from the embedded admin portal to perform actions on your app. For example, showing a notification when the SSO connection is enabled.

Event Type	Description
`ORGANIZATION_SSO_ENABLED`	Triggered when the SSO connection is enabled
`ORGANIZATION_SSO_DISABLED`	Triggered when the SSO connection is disabled
`PORTAL_SESSION_EXPIRY`	Triggered when the portal session expires
`PORTAL_SESSION_TIMEOUT`	Triggered when the portal session times out
`ORGANIZATION_DIRECTORY_ENABLED`	Triggered when the SCIM provisioning is enabled
`ORGANIZATION_DIRECTORY_DISABLED`	Triggered when the SCIM provisioning is disabled

To listen to these events:

Add a listener to the parent window.
Check the event origin and type to determine the action to take.
Handle the event data as needed.

Listening to events from the embedded admin portal

window.onmessage = event => {
  if (
    event.origin === '<SCALEKIT_ENVIRONMENT_URL>' &&
    event.data &&
    event.data.event_type === '<EVENT_TYPE>'
  ) {
    console.log(event.data); // Handle the event data
  }
};

Below is an example of the data structure you might receive in your browser console when a event is triggered:

ORGANIZATION_SSO_ENABLED

ORGANIZATION_SSO_DISABLED

PORTAL_SESSION_EXPIRY

PORTAL_SESSION_WARNING

ORGANIZATION_DIRECTORY_ENABLED

ORGANIZATION_DIRECTORY_DISABLED

note

The domain of your parent window must be listed in the Scalekit Dashboard > API Config > Redirect URIs for security purpose
Always validate the event.origin to ensure events are coming from a trusted source.

The Admin Portal can be customized to match your brand's logo and colors. Refer to the Customize Admin Portal Guide for more information.

No-Code Admin Portal​

Embedded Admin Portal​

UI Events​

No-Code Admin Portal

Embedded Admin Portal

UI Events