Single Sign-On (SSO) - Activepieces

Activepieces supports enterprise Single Sign-On (SSO) authentication, allowing users to authenticate using your organization’s identity provider.

Supported Providers

SAML 2.0

Industry-standard protocol for enterprise SSO with Okta, Azure AD, Google Workspace, and more.

OAuth 2.0

Modern authentication protocol for third-party identity providers.

SAML Configuration

Activepieces implements SAML 2.0 authentication using the Service Provider (SP) initiated flow.

Prerequisites

Identity Provider Access

Admin access to your IdP (Okta, Azure AD, Google Workspace, etc.)

Required Information

IdP Metadata XML or URL
IdP Certificate (for request signing)
Attribute mappings

Platform Configuration

Platform-level SSO configuration in Activepieces

Setting Up SAML

IdP Configuration
Activepieces Setup
Provider Examples

Configure Your Identity Provider

1. Create SAML Application

In your IdP, create a new SAML 2.0 application with these settings:Service Provider Details:

Entity ID: Activepieces
ACS URL: https://your-domain.com/api/v1/authn/saml/acs
Name ID Format: EmailAddress

2. Configure Attribute Mappings

These attributes are required and must be mapped exactly:

SAML Attribute	User Property	Required
`email`	User email address	✅
`firstName`	User first name	✅
`lastName`	User last name	✅

Example IdP Mappings:

<Attribute Name="email">
  <AttributeValue>user.email</AttributeValue>
</Attribute>
<Attribute Name="firstName">
  <AttributeValue>user.firstName</AttributeValue>
</Attribute>
<Attribute Name="lastName">
  <AttributeValue>user.lastName</AttributeValue>
</Attribute>

3. Download IdP Metadata

Export the IdP metadata XML or copy the metadata URL.

Configure Platform SSO

1. Enable SAML Authentication

In your platform settings:

{
  federatedAuthProviders: {
    saml: {
      idpMetadata: "<EntityDescriptor>...</EntityDescriptor>",
      idpCertificate: "-----BEGIN PRIVATE KEY-----\n..."
    }
  }
}

The idpCertificate is used to sign authentication requests sent to your IdP.

2. Generate Certificate

Generate a private key for signing:

# Generate private key
openssl genrsa -out saml-private.key 2048

# Extract private key content
cat saml-private.key

3. Test Connection

Access the SAML login endpoint:

https://your-domain.com/api/v1/authn/saml/login

Provider-Specific Setup

Okta

Application Settings:

Single sign-on URL: https://your-domain.com/api/v1/authn/saml/acs
Audience URI (SP Entity ID): Activepieces
Name ID format: EmailAddress

Attribute Statements:

Name	Value
email	user.email
firstName	user.firstName
lastName	user.lastName

Azure AD

Basic SAML Configuration:

Identifier (Entity ID): Activepieces
Reply URL (ACS URL): https://your-domain.com/api/v1/authn/saml/acs

Attributes & Claims:

Claim name	Source attribute
email	user.mail
firstName	user.givenname
lastName	user.surname

Google Workspace

Service Provider Details:

ACS URL: https://your-domain.com/api/v1/authn/saml/acs
Entity ID: Activepieces
Name ID: Basic Information > Primary Email

Attribute Mapping:

App attribute	Google Directory attribute
email	Primary Email
firstName	First Name
lastName	Last Name

SAML Authentication Flow

SAML Response Validation

Activepieces validates SAML responses:

Signature Verification

Verifies the SAML response is signed by the IdP

Attribute Extraction

Extracts email, firstName, lastName from assertion

User Provisioning

Creates or updates user account automatically

Session Creation

Issues JWT token for authenticated session

Security Configuration

SAML Security Settings

Activepieces enforces these security features:

{
  isAssertionEncrypted: true,
  wantMessageSigned: true,
  wantLogoutResponseSigned: true,
  wantLogoutRequestSigned: true,
  messageSigningOrder: 'encrypt-then-sign'
}

All SAML messages must be signed to prevent tampering. Ensure your IdP is configured to sign assertions.

Certificate Management

Private Key Security

Store private key securely (encrypted at rest)
Never expose in logs or client-side code
Rotate keys annually or after security incidents

Certificate Rotation

Generate new key pair
Update IdP with new certificate
Update Activepieces configuration
Test authentication
Revoke old certificate

Key Requirements

Minimum 2048-bit RSA key
PEM format
No password protection (stored encrypted)

User Provisioning

When users authenticate via SSO:

User Creation

New user account created with attributes from SAML:

