HubSpot

Ce guide vous explique comment configurer l'authentification unique (SSO) entre SmartLink et HubSpot en utilisant SAML 2.0.

Prérequis

• HubSpot Enterprise (Marketing Hub, Sales Hub, Service Hub ou CMS Hub)
• Accès Super Admin à HubSpot
• Domaine email vérifié dans HubSpot
• Application configurée dans SmartLink avec SAML2

Note : Le SSO SAML est disponible uniquement avec les plans Enterprise de HubSpot.

Configuration dans SmartLink

1. Créer l'application

1. Connectez-vous à SmartLink en tant qu'administrateur
2. Allez dans Applications → Ajouter
3. Créez une nouvelle application :
   • Nom : HubSpot
   • URL : https://app.hubspot.com
   • Description : Plateforme CRM et marketing automation
   • Icône : Choisissez l'icône HubSpot

2. Configurer SAML2

1. Dans l'onglet Authentification
2. Sélectionnez SAML2
3. Configurez les paramètres suivants :
   • Entity ID : https://[votre-smartlink].link.vaultys.org/[appid]
   • ACS URL : https://app.hubspot.com/login/saml
   • Format NameID : emailAddress
   • App ID : [appid] (identifiant unique généré automatiquement)

3. Récupérer les métadonnées

Notez les URLs suivantes :

• Métadonnées IdP : https://[votre-smartlink].link.vaultys.org/api/saml2/[appid]/metadata
• SSO URL : https://[votre-smartlink].link.vaultys.org/api/saml2/sso/[appid]
• SLO URL : https://[votre-smartlink].link.vaultys.org/api/saml2/slo/[appid]
• Entity ID : https://[votre-smartlink].link.vaultys.org/[appid]
• Certificat X.509 : Téléchargez depuis SmartLink

Configuration dans HubSpot

1. Accéder aux paramètres SSO

1. Connectez-vous à HubSpot en tant que Super Admin
2. Cliquez sur l'icône Paramètres (⚙️)
3. Dans le menu de gauche : Account Defaults → Security
4. Cliquez sur l'onglet Single Sign-On

2. Configuration du fournisseur d'identité

Cliquez sur Configure SSO et remplissez :

Identity Provider Settings

• Identity Provider Single Sign-On URL : https://[votre-smartlink].link.vaultys.org/api/saml2/sso/[appid]
• Identity Provider Identifier : [appid]
• Verification Certificate : Collez le certificat X.509 depuis SmartLink

Service Provider Settings (fourni par HubSpot)

Notez ces valeurs pour les configurer dans SmartLink si nécessaire :

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

3. Configuration des attributs

Configurez le mapping des attributs SAML :

Attribut HubSpot	Attribut SAML	Obligatoire
Email	http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress	✅
First Name	http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname	✅
Last Name	http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname	✅
Groups	groups	❌

4. Configuration des domaines

1. Dans Security → Login Verification
2. Ajoutez vos domaines d'entreprise
3. Activez Require SSO pour ces domaines

Configuration des équipes et permissions

Structure des équipes

{
  "teams": {
    "Sales": {
      "permissions": ["contacts:read", "contacts:write", "deals:read", "deals:write"],
      "saml_group": "smartlink-sales"
    },
    "Marketing": {
      "permissions": ["marketing:all", "content:write", "campaigns:manage"],
      "saml_group": "smartlink-marketing"
    },
    "Service": {
      "permissions": ["tickets:all", "feedback:read", "knowledge:write"],
      "saml_group": "smartlink-support"
    },
    "Admin": {
      "permissions": ["super-admin"],
      "saml_group": "smartlink-hubspot-admins"
    }
  }
}

Rôles personnalisés

Créez des rôles dans HubSpot :

1. Settings → Users & Teams → Roles
2. Créez des rôles correspondant à vos groupes SmartLink
3. Assignez les permissions appropriées

Partitions (HubSpot Enterprise)

Pour isoler les données entre équipes :

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 de la configuration

1. Test de connexion

1. Ouvrez une fenêtre de navigation privée
2. Allez sur app.hubspot.com
3. Cliquez sur Log in with SSO
4. Entrez votre email d'entreprise
5. Vous êtes redirigé vers SmartLink
6. Après authentification, vous accédez à HubSpot

2. Test des permissions

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

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

