Skip to main content

HubSpot

This guide explains how to set up single sign-on (SSO) between VaultysHub and HubSpot using SAML 2.0.

Prerequisites​

  • HubSpot Enterprise (Marketing Hub, Sales Hub, Service Hub, or CMS Hub)
  • Super Admin access to HubSpot
  • Verified email domain in HubSpot
  • Application configured in VaultysHub with SAML2

Note: SAML SSO is only available with HubSpot Enterprise plans.

Configuration in VaultysHub​

1. Create the application​

  1. Log in to VaultysHub as an administrator
  2. Go to Applications → Add
  3. Create a new application:
    • Name: HubSpot
    • URL: https://app.hubspot.com
    • Description: CRM and marketing automation platform
    • Icon: Choose the HubSpot icon

2. Configure SAML2​

  1. In the Authentication tab
  2. Select SAML2
  3. Configure the following settings:
    • Entity ID: the Entity ID of the Service Provider provided by HubSpot (not the URL of VaultysHub)
    • ACS URL: https://app.hubspot.com/login/saml
    • Format NameID: emailAddress
    • App ID: [appid] (automatically generated unique identifier)

3. Retrieve the metadata​

Note the following URLs:

  • IdP Metadata: https://[your-vaultyshub].link.vaultys.org/api/saml2/metadata/[appid]
  • SSO URL: https://[your-vaultyshub].link.vaultys.org/api/saml2/sso/[appid]
  • Entity ID: https://[your-vaultyshub].link.vaultys.org/[appid]
  • X.509 Certificate: Download from VaultysHub

Single Logout from VaultysHub is not supported.

Configuration in HubSpot​

1. Access SSO settings​

  1. Log in to HubSpot as a Super Admin
  2. Click on the Settings icon
  3. In the left menu: Account Defaults → Security
  4. Click on the Single Sign-On tab

2. Configure the identity provider​

Click on Configure SSO and fill in:

Identity Provider Settings​

  • Identity Provider Single Sign-On URL: https://[your-vaultyshub].link.vaultys.org/api/saml2/sso/[appid]
  • Identity Provider Identifier: https://[your-vaultyshub].link.vaultys.org/[appid]
  • Verification Certificate: Paste the X.509 certificate from VaultysHub

Service Provider Settings (provided by HubSpot)​

Note these values to configure them in VaultysHub if necessary:

  • Audience URI (SP Entity ID): https://api.hubspot.com
  • Sign on URL: https://app.hubspot.com/login/saml

3. Configure attributes​

Configure the SAML attribute mapping:

HubSpot AttributeSAML AttributeRequired
EmailemailYes
First NamefirstNameYes
Last NamelastNameYes

4. Configure domains​

  1. In Security → Login Verification
  2. Add your company domains
  3. Enable Require SSO for these domains

Configuration of teams and permissions​

Team structure​

VaultysHub does not pass user groups: teams and permissions are assigned directly in HubSpot (Settings → Users & Teams).

Custom roles​

Create roles in HubSpot:

  1. Settings → Users & Teams → Roles
  2. Create the roles you need
  3. Assign the appropriate permissions

Partitions (HubSpot Enterprise)​

To isolate data between teams:

partitions:
  - name: "EMEA Sales"
    teams: ["sales-emea"]
    objects: ["contacts", "companies", "deals"]
    
  - name: "Americas Sales"
    teams: ["sales-americas"]
    objects: ["contacts", "companies", "deals"]
    
  - name: "Marketing Global"
    teams: ["marketing"]
    objects: ["marketing-emails", "workflows", "forms"]

Test the configuration​

1. Connection test​

  1. Open a private browsing window
  2. Go to app.hubspot.com
  3. Click on Log in with SSO
  4. Enter your company email
  5. You are redirected to VaultysHub
  6. After authentication, you access HubSpot

2. Permission test​

// Test via the HubSpot API
const hubspot = require('@hubspot/api-client');

const hubspotClient = new hubspot.Client({
  accessToken: process.env.HUBSPOT_ACCESS_TOKEN
});

async function testPermissions() {
  try {
    // Test read contacts
    const contacts = await hubspotClient.crm.contacts.basicApi.getPage();
    console.log('Contacts access: ✓');
    
    // Test create deal
    const deal = await hubspotClient.crm.deals.basicApi.create({
      properties: {
        dealname: 'Test SSO Deal',
        amount: '1000'
      }
    });
    console.log('Deal creation: ✓');
  } catch (error) {
    console.error('Permission denied:', error.message);
  }
}

3. Mobile verification​

