HubSpot

Dieser Leitfaden erklärt, wie man die Einmalanmeldung (SSO) zwischen SmartLink und HubSpot mithilfe von SAML 2.0 einrichtet.

Voraussetzungen

• HubSpot Enterprise (Marketing Hub, Sales Hub, Service Hub oder CMS Hub)
• Super Admin-Zugriff auf HubSpot
• Überprüfte E-Mail-Domain in HubSpot
• Anwendung in SmartLink mit SAML2 konfiguriert

Hinweis: SAML SSO ist nur mit den Enterprise-Plänen von HubSpot verfügbar.

Konfiguration in SmartLink

1. Anwendung erstellen

1. Melden Sie sich als Administrator bei SmartLink an
2. Gehen Sie zu Anwendungen → Hinzufügen
3. Erstellen Sie eine neue Anwendung:
   • Name: HubSpot
   • URL: https://app.hubspot.com
   • Beschreibung: CRM- und Marketing-Automatisierungsplattform
   • Symbol: Wählen Sie das HubSpot-Symbol aus

2. SAML2 konfigurieren

1. Im Tab Authentifizierung
2. Wählen Sie SAML2
3. Konfigurieren Sie die folgenden Parameter:
   • Entity ID: https://[your-smartlink].link.vaultys.org/[appid]
   • ACS-URL: https://app.hubspot.com/login/saml
   • Format NameID: emailAddress
   • App-ID: [appid] (automatisch generierte eindeutige Kennung)

3. Metadaten abrufen

Notieren Sie sich die folgenden URLs:

• IdP-Metadaten: https://[your-smartlink].link.vaultys.org/api/saml2/[appid]/metadata
• SSO-URL: https://[your-smartlink].link.vaultys.org/api/saml2/sso/[appid]
• SLO-URL: https://[your-smartlink].link.vaultys.org/api/saml2/slo/[appid]
• Entity ID: https://[your-smartlink].link.vaultys.org/[appid]
• X.509-Zertifikat: Von SmartLink herunterladen

Konfiguration in HubSpot

1. Zugriff auf SSO-Einstellungen

1. Melden Sie sich als Super Admin bei HubSpot an
2. Klicken Sie auf das Symbol Einstellungen (⚙️)
3. Im linken Menü: Account-Standards → Sicherheit
4. Klicken Sie auf den Tab Single Sign-On

2. Konfiguration des Identitätsanbieters

Klicken Sie auf SSO konfigurieren und füllen Sie aus:

Einstellungen des Identitätsanbieters

• Identitätsanbieter Single Sign-On-URL: https://[your-smartlink].link.vaultys.org/api/saml2/sso/[appid]
• Identitätsanbieter-Identifier: [appid]
• Verifizierungszertifikat: Fügen Sie das X.509-Zertifikat von SmartLink ein

Einstellungen des Dienstanbieters (von HubSpot bereitgestellt)

Notieren Sie diese Werte, um sie bei Bedarf in SmartLink zu konfigurieren:

• Ziel-URI (SP-Entity-ID): https://api.hubspot.com
• Anmeldungs-URL: https://app.hubspot.com/login/saml

3. Attributkonfiguration

Konfigurieren Sie das Mapping der SAML-Attribute:

HubSpot-Attribut	SAML-Attribut	Erforderlich
E-Mail	http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress	✅
Vorname	http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname	✅
Nachname	http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname	✅
Gruppen	groups	❌

4. Domänenkonfiguration

1. In Sicherheit → Anmeldeüberprüfung
2. Fügen Sie Ihre Unternehmensdomänen hinzu
3. Aktivieren Sie SSO erforderlich für diese Domänen

Konfiguration von Teams und Berechtigungen

Teamstruktur

{
  "teams": {
    "Vertrieb": {
      "berechtigungen": ["Kontakte lesen", "Kontakte schreiben", "Deals lesen", "Deals schreiben"],
      "saml_gruppe": "smartlink-vertrieb"
    },
    "Marketing": {
      "berechtigungen": ["Marketing: alle", "Inhalte schreiben", "Kampagnen verwalten"],
      "saml_gruppe": "smartlink-marketing"
    },
    "Service": {
      "berechtigungen": ["Tickets: alle", "Feedback lesen", "Wissensdatenbank schreiben"],
      "saml_gruppe": "smartlink-support"
    },
    "Admin": {
      "berechtigungen": ["Super-Admin"],
      "saml_gruppe": "smartlink-hubspot-admins"
    }
  }
}

