Single Sign-On (SSO)

Configure SAML and OAuth authentication for your platform

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

1. Identity Provider Access

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

2. Required Information

   • IdP Metadata XML or URL
   • IdP Certificate (for request signing)
   • Attribute mappings
3. Platform Configuration

   Platform-level SSO configuration in Activepieces

Setting Up SAML

IdP Configuration

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.

Activepieces Setup

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 Examples

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:

1. Signature Verification

   Verifies the SAML response is signed by the IdP

2. Attribute Extraction

   Extracts email, firstName, lastName from assertion

3. User Provisioning

   Creates or updates user account automatically

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

1. Generate new key pair
2. Update IdP with new certificate
3. Update Activepieces configuration
4. Test authentication
5. Revoke old certificate

Key Requirements

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

User Provisioning

When users authenticate via SSO:

First-Time Login

1. User Creation

   New user account created with attributes from SAML:

   {
     email: "[e-mail]",
     firstName: "John",
     lastName: "Doe",
     status: UserStatus.ACTIVE,
     identityId: "identity_xyz"
   }
   
2. Invitation Processing

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

   • Added to invited projects
   • Assigned specified roles
   • Invitations marked as accepted
3. Audit Event

   Login event recorded:

   {
     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:

1. Check IdP attribute mappings
2. Verify attribute names match exactly
3. Test with SAML tracer browser extension

Signature Verification Failed

Cause: IdP certificate mismatch or unsigned responses

Solution:

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

Redirect Loop

Cause: ACS URL misconfiguration

Solution:

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

Users Not Provisioned

Cause: Platform ID not configured correctly

Solution:

1. Verify platform ID in SAML configuration
2. Check custom domain settings
3. Review platform resolution logic

Testing SSO

1. Test Login Flow

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

   Check that user profile has correct information after login

3. Test Invitations

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

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

Related Topics

Users & Permissions

Configure user roles

Audit Logs

Track authentication events

Security Practices

General security guidelines