AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents
TypeScript ai-agentai-agent-toolsai-agentsai-agents-frameworkmcpmcp-servermcp-toolsmcpsn8n-alternativeno-code-automationworkflowworkflow-automationworkflows
---
title: "How to Setup SSO"
description: "Configure Single Sign-On (SSO) to enable secure, centralized authentication for your Activepieces platform"
icon: "key"
---
<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 (Okta, Microsoft Entra ID, JumpCloud, or any SAML 2.0 provider)
- Access to your company domain's **DNS settings**, to verify the domain
## The Authentication page
Go to **Platform admin** → **Security** → **Authentication**. The page has three sections:
- **Domain**: the company domain your people sign in with.
- **Sign-in methods**: single sign-on (SAML 2.0), Continue with Google, and email and password.
- **Allowed domains**: the email domains allowed to sign in with email and password.

## Verify your domain
Single sign-on needs a verified company domain (for example `acme.com`).
<Steps>
<Step title="Enter the domain">
Under **Domain**, click **Verify domain** and enter your company domain. It must be a public hostname containing a dot, and on Cloud each domain can be claimed by only one platform.
</Step>
<Step title="Add the TXT record">
Copy the TXT record's **Name** and **Value** and add them at your DNS provider.
</Step>
<Step title="Verify DNS">
Click **Verify DNS**. DNS changes can take a few minutes to show up, so try again if the record isn't found yet. Verify within 7 days, or the domain is dropped and you start again with a new record.
</Step>
</Steps>
While a domain is being verified it shows as **Verifying**, with **Waiting for DNS · day N of 7** under it. Its menu lets you **Continue verifying** or **Cancel verification**. Once verified, use **View DNS record** to see the record again.
You can also verify the domain from the first step of the SAML setup, described below.
<Warning>
**Remove domain** also deletes your SAML connection, so single sign-on stops working. To confirm, type the domain name. You can't remove it while single sign-on is the only way to sign in: turn on email and password or Google sign-in first.
</Warning>
## Set up SAML
Under **Sign-in methods**, click **Set up** next to **Single sign-on** (or **Manage** once it's connected). The setup has two steps:
1. **SSO Domain**: verify your domain, or confirm the one you already verified.
2. **SAML 2.0**:
- **Copy these into your identity provider**: the **Single sign-on URL** and the **Audience URI (SP Entity ID)**, which is `Activepieces`.
- **Paste these from your identity provider**: the **IDP Metadata** (the metadata XML, or a metadata URL) and the **IDP Certificate**.
The **SAML 2.0** step opens once the domain is verified. Once saved, the fields say **Saved**; paste new values only to replace them.
To turn single sign-on off, open **Manage**, click **Disable** under the SAML step and type `disable` to confirm. This deletes the SAML connection but keeps your verified domain, so you can connect again later. As with removing the domain, it's blocked while single sign-on is the only way to sign in.
**Signing in with SAML on Cloud**
On the cloud sign-in page, **Sign in with SAML** asks for the organization's domain. Entering `acme.com` sends the person to the identity provider of the platform that verified `acme.com`. The signed-in email must be at that domain.
<Note>
On self-hosted Enterprise instances the SAML button on the sign-in page redirects directly to the configured identity provider.
</Note>
## Google and email and password
Turn **Continue with Google** and **Email and password** on or off under **Sign-in methods**. Each change asks you to confirm. You can't turn off the last sign-in method that works: turn on another one first. On a self-hosted server, Google only counts once it's set up.
On self-hosted instances, the Google button only appears once `AP_GOOGLE_CLIENT_ID` and `AP_GOOGLE_CLIENT_SECRET` are set. See [Google sign-in on self-hosted](#google).
## Allowed domains
**Allowed domains** limits sign-in to email addresses at the domains you list. Add your company domain too, or people at your company are refused.
- **Cloud**: the list applies to email and password sign-in.
- **Self-hosted Enterprise**: the list also applies to anyone creating an account, with any sign-in method.
Removing the last domain turns the restriction off.
<Tip>
We recommend testing SSO with a small group of users before turning other sign-in methods off.
</Tip>
## Supported SSO Providers
Activepieces supports multiple SSO providers to integrate with your existing identity management system.
### Google
On Cloud, Continue with Google works without setup. On self-hosted instances, create a Google OAuth client and pass it to Activepieces with environment variables.
<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**, and select **Web application**.
</Step>
<Step title="Configure Redirect URI">
Add `<your Activepieces URL>/redirect` to the **Authorized redirect URIs**. If you set `AP_INTERNAL_URL`, use that URL instead.
</Step>
<Step title="Set the environment variables">
Set `AP_GOOGLE_CLIENT_ID` and `AP_GOOGLE_CLIENT_SECRET` to the client's ID and secret, then restart Activepieces. See [environment variables](/install/reference/environment-variables).
</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 **Single sign-on URL** from step 2 of the SAML setup
- **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 **IDP Certificate** field
</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 **Single sign-on URL** from step 2 of the SAML setup
</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 **IDP Certificate** 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 **Single sign-on URL** from step 2 of the SAML setup and paste it into the **ACS URLs** field in JumpCloud.

</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` |

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

<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**.

<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:
```text
-----BEGIN CERTIFICATE-----
[PASTE THE CERTIFICATE VALUE HERE]
-----END CERTIFICATE-----
```
Paste this into the **IDP Certificate** field.
</Step>
<Step title="Assign Users to Application">
In JumpCloud, assign the application to the appropriate users or user groups.

</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 the user's email is at your verified domain
- If you use allowed domains, check that the user's domain is on the list
</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).