HubSpot mobile apps support SSO:

  • HubSpot Mobile App
  • HubSpot Keyboard (iOS)
  • HubSpot CRM Scanner

Integration with workflows​

Authentication-based triggers​

// Custom workflow triggered on SSO login
{
  "trigger": {
    "type": "user_login",
    "conditions": {
      "auth_method": "saml"
    }
  },
  "actions": [
    {
      "type": "send_email",
      "template": "welcome_sso_user",
      "to": "{{user.email}}"
    },
    {
      "type": "assign_onboarding_tasks",
      "tasks": ["complete_profile", "watch_training", "setup_signature"]
    }
  ]
}

Configuration of integrations​

HubSpot App Marketplace​

Marketplace apps work with SSO:

{
  "marketplace_apps": {
    "salesforce": {
      "sso_compatible": true,
      "additional_auth": "oauth2"
    },
    "slack": {
      "sso_compatible": true,
      "workspace_linking": true
    },
    "zoom": {
      "sso_compatible": true,
      "calendar_sync": true
    }
  }
}

Webhooks and API​

Configuration of webhooks with SSO authentication:

// Secure webhook endpoint
app.post('/webhooks/hubspot', verifyHubSpotSignature, async (req, res) => {
  const { subscriptionType, objectId, propertyName, propertyValue } = req.body;
  
  // Check that the user has permissions via SSO
  const user = await getUserFromWebhook(req);
  if (!hasPermission(user, subscriptionType)) {
    return res.status(403).json({ error: 'Insufficient permissions' });
  }
  
  // Process the webhook
  await processWebhook(req.body);
  res.status(200).send();
});

Troubleshooting​

"Invalid SAML Response" error​

Problem: The SAML response is not valid

Solution:

  1. Ensure that the Entity ID is https://[your-vaultyshub].link.vaultys.org/[appid] in VaultysHub
  2. Check the X.509 certificate (PEM format, without header/footer)
  3. Ensure that the ACS URL is: https://app.hubspot.com/login/saml
  4. Check the logs in HubSpot: Settings → Audit Logs

"User not authorized for this account" error​

Problem: The user does not have access to the HubSpot account

Solution:

  1. Ensure that the email domain is added and verified
  2. Make sure the user is provisioned in HubSpot
  3. Check the user's permissions in Users & Teams

Teams are not assigned​

Problem: Users are not in the correct teams

Solution: VaultysHub does not pass groups in the SAML assertion. Assign users to teams directly in HubSpot (Settings → Users & Teams).

Issue with mobile applications​

Problem: Unable to log in via the mobile app

Solution:

  1. Ensure that the Allow mobile SSO option is enabled
  2. Use the app's built-in browser, not an external browser
  3. Check that the SSL certificate is valid and recognized

Security​

{
  "security_settings": {
    "enforce_sso": true,
    "session_timeout": "12h",
    "require_2fa_for_api": true,
    "ip_restrictions": {
      "enabled": true,
      "allowed_ips": ["203.0.113.0/24"]
    },
    "api_key_rotation": "90d",
    "audit_log_retention": "2y",
    "sensitive_data_masking": true
  }
}

Compliance​

  • GDPR: HubSpot is GDPR compliant with DPA available
  • SOC 2 Type II: Certification available
  • ISO 27001: Certified
  • Privacy Shield: EU-US/Swiss-US Framework

Backup and recovery​

Recovery plan in case of SSO issues:

  1. Backup Super Admin account with local authentication
  2. API keys for emergency programmatic access
  3. Documentation of recovery procedures
  4. Contact HubSpot support Enterprise: priority support 24/7

User migration​

Batch migration script​

import pandas as pd
from hubspot import HubSpot
from datetime import datetime

def migrate_users_to_sso(csv_file):
    """Bulk migration to SSO"""
    api_client = HubSpot(access_token=ADMIN_TOKEN)
    users_df = pd.read_csv(csv_file)
    
    migration_report = []
    
    for index, user in users_df.iterrows():
        try:
            # Disable password authentication
            api_client.settings.users.update(
                user_id=user['user_id'],
                properties={
                    'authentication_method': 'saml_only',
                    'password_login_enabled': False
                }
            )
            
            # Send notification
            send_migration_email(user['email'])
            
            migration_report.append({
                'user': user['email'],
                'status': 'success',
                'timestamp': datetime.now()
            })
            
        except Exception as e:
            migration_report.append({
                'user': user['email'],
                'status': 'failed',
                'error': str(e)
            })
    
    return pd.DataFrame(migration_report)

Resources​