How to Setup SSO - Activepieces

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.

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.

    ![JumpCloud ACS URL](/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` |
    
    ![JumpCloud User Attributes](/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.
    
    ![JumpCloud Redirect Binding](/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**.
    
    ![JumpCloud Export Metadata](/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.
    
    ![JumpCloud Assign App](/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.