SAML Configuration

​

Overview

• Standards-based SSO using SAML 2.0 protocol
• Integration with enterprise identity providers
• Secure assertion-based authentication
• Automatic user provisioning via SAML attributes

​

Prerequisites

• Cal.com Enterprise license with SSO enabled
• Identity Provider supporting SAML 2.0
• Separate PostgreSQL database for SAML data
• Admin access to both Cal.com and your IdP

​

Setup Guide

​

1. Configure Environment

# Required: Separate database for SAML data
SAML_DATABASE_URL=postgresql://postgres:@localhost:5450/cal-saml

# Required: Email addresses of SAML administrators
SAML_ADMINS=[email protected],[email protected]

# Required: Encryption key for sensitive data
# Generate with: openssl rand -base64 24
CALENDSO_ENCRYPTION_KEY=your_32_byte_encryption_key

# Optional: Client secret for OAuth 2.0 flows
SAML_CLIENT_SECRET_VERIFIER=your_random_secret

# Optional: Enable for hosted Cal.com features
NEXT_PUBLIC_HOSTED_CAL_FEATURES=1

​

2. Create SAML Database

# Create database
creatdb cal-saml

# Run migrations
DATABASE_URL="postgresql://postgres:@localhost:5450/cal-saml" \
  yarn workspace @calcom/prisma migrate deploy

​

3. Retrieve SAML Metadata

• Entity ID / Audience: https://saml.cal.com
• Assertion Consumer Service (ACS) URL: https://your-domain.com/api/auth/saml/callback
• Single Logout URL: https://your-domain.com/api/auth/saml/logout
• Name ID Format: urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress

​

4. Configure Identity Provider

​

Okta Configuration

1. Navigate to Applications → Create App Integration
2. Select SAML 2.0
3. Configure:
   • Single sign-on URL: https://your-domain.com/api/auth/saml/callback
   • Audience URI: https://saml.cal.com
   • Name ID format: EmailAddress
   • Application username: Email
4. Attribute Statements (optional):
   firstName  → user.firstName
   lastName   → user.lastName
   email      → user.email
   
5. Download the IdP metadata XML

​

Azure AD Configuration

1. Navigate to Enterprise Applications → New Application
2. Create a non-gallery application
3. Configure Single sign-on → SAML
4. Set:
   • Identifier (Entity ID): https://saml.cal.com
   • Reply URL (ACS): https://your-domain.com/api/auth/saml/callback
   • Sign on URL: https://your-domain.com
5. User Attributes & Claims:
   email       → user.mail
   firstName   → user.givenname
   lastName    → user.surname
   
6. Download Federation Metadata XML

​

Google Workspace Configuration

1. Navigate to Apps → Web and mobile apps → Add custom SAML app
2. Download IdP metadata
3. Configure Service Provider Details:
   • ACS URL: https://your-domain.com/api/auth/saml/callback
   • Entity ID: https://saml.cal.com
   • Name ID format: EMAIL
   • Name ID: Basic Information > Primary email
4. Attribute mapping:
   firstName   → Basic Information > First name
   lastName    → Basic Information > Last name
   email       → Basic Information > Primary email
   

​

5. Upload IdP Metadata to Cal.com

1. Log in to Cal.com as a SAML admin
2. Navigate to Settings → Security → Single Sign-On
3. Select your organization/team
4. Upload or paste your IdP metadata XML
5. Or manually configure:
   • IdP Entity ID: From IdP metadata
   • SSO URL: From IdP metadata
   • Certificate: X.509 certificate from IdP

​

SAML Constants

export const samlTenantID = "Cal.com";
export const samlProductID = "Cal.com";
export const samlAudience = "https://saml.cal.com";
export const samlPath = "/api/auth/saml/callback";
export const clientSecretVerifier = process.env.SAML_CLIENT_SECRET_VERIFIER;

​

Tenant Structure

export const tenantPrefix = "team-";

// Example: Team with ID 123
const tenant = `team-123`;

• Multiple teams to have different SAML configurations
• Isolated authentication per team
• Organization-level SAML that applies to all sub-teams

​

User Provisioning

​

First-Time Login

// 1. Extract email from SAML assertion
const email = samlResponse.email;

// 2. Check for organization matching email domain
const domain = email.split("@")[1];
const organization = await organizationRepository
  .getVerifiedOrganizationByAutoAcceptEmailDomain(domain);