{
  email: "[email protected]",
  firstName: "John",
  lastName: "Doe",
  status: UserStatus.ACTIVE,
  identityId: "identity_xyz"
}

Invitation Processing

If user has pending invitations, they’re automatically provisioned:

Added to invited projects
Assigned specified roles
Invitations marked as accepted

Audit Event

{
  action: ApplicationEventName.USER_SIGNED_UP,
  data: { source: 'sso' }
}

Subsequent Logins

User profile updated with latest attributes
Login event recorded
Session token issued

OAuth Providers

Activepieces also supports OAuth 2.0 for federated authentication:

Supported OAuth Providers

Google

Google Workspace accounts

GitHub

GitHub organization members

Microsoft

Azure AD / Microsoft 365

Custom

Any OAuth 2.0 provider

OAuth Configuration

{
  federatedAuthProviders: {
    oauth: {
      clientId: "your-client-id",
      clientSecret: "your-client-secret",
      authorizationUrl: "https://provider.com/oauth/authorize",
      tokenUrl: "https://provider.com/oauth/token",
      userInfoUrl: "https://provider.com/oauth/userinfo"
    }
  }
}

Troubleshooting

Invalid SAML Response Error

Cause: Missing required attributes (email, firstName, lastName)Solution:

Check IdP attribute mappings
Verify attribute names match exactly
Test with SAML tracer browser extension

Signature Verification Failed

Cause: IdP certificate mismatch or unsigned responsesSolution:

Ensure IdP is configured to sign assertions
Verify certificate in IdP metadata matches
Check certificate format (PEM)

Redirect Loop

Cause: ACS URL misconfigurationSolution:

Verify ACS URL in IdP matches exactly: /api/v1/authn/saml/acs
Check domain configuration
Ensure no trailing slashes

Users Not Provisioned

Cause: Platform ID not configured correctlySolution:

Verify platform ID in SAML configuration
Check custom domain settings
Review platform resolution logic

Testing SSO

Test Login Flow

# Access SAML login endpoint
curl -L https://your-domain.com/api/v1/authn/saml/login

Verify Attributes

Check that user profile has correct information after login

Test Invitations

Invite a new SSO user and verify they’re provisioned correctly

Review Audit Logs

Confirm authentication events are logged:

USER_SIGNED_UP
USER_SIGNED_IN

Production Checklist

Metadata Validation

✅ IdP metadata is valid XML ✅ All required endpoints present ✅ Certificate is valid and not expired

Attribute Mapping

✅ email, firstName, lastName mapped ✅ Attribute names match exactly ✅ Test with actual user accounts

Security

✅ Private key stored securely ✅ Message signing enabled ✅ Assertion encryption enabled

Testing

✅ Login flow works end-to-end ✅ User provisioning succeeds ✅ Audit events are logged

Users & Permissions

Configure user roles

Audit Logs

Track authentication events

Security Practices

General security guidelines

Platform Management

Security

​Supported Providers

SAML 2.0

OAuth 2.0

​SAML Configuration

​Prerequisites

​Setting Up SAML

​Configure Your Identity Provider

​1. Create SAML Application

​2. Configure Attribute Mappings

​3. Download IdP Metadata

​Configure Platform SSO

​1. Enable SAML Authentication

​2. Generate Certificate

​3. Test Connection

​Provider-Specific Setup

​SAML Authentication Flow

​SAML Response Validation

​Security Configuration

​SAML Security Settings

​Certificate Management

​User Provisioning

​First-Time Login

​Subsequent Logins

​OAuth Providers

​Supported OAuth Providers

Google

GitHub

Microsoft

Custom

​OAuth Configuration

​Troubleshooting

​Testing SSO

​Production Checklist

Metadata Validation

Attribute Mapping

Security

Testing

​Related Topics

Users & Permissions

Audit Logs

Security Practices

Build docs developers (and LLMs) love

Supported Providers

SAML Configuration

Prerequisites

Setting Up SAML

Configure Your Identity Provider

1. Create SAML Application

2. Configure Attribute Mappings

3. Download IdP Metadata

Configure Platform SSO

1. Enable SAML Authentication

2. Generate Certificate

3. Test Connection

Provider-Specific Setup

SAML Authentication Flow

SAML Response Validation

Security Configuration

SAML Security Settings

Certificate Management

User Provisioning

First-Time Login

Subsequent Logins

OAuth Providers

Supported OAuth Providers

OAuth Configuration

Troubleshooting

Testing SSO

Production Checklist

Related Topics