Benutzerdefinierte Rollen

Erstellen Sie Rollen in HubSpot:

1. Einstellungen → Benutzer & Teams → Rollen
2. Erstellen Sie Rollen, die Ihren SmartLink-Gruppen entsprechen
3. Weisen Sie die entsprechenden Berechtigungen zu

Partitionen (HubSpot Enterprise)

Zur Isolierung von Daten zwischen Teams:

partitions:
  - name: "EMEA Vertrieb"
    teams: ["vertrieb-emea"]
    objekte: ["kontakte", "unternehmen", "deals"]
    
  - name: "Amerikas Vertrieb"
    teams: ["vertrieb-americas"]
    objekte: ["kontakte", "unternehmen", "deals"]
    
  - name: "Globales Marketing"
    teams: ["marketing"]
    objekte: ["marketing-e-mails", "workflows", "formulare"]

Konfigurationstest

1. Verbindungstest

1. Öffnen Sie ein privates Browserfenster
2. Gehen Sie zu app.hubspot.com
3. Klicken Sie auf Mit SSO anmelden
4. Geben Sie Ihre Unternehmens-E-Mail ein
5. Sie werden zu SmartLink weitergeleitet
6. Nach der Authentifizierung gelangen Sie zu HubSpot

2. Berechtigungstest

// Test über die HubSpot-API
const hubspot = require('@hubspot/api-client');

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

async function testBerechtigungen() {
  try {
    // Kontakte lesen testen
    const kontakte = await hubspotClient.crm.contacts.basicApi.getPage();
    console.log('Zugriff auf Kontakte: ✓');
    
    // Deal erstellen testen
    const deal = await hubspotClient.crm.deals.basicApi.create({
      properties: {
        dealname: 'Test-SO-Deal',
        amount: '1000'
      }
    });
    console.log('Deal erstellen: ✓');
  } catch (error) {
    console.error('Berechtigung verweigert:', error.message);
  }
}

3. Mobile Überprüfung

Die mobilen HubSpot-Apps unterstützen SSO:

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

Integration mit Workflows

Authentifizierungsbasierte Trigger

// Benutzerdefinierter Workflow bei SSO-Anmeldung auslösen
{
  "auslöser": {
    "typ": "benutzer_anmeldung",
    "bedingungen": {
      "auth_methode": "saml",
      "benutzer_gruppe": "smartlink-neue-benutzer"
    }
  },
  "aktionen": [
    {
      "typ": "e-mail_senden",
      "vorlage": "willkommen_sso_benutzer",
      "an": "{{benutzer.e-mail}}"
    },
    {
      "typ": "onboarding_aufgaben_zuweisen",
      "aufgaben": ["profil_vollständig_ausfüllen", "schulung_ansehen", "signatur_einrichten"]
    }
  ]
}

Automatisierungen mit SSO-Gruppen

# Skript zum automatischen Zuweisen von Leads
def leads_zuweisen_nach_sso_gruppe(benutzer_e-mail, sso_gruppen):
    if 'smartlink-vertrieb-emea' in sso_gruppen:
        team_zuweisen('EMEA Vertrieb', benutzer_e-mail)
    elif 'smartlink-vertrieb-americas' in sso_gruppen:
        team_zuweisen('Amerikas Vertrieb', benutzer_e-mail)
    else:
        team_zuweisen('Globaler Vertriebspool', benutzer-e-mail)

Integrationskonfiguration

HubSpot App Marketplace

Die Apps im Marketplace funktionieren mit SSO:

{
  "marketplace_apps": {
    "salesforce": {
      "sso_kompatibel": true,
      "zusätzliche_auth": "oauth2"
    },
    "slack": {
      "sso_kompatibel": true,
      "workspace_verknüpfung": true
    },
    "zoom": {
      "sso_kompatibel": true,
      "kalender_sync": true
    }
  }
}

Webhooks und API

Konfiguration von Webhooks mit SSO-Authentifizierung:

// Sichere Webhook-Endpunkt
app.post('/webhooks/hubspot', verifyHubSpotSignature, async (req, res) => {
  const { subscriptionType, objectId, propertyName, propertyValue } = req.body;
  
  // Überprüfen, ob der Benutzer über SSO-Berechtigungen verfügt
  const benutzer = await getUserFromWebhook(req);
  if (!hatBerechtigung(benutzer, subscriptionType)) {
    return res.status(403).json({ fehler: 'Unzureichende Berechtigungen' });
  }
  
  // Webhook verarbeiten
  await processWebhook(req.body);
  res.status(200).send();
});