// 3. Create user and connect to organization
if (organization && ORGANIZATIONS_AUTOLINK) {
  await createUsersAndConnectToOrg({
    emailsToCreate: [email],
    identityProvider: IdentityProvider.SAML,
    identityProviderId: email,
    org: organization,
  });
}

​

Required Conditions

1. ORGANIZATIONS_AUTOLINK=1 must be set
2. Organization must have verified the email domain
3. User email domain must match organization domain
4. User must not already belong to another organization

​

Permission Management

​

Self-Hosted Deployments

const isSAMLAdmin = (email: string) => {
  const samlAdmins = (process.env.SAML_ADMINS || "").split(",");
  for (const admin of samlAdmins) {
    if (
      admin.toLowerCase() === email.toLowerCase() &&
      admin.toUpperCase() === email.toUpperCase()
    ) {
      return true;
    }
  }
  return false;
};

​

Hosted Deployments

const permissionCheckService = new PermissionCheckService();
const hasPermission = await permissionCheckService.checkPermission({
  userId,
  teamId,
  permission: "organization.read",
  fallbackRoles: [MembershipRole.OWNER, MembershipRole.ADMIN],
});

​

Testing SAML Configuration

​

1. Verify SAML Connection

# Check connection exists
curl -X GET "https://your-domain.com/api/auth/saml/config?tenant=team-123"

​

2. Initiate Test Login

1. Open incognito browser window
2. Navigate to /auth/login
3. Enter email address that matches SAML domain
4. Verify redirect to IdP
5. Log in with IdP credentials
6. Verify successful redirect back to Cal.com
7. Confirm user session is created

​

3. Check SAML Response

# Add logging for SAML events
DEBUG=saml*

​

Troubleshooting

​

Invalid SAML Response

1. Verify ACS URL exactly matches: https://your-domain.com/api/auth/saml/callback
2. Check Entity ID matches: https://saml.cal.com
3. Ensure certificate is not expired
4. Verify clock sync between IdP and Cal.com servers

​

User Not Found

1. Verify SAML connection is configured for the user’s team
2. Check user has membership in a team with SAML enabled
3. Confirm email in SAML assertion matches user’s email
4. Review SAML admin permissions

​

Auto-Provisioning Not Working

1. Set ORGANIZATIONS_AUTOLINK=1 in environment
2. Verify organization has verified the email domain
3. Check user email domain matches organization’s domain
4. Ensure user doesn’t already belong to another organization

​

Permission Denied

• Self-hosted: Add email to SAML_ADMINS environment variable
• Hosted: Assign Owner or Admin role in organization

​

Database Connection Error

1. Verify SAML_DATABASE_URL is correctly set
2. Ensure database exists and is accessible
3. Run migrations: DATABASE_URL=$SAML_DATABASE_URL yarn prisma migrate deploy
4. Check database credentials and network access

​

SAML Attributes

​

Security Best Practices

1. Certificate Validation: Always validate SAML assertions with IdP certificate
2. Encryption: Use CALENDSO_ENCRYPTION_KEY to encrypt sensitive SAML data
3. HTTPS Only: Never use SAML over HTTP in production
4. Short Session Lifetime: Configure IdP to issue short-lived assertions
5. Audit Logging: Monitor SAML login attempts and failures
6. Certificate Rotation: Rotate SAML certificates before expiration
7. Restrict Admins: Limit SAML_ADMINS to necessary personnel only

​

Advanced Configuration

​

Custom SAML Attributes

// Custom attribute mapping in IdP
Attributes:
  department  → user.department
  role        → user.role
  phone       → user.phone

• Custom routing logic
• Team assignment rules
• User metadata

​

Multiple SAML Connections

// Team A uses Okta
Tenant: team-123
IdP: Okta

// Team B uses Azure AD
Tenant: team-456
IdP: Azure AD

​

API Reference

​

SAML Endpoints

​

Connection Types

export type SSOConnection = (SAMLSSORecord | OIDCSSORecord) & {
  type: string;
  acsUrl: string | null;
  entityId: string | null;
  callbackUrl: string | null;
};

​

Related Documentation

• SSO Overview
• SCIM Provisioning
• Organizations Setup
• BoxyHQ SAML Jackson