> ## Documentation Index
> Fetch the complete documentation index at: https://www.activepieces.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# How to Setup SSO

> Configure Single Sign-On (SSO) to enable secure, centralized authentication for your Activepieces platform

<Snippet file="enterprise-feature.mdx" />

## Overview

Single Sign-On (SSO) allows your team to authenticate using your organization's existing identity provider, eliminating the need for separate Activepieces credentials. This improves security, simplifies user management, and provides a seamless login experience.

## Prerequisites

Before configuring SSO, ensure you have:

* **Admin access** to your Activepieces platform
* **Admin access** to your identity provider (Google, GitHub, Okta, or JumpCloud)
* The **redirect URL** from your Activepieces SSO configuration screen

## Accessing SSO Configuration

Navigate to **Platform Settings** → **SSO** in your Activepieces admin dashboard to access the SSO configuration screen.

<img src="https://mintcdn.com/activepieces/uHZ35vXyxX7goNO-/resources/screenshots/sso.png?fit=max&auto=format&n=uHZ35vXyxX7goNO-&q=85&s=88efce2224ae9782860510b0d36a6731" alt="SSO Configuration" width="1420" height="900" data-path="resources/screenshots/sso.png" />

## Enforcing SSO

You can enforce SSO by specifying your organization's email domain. When SSO enforcement is enabled:

* Users with matching email domains must authenticate through the SSO provider
* Email/password login can be disabled for enhanced security
* All authentication is routed through your designated identity provider

<Tip>
  We recommend testing SSO with a small group of users before enforcing it organization-wide.
</Tip>

## SSO Domain

The **SSO Domain** lets you map a public domain (e.g. `acme.com`) to your platform's SAML provider so users can discover the right IdP from the shared sign-in page.

You can set it in the SAML configuration dialog (**Platform Settings → SSO → SAML 2.0 → Enable**), in the **SSO Domain** field. Leave it empty to disable domain-based discovery.

**How it works on Cloud**

On the cloud sign-in page, clicking **Sign in with SAML** opens a dialog asking the user for their organization's domain. When they enter `acme.com`, the platform whose SSO Domain matches is looked up and the user is redirected to that platform's identity provider.

**Constraints**

* Must be a valid public hostname containing a dot (e.g. `acme.com`, not `acme`).
* Each domain can be claimed by only one platform on Cloud.

<Note>
  On self-hosted Enterprise instances the SAML button on the sign-in page redirects directly to the configured identity provider, so the **SSO Domain** field is effectively ignored at login. You can still leave it empty.
</Note>

## Supported SSO Providers

Activepieces supports multiple SSO providers to integrate with your existing identity management system.

### Google

<Steps>
  <Step title="Access Google Cloud Console">
    Go to the [Google Cloud Console](https://console.cloud.google.com/) and select your project (or create a new one).
  </Step>

  <Step title="Create OAuth2 Credentials">
    Navigate to **APIs & Services** → **Credentials** → **Create Credentials** → **OAuth client ID**.

    Select **Web application** as the application type.
  </Step>

  <Step title="Configure Redirect URI">
    Copy the **Redirect URL** from the Activepieces SSO configuration screen and add it to the **Authorized redirect URIs** in Google Cloud Console.
  </Step>

  <Step title="Copy Credentials to Activepieces">
    Copy the **Client ID** and **Client Secret** from Google and paste them into the corresponding fields in Activepieces.
  </Step>

  <Step title="Save Configuration">
    Click **Finish** to complete the setup.
  </Step>
</Steps>

### GitHub

<Steps>
  <Step title="Access GitHub Developer Settings">
    Go to [GitHub Developer Settings](https://github.com/settings/developers) → **OAuth Apps** → **New OAuth App**.
  </Step>

  <Step title="Register New Application">
    Fill in the application details:

    * **Application name**: Choose a recognizable name (e.g., "Activepieces SSO")
    * **Homepage URL**: Enter your Activepieces instance URL
  </Step>

  <Step title="Configure Authorization Callback">
    Copy the **Redirect URL** from the Activepieces SSO configuration screen and paste it into the **Authorization callback URL** field.
  </Step>

  <Step title="Complete Registration">
    Click **Register application** to create the OAuth App.
  </Step>

  <Step title="Generate Client Secret">
    After registration, click **Generate a new client secret** and copy it immediately (it won't be shown again).
  </Step>

  <Step title="Copy Credentials to Activepieces">
    Copy the **Client ID** and **Client Secret** and paste them into the corresponding fields in Activepieces.
  </Step>

  <Step title="Save Configuration">
    Click **Finish** to complete the setup.
  </Step>
</Steps>

### SAML with Okta

<Steps>
  <Step title="Create New Application in Okta">
    Go to the [Okta Admin Portal](https://login.okta.com/) → **Applications** → **Create App Integration**.
  </Step>

  <Step title="Select SAML 2.0">
    Choose **SAML 2.0** as the sign-on method and click **Next**.
  </Step>

  <Step title="Configure General Settings">
    Enter an **App name** (e.g., "Activepieces") and optionally upload a logo. Click **Next**.
  </Step>

  <Step title="Configure SAML Settings">
    * **Single sign-on URL**: Copy the SSO URL from the Activepieces configuration screen
    * **Audience URI (SP Entity ID)**: Enter `Activepieces`
    * **Name ID format**: Select `EmailAddress`
  </Step>

  <Step title="Add Attribute Statements">
    Add the following attribute mappings:

    | Name        | Value            |
    | ----------- | ---------------- |
    | `firstName` | `user.firstName` |
    | `lastName`  | `user.lastName`  |
    | `email`     | `user.email`     |
  </Step>

  <Step title="Complete Setup in Okta">
    Click **Next**, select the appropriate feedback option, and click **Finish**.
  </Step>

  <Step title="Export IdP Metadata">
    Go to the **Sign On** tab → **View SAML setup instructions** or **View IdP metadata**. Copy the Identity Provider metadata XML.
  </Step>

  <Step title="Configure Activepieces">
    * Paste the **IdP Metadata** XML into the corresponding field
    * Copy the **X.509 Certificate** from Okta and paste it into the **Signing Key** field
    * (Optional, Cloud) Set the **SSO Domain** to your organization's public domain (e.g. `acme.com`) so users can sign in by entering it on the cloud sign-in page. See [SSO Domain](#sso-domain) above.
  </Step>

  <Step title="Save Configuration">
    Click **Save** to complete the setup.
  </Step>
</Steps>

### SAML with Microsoft Entra ID (Azure AD)

<Steps>
  <Step title="Create an Enterprise Application">
    Go to the [Azure Portal](https://portal.azure.com/) → **Microsoft Entra ID** → **Enterprise applications** → **New application** → **Create your own application**.

    Name it (e.g., "Activepieces") and select **Integrate any other application you don't find in the gallery (Non-gallery)**.
  </Step>

  <Step title="Configure SAML Single Sign-On">
    Open the application → **Single sign-on** → select **SAML**.
  </Step>

  <Step title="Set Identifier and Reply URL">
    Edit **Basic SAML Configuration**:

    * **Identifier (Entity ID)**: `Activepieces`
    * **Reply URL (Assertion Consumer Service URL)**: paste the SSO URL from the Activepieces configuration screen
  </Step>

  <Step title="Configure User Attributes & Claims">
    Edit **Attributes & Claims** and add these additional claims (leave **Namespace** empty):

    | Claim name  | Source attribute |
    | ----------- | ---------------- |
    | `firstName` | `user.givenname` |
    | `lastName`  | `user.surname`   |
    | `email`     | `user.mail`      |
  </Step>

  <Step title="Copy the Federation Metadata">
    In the **SAML Certificates** section, copy the **App Federation Metadata Url**.

    You can paste this URL directly into the **IdP Metadata** field in Activepieces — Activepieces will fetch the metadata XML automatically. Alternatively, open the URL in a browser, save the XML, and paste its contents.
  </Step>

  <Step title="Copy the Signing Certificate">
    Download the **Certificate (Base64)** from the **SAML Certificates** section. Open the file and copy its contents (including the `-----BEGIN CERTIFICATE-----` / `-----END CERTIFICATE-----` markers) into the **Signing Key** field in Activepieces.
  </Step>

  <Step title="Assign Users">
    Go to **Users and groups** in the application and assign the users or groups that should be allowed to sign in.
  </Step>

  <Step title="Save Configuration">
    Click **Save** in Activepieces to complete the setup.
  </Step>
</Steps>

### SAML with JumpCloud

<Steps>
  <Step title="Create New Application in JumpCloud">
    Go to the [JumpCloud Admin Portal](https://console.jumpcloud.com/) → **SSO Applications** → **Add New Application** → **Custom SAML App**.
  </Step>

  <Step title="Configure ACS URL">
    Copy the **ACS URL** from the Activepieces configuration screen and paste it into the **ACS URLs** field in JumpCloud.

    <img src="https://mintcdn.com/activepieces/uHZ35vXyxX7goNO-/resources/screenshots/jumpcloud/acl-url.png?fit=max&auto=format&n=uHZ35vXyxX7goNO-&q=85&s=850741fb9a122b3aa3be92a9c0f16475" alt="JumpCloud ACS URL" width="608" height="263" data-path="resources/screenshots/jumpcloud/acl-url.png" />
  </Step>

  <Step title="Configure SP Entity ID">
    Set the **SP Entity ID** (Audience URI) to `Activepieces`.
  </Step>

  <Step title="Add User Attributes">
    Configure the following attribute mappings:

    | Service Provider Attribute | JumpCloud Attribute |
    | -------------------------- | ------------------- |
    | `firstName`                | `firstname`         |
    | `lastName`                 | `lastname`          |
    | `email`                    | `email`             |

    <img src="https://mintcdn.com/activepieces/uHZ35vXyxX7goNO-/resources/screenshots/jumpcloud/user-attribute.png?fit=max&auto=format&n=uHZ35vXyxX7goNO-&q=85&s=7ca21b93a70e8b51d392ee06cc6c4d10" alt="JumpCloud User Attributes" width="599" height="368" data-path="resources/screenshots/jumpcloud/user-attribute.png" />
  </Step>

  <Step title="Enable HTTP-Redirect Binding">
    JumpCloud does not include the `HTTP-Redirect` binding by default. You **must** enable this option.

    <img src="https://mintcdn.com/activepieces/uHZ35vXyxX7goNO-/resources/screenshots/jumpcloud/declare-login.png?fit=max&auto=format&n=uHZ35vXyxX7goNO-&q=85&s=8f2daa949a616e4dc98840b7623f00cb" alt="JumpCloud Redirect Binding" width="597" height="243" data-path="resources/screenshots/jumpcloud/declare-login.png" />

    <Warning>
      Without HTTP-Redirect binding, the SSO integration will not work correctly.
    </Warning>
  </Step>

  <Step title="Export Metadata">
    Click **Save**, then refresh the page and click **Export Metadata**.

    <img src="https://mintcdn.com/activepieces/uHZ35vXyxX7goNO-/resources/screenshots/jumpcloud/export-metadata.png?fit=max&auto=format&n=uHZ35vXyxX7goNO-&q=85&s=9945a82f3b87881deea9dce937968f01" alt="JumpCloud Export Metadata" width="618" height="250" data-path="resources/screenshots/jumpcloud/export-metadata.png" />

    <Tip>
      Verify that the exported XML contains `Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"` to ensure the binding was properly enabled.
    </Tip>
  </Step>

  <Step title="Configure IdP Metadata in Activepieces">
    Paste the exported metadata XML into the **IdP Metadata** field in Activepieces.
  </Step>

  <Step title="Configure Signing Certificate">
    Locate the `<ds:X509Certificate>` element in the IdP metadata and extract its value. Format it as a PEM certificate:

    ```
    -----BEGIN CERTIFICATE-----
    [PASTE THE CERTIFICATE VALUE HERE]
    -----END CERTIFICATE-----
    ```

    Paste this into the **Signing Key** field.
  </Step>

  <Step title="Assign Users to Application">
    In JumpCloud, assign the application to the appropriate users or user groups.

    <img src="https://mintcdn.com/activepieces/uHZ35vXyxX7goNO-/resources/screenshots/jumpcloud/user-groups.png?fit=max&auto=format&n=uHZ35vXyxX7goNO-&q=85&s=43f7dcb66b7aaeec59a070053fdaf8e7" alt="JumpCloud Assign App" width="939" height="526" data-path="resources/screenshots/jumpcloud/user-groups.png" />
  </Step>

  <Step title="Save Configuration">
    Click **Finish** to complete the setup.
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Users cannot log in after SSO configuration">
    * Verify the redirect URL is correctly configured in your identity provider
    * Ensure users are assigned to the application in your identity provider
    * Check that email domains match the SSO enforcement settings
  </Accordion>

  <Accordion title="SAML authentication fails">
    * Confirm the IdP metadata is complete and correctly formatted
    * If you pasted a metadata URL, make sure it is publicly reachable (Activepieces fetches it server-side)
    * Verify the signing certificate is properly formatted with BEGIN/END markers
    * Ensure all required attributes (firstName, lastName, email) are mapped
  </Accordion>

  <Accordion title="HTTP-Redirect binding error (JumpCloud)">
    * Enable the HTTP-Redirect binding option in JumpCloud
    * Re-export the metadata after enabling the binding
    * Verify the binding appears in the exported XML
  </Accordion>
</AccordionGroup>

## Need Help?

If you encounter issues during SSO setup, please contact our enterprise support or [sales team](https://www.activepieces.com/sales).