Fehlerbehebung

Fehler "Ungültige SAML-Antwort"

Problem: Die SAML-Antwort ist ungültig

Lösung:

1. Überprüfen Sie, ob die Entity-ID in SmartLink [appid] ist
2. Überprüfen Sie das X.509-Zertifikat (PEM-Format, ohne Header/Fußzeile)
3. Stellen Sie sicher, dass die ACS-URL lautet: https://app.hubspot.com/login/saml
4. Überprüfen Sie die Protokolle in HubSpot: Einstellungen → Audit-Protokolle

Fehler "Benutzer nicht für dieses Konto autorisiert"

Problem: Der Benutzer hat keinen Zugriff auf das HubSpot-Konto

Lösung:

1. Überprüfen Sie, ob die E-Mail-Domain hinzugefügt und überprüft ist
2. Stellen Sie sicher, dass der Benutzer in HubSpot provisioniert ist
3. Überprüfen Sie die Berechtigungen des Benutzers unter Benutzer & Teams

Teams sind nicht zugewiesen

Problem: Benutzer sind nicht in den richtigen Teams

Lösung:

<!-- Richtige Formatierung der SAML-Aussage für Gruppen -->
<saml:Attribut Name="groups">
  <saml:Attributwert>smartlink-hubspot-vertrieb</saml:Attributwert>
  <saml:Attributwert>smartlink-hubspot-emea</saml:Attributwert>
</saml:Attribut>

Problem mit mobilen Apps

Problem: Keine Verbindung über die mobile App möglich

Lösung:

1. Stellen Sie sicher, dass die Option Mobile SSO zulassen aktiviert ist
2. Verwenden Sie den integrierten Browser der App, nicht einen externen Browser
3. Überprüfen Sie, ob das SSL-Zertifikat gültig und erkannt ist

Sicherheit

Empfohlene Konfiguration

{
  "security_settings": {
    "sso_erzwingen": true,
    "session_timeout": "12h",
    "2fa_für_api_erfordern": true,
    "ip_einschränkungen": {
      "aktiviert": true,
      "erlaubte_ips": ["203.0.113.0/24"]
    },
    "api_key_rotation": "90d",
    "audit_log_retention": "2y",
    "sensitive_data_masking": true
  }
}

Compliance

• DSGVO: HubSpot ist DSGVO-konform mit verfügbarer DPA
• SOC 2 Typ II: Zertifizierung verfügbar
• ISO 27001: Zertifiziert
• Privacy Shield: EU-US/Swiss-US-Rahmen

Backup und Wiederherstellung

Wiederherstellungsplan bei SSO-Problemen:

1. Backup-Super-Admin-Konto mit lokaler Authentifizierung
2. API-Schlüssel für den Notfall-Zugriff
3. Dokumentation der Wiederherstellungsverfahren
4. Support kontaktieren HubSpot Enterprise: Priorisierter 24/7-Support

Benutzermigration

Batch-Migrationskript

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

def benutzer_zu_sso_migrieren(csv_datei):
    """Massenmigration zu SSO"""
    api_client = HubSpot(access_token=ADMIN_TOKEN)
    users_df = pd.read_csv(csv_datei)
    
    migrationsbericht = []
    
    for index, user in users_df.iterrows():
        try:
            # Deaktivieren der Passwortauthentifizierung
            api_client.settings.users.update(
                user_id=user['user_id'],
                properties={
                    'authentication_method': 'saml_only',
                    'password_login_enabled': False
                }
            )
            
            # Benachrichtigung senden
            send_migration_email(user['email'])
            
            migrationsbericht.append({
                'benutzer': user['email'],
                'status': 'erfolgreich',
                'zeitstempel': datetime.now()
            })
            
        except Exception as e:
            migrationsbericht.append({
                'benutzer': user['email'],
                'status': 'fehlgeschlagen',
                'fehler': str(e)
            })
    
    return pd.DataFrame(migrationsbericht)

Ressourcen

• HubSpot SSO-Dokumentation
• HubSpot API-Dokumentation
• HubSpot Academy - Sicherheitsbewährte Praktiken
• SAML-Konfiguration SmartLink
• HubSpot Community Forum