async function testPermissions() {
  try {
    // Test lecture contacts
    const contacts = await hubspotClient.crm.contacts.basicApi.getPage();
    console.log('Contacts access: ✓');
    
    // Test création 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. Vérification mobile

Les applications mobiles HubSpot supportent le SSO :

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

Intégration avec les workflows

Déclencheurs basés sur l'authentification

// Workflow personnalisé déclenché à la connexion SSO
{
  "trigger": {
    "type": "user_login",
    "conditions": {
      "auth_method": "saml",
      "user_group": "smartlink-new-users"
    }
  },
  "actions": [
    {
      "type": "send_email",
      "template": "welcome_sso_user",
      "to": "{{user.email}}"
    },
    {
      "type": "assign_onboarding_tasks",
      "tasks": ["complete_profile", "watch_training", "setup_signature"]
    }
  ]
}

Automatisations avec les groupes SSO

# Script pour assigner automatiquement les leads
def assign_leads_by_sso_group(user_email, sso_groups):
    if 'smartlink-sales-emea' in sso_groups:
        assign_to_team('EMEA Sales', user_email)
    elif 'smartlink-sales-americas' in sso_groups:
        assign_to_team('Americas Sales', user_email)
    else:
        assign_to_team('Global Sales Pool', user_email)

Configuration des intégrations

HubSpot App Marketplace

Les apps du marketplace fonctionnent avec 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 et API

Configuration des webhooks avec authentification SSO :

// Webhook endpoint sécurisé
app.post('/webhooks/hubspot', verifyHubSpotSignature, async (req, res) => {
  const { subscriptionType, objectId, propertyName, propertyValue } = req.body;
  
  // Vérifier que l'utilisateur a les permissions via SSO
  const user = await getUserFromWebhook(req);
  if (!hasPermission(user, subscriptionType)) {
    return res.status(403).json({ error: 'Insufficient permissions' });
  }
  
  // Traiter le webhook
  await processWebhook(req.body);
  res.status(200).send();
});

Dépannage

Erreur "Invalid SAML Response"

Problème : La réponse SAML n'est pas valide

Solution :

1. Vérifiez que l'Entity ID est bien [appid] dans SmartLink
2. Vérifiez le certificat X.509 (format PEM, sans header/footer)
3. Assurez-vous que l'ACS URL est : https://app.hubspot.com/login/saml
4. Vérifiez les logs dans HubSpot : Settings → Audit Logs

Erreur "User not authorized for this account"

Problème : L'utilisateur n'a pas accès au compte HubSpot

Solution :

1. Vérifiez que le domaine email est ajouté et vérifié
2. Assurez-vous que l'utilisateur est provisionné dans HubSpot
3. Vérifiez les permissions de l'utilisateur dans Users & Teams

Les équipes ne sont pas assignées

Problème : Les utilisateurs ne sont pas dans les bonnes équipes

Solution :

<!-- Format correct de l'assertion SAML pour les groupes -->
<saml:Attribute Name="groups">
  <saml:AttributeValue>smartlink-hubspot-sales</saml:AttributeValue>
  <saml:AttributeValue>smartlink-hubspot-emea</saml:AttributeValue>
</saml:Attribute>

Problème avec les applications mobiles

Problème : Impossible de se connecter via l'app mobile

Solution :

1. Assurez-vous que l'option Allow mobile SSO est activée
2. Utilisez le navigateur intégré de l'app, pas un navigateur externe
3. Vérifiez que le certificat SSL est valide et reconnu

Sécurité

Configuration recommandée

{
  "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
  }
}

Conformité

• GDPR : HubSpot est conforme GDPR avec DPA disponible
• SOC 2 Type II : Certification disponible
• ISO 27001 : Certifié
• Privacy Shield : Framework EU-US/Swiss-US

Backup et récupération

Plan de récupération en cas de problème SSO :

1. Compte Super Admin de secours avec authentification locale
2. API keys pour accès programmatique d'urgence
3. Documentation des procédures de récupération
4. Contact support HubSpot Enterprise : support prioritaire 24/7

Migration des utilisateurs

Script de migration batch

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

def migrate_users_to_sso(csv_file):
    """Migration en masse vers 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:
            # Désactiver l'auth par mot de passe
            api_client.settings.users.update(
                user_id=user['user_id'],
                properties={
                    'authentication_method': 'saml_only',
                    'password_login_enabled': False
                }
            )
            
            # Envoyer 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)

Ressources

• Documentation HubSpot SSO
• HubSpot API Documentation
• HubSpot Academy - Security Best Practices
• Configuration SAML SmartLink
• HubSpot Community Forum