# Connector einrichten

> Einen Connector für Ihre Organisation installieren, konfigurieren, eine OAuth-App registrieren oder einen API-Schlüssel hinterlegen und festlegen, wer ihn benutzen darf. Mit jeder Ansicht, den Anleitungen der Anbieter, der Netz-Freigabe und der Lösung für jeden Verbindungsfehler.

Jeder Connector wird gleich eingerichtet, egal womit er sich verbindet: Sie installieren ihn für die Organisation, tragen ein, was der Connector wissen muss, bereiten die Anmeldung beim Anbieter vor und legen fest, wer ihn benutzen darf. Danach verbindet jede Person mit einem Klick ihr eigenes Konto oder arbeitet mit einem gemeinsamen Konto, das Sie für alle verbunden haben.

Diese Anleitung begleitet Jana Brandt, Administratorin bei Brandt & Söhne, durch zwei typische Fälle. **Outlook E-Mail** meldet sich über OAuth an: Jana registriert einmal eine App in Microsoft Entra, danach meldet sich jede Person mit ihrem eigenen Microsoft-Konto an. **Paperboi**, das Archiv der Firma, läuft auf einem Server im Büronetz und arbeitet mit API-Schlüsseln: Jana trägt die API-Adresse ein, gibt den Server in der Netz-Freigabe frei und hinterlegt einen gemeinsamen Schlüssel. Fast alle anderen Connectoren sind eine Spielart dieser beiden.

## Bevor Sie beginnen

- Sie brauchen das Recht `ai.plugin.admin`. Administratoren haben es.
- Schauen Sie nach, wie sich der Connector anmeldet. Der [Katalog](/de/plugins/catalog/) nennt es für jeden Connector, und die Connector-Seite zeigt es im Abschnitt <Ui>Einrichtung</Ui>.
- **Für OAuth-Connectoren:** Sie brauchen Administratorzugang zur Entwicklerkonsole des Anbieters (Microsoft Entra Admin Center, Google Cloud Console, Atlassian Developer Console und so weiter), um eine App zu registrieren.
- **Für Connectoren mit API-Schlüssel:** Entscheiden Sie, ob jede Person ihren eigenen Schlüssel mitbringt oder ein gemeinsamer Schlüssel für alle gilt.
- **Für Systeme im eigenen Netz:** Das System muss vom nexxus-Server aus erreichbar sein. Seine Adresse geben Sie unter <Ui>Netz-Freigabe</Ui> frei, siehe [unten](#systeme-im-eigenen-netz-erreichen).

## Connector installieren

<Steps>

1. Öffnen Sie <MenuPath to="KI > KI einrichten > Connectoren" />.

   Der Katalog zeigt zuerst den Abschnitt <Ui>Installiert</Ui>, dann <Ui>Beliebt</Ui> (nach Zahl der verbundenen Personen in Ihrem Mandanten), dann jede Kategorie. Als Administrator sehen Sie den ganzen Katalog, alle anderen nur, was installiert ist.

2. Suchen Sie den Connector über <Ui>Connectoren durchsuchen</Ui> oder grenzen Sie die Liste mit den Reitern <Ui>Alle</Ui>, <Ui>Integrationen</Ui>, <Ui>Skills</Ui> und <Ui>Werkzeuge</Ui> ein.

3. Klicken Sie auf der Karte des Connectors auf **+** (<Ui>Installieren</Ui>).

   Braucht der Connector vorher einen Wert, etwa die API-Adresse bei Paperboi, öffnet nexxus die Connector-Seite bei <Ui>Konfiguration</Ui> und setzt den Cursor ins erste leere Pflichtfeld. Sonst erscheint <Ui>{'{name} ist installiert.'}</Ui>

   <Screenshot src={shot_plg_catalog_install} url="/plugins" alt={"Der Abschnitt Dateien und Ablage mit dem Knopf zum Installieren auf der Paperboi-Karte"} caption={"„+“ installiert den Connector oder öffnet zuerst die Konfiguration, wenn ein Wert fehlt."} />

4. Klicken Sie auf den Namen des Connectors, um seine Seite zu öffnen.

</Steps>

Sie können einen Connector auch zuerst öffnen und oben auf seiner Seite auf <Ui>Installieren</Ui> klicken. Die Seite beginnt mit der Beschreibung und einem Satz dazu, wohin die Daten gehen. Bei Paperboi heißt es dort, dass Anfragen mit dem Schlüssel der Person direkt an die eingestellte Paperboi-Instanz gehen. Darunter folgen die Abschnitte, die für diesen Connector gelten:

| Abschnitt | Wer ihn sieht | Wofür |
|---|---|---|
| <Ui>Einrichtung</Ui> | Alle, Administratoren ausführlicher | Was beim Anbieter einzurichten ist und was jede Person vor dem Verbinden braucht |
| <Ui>Meine Verbindung</Ui> | Alle, bei Connectoren mit persönlicher Anmeldung | Verbinden, neu verbinden, Berechtigungen ergänzen, trennen |
| <Ui>Verbindung für alle</Ui> | Administratoren, bei Connectoren mit gemeinsamer Anmeldung | Ein Konto für die ganze Organisation verbinden |
| <Ui>Berechtigungen</Ui> | Alle, bei Connectoren mit Berechtigungsgruppen | Welche Gruppen die Organisation erlaubt und die Person freigibt |
| <Ui>Benötigt</Ui> | Skills | Die Connectoren, die der Skill mit einschaltet |
| <Ui>Aktionen</Ui> | Alle, Häkchen nur für Administratoren | Jede Aktion, lesend oder schreibend, erlaubt oder nicht |
| <Ui>Auslöser</Ui> | Connectoren mit Auslösern | Einen Ihrer KI-Schedules starten, wenn etwas Neues ankommt |
| <Ui>Installation</Ui> | Administratoren | An oder aus, vorausgewählt oder nicht, beschränkt auf Rollen oder Geschäftseinheiten |
| <Ui>Konfiguration</Ui> | Administratoren | Werte für alle: API-Adresse, OAuth-App, Region des Anbieters |
| <Ui>Letzte Aufrufe</Ui> | Administratoren | Wer welche Aktion wann aufgerufen hat, ohne Inhalte |

<Screenshot src={shot_plg_detail_hero} url="/plugins/paperboi" alt={"Der Kopf der Connector-Seite von Paperboi mit Chips und Beschreibung"} caption={"Die Connector-Seite beginnt damit, was der Connector ist und wie viel er benutzt wird."} />

## Konfiguration ausfüllen

Unter <Ui>Konfiguration</Ui> stehen die Werte, die für die ganze Organisation gelten: die Adresse eines selbst betriebenen Systems, die Region des Anbieters oder Ihre eigene OAuth-App. Die Feldnamen bringt der Connector selbst mit, bei Paperboi etwa <Ui>API-Adresse</Ui>.

| Feldart | Erscheint als | Hinweis |
|---|---|---|
| Adresse (URL) | Textfeld | Muss mit `http://` oder `https://` beginnen, sonst <Ui>Bitte eine Adresse mit http:// oder https:// angeben.</Ui> |
| Zahl | Zahlenfeld | Ganze Zahlen, wo der Connector eine verlangt, etwa einen Port |
| Ja oder nein | Schalter <Ui>An</Ui> / <Ui>Aus</Ui> | Etwa <Ui>In Dateien anzeigen</Ui> bei Paperboi |
| Auswahl | Auswahlliste | Etwa die Region bei DeepL, Intercom, Make, Pylon oder Wrike |
| Geheimnis | Passwortfeld, nie vorausgefüllt | Nach dem Speichern steht dort <Ui>Gespeichert. Leer lassen, um den Wert zu behalten.</Ui> |
| Text | Textfeld oder Textbereich | Alles andere |

Pflichtfelder tragen den Hinweis <Ui>Pflichtfeld</Ui>. Klicken Sie auf <Ui>Speichern</Ui> (oder <Ui>Installieren</Ui>, wenn der Connector noch nicht installiert ist). nexxus speichert die Konfiguration als Ganzes verschlüsselt und zeigt ein Geheimnis nie wieder an.

OAuth-Connectoren bieten hier immer <Ui>Client-ID</Ui> und <Ui>Client-Secret</Ui> an. Connectoren, die sich bei Microsoft anmelden, haben zusätzlich <Ui>Entra-Mandant (Domain oder ID)</Ui>. Ein leeres Feld nimmt den Standardwert des Connectors. Viele Connectoren lassen sich deshalb installieren, ohne das Formular überhaupt zu öffnen.

<Screenshot src={shot_plg_detail_install_config} url="/plugins/paperboi#konfiguration" alt={"Installation und Konfiguration von Paperboi vor dem Installieren"} caption={"Installation legt fest, wer den Connector bekommt, Konfiguration hält die Werte für alle."} />

## Festlegen, wer ihn bekommt

### Installation

Unter <Ui>Installation</Ui> legen Sie für diesen Mandanten fest, ob der Connector an ist, ob er in neuen Unterhaltungen vorausgewählt ist und wer ihn benutzen darf.

- <Ui>Connector</Ui>: <Ui>Eingeschaltet</Ui> oder <Ui>Ausgeschaltet</Ui>. Ausgeschaltet verschwindet er bei allen aus der Auswahl, die Einstellungen bleiben.
- <Ui>In neuen Unterhaltungen</Ui>: der Standard des Connectors, angezeigt als <Ui>Standard des Connectors (vorausgewählt)</Ui> oder <Ui>Standard des Connectors (nicht vorausgewählt)</Ui>, oder Ihre Wahl <Ui>Vorausgewählt</Ui> beziehungsweise <Ui>Nicht vorausgewählt</Ui>.
- <Ui>Nur für Rollen</Ui>: leer bedeutet alle, die Connectoren benutzen dürfen.
- <Ui>Nur für Geschäftseinheiten</Ui>: leer bedeutet alle Geschäftseinheiten. Eine Einheit schließt die Einheiten darunter ein.

Wer nicht dazugehört, sieht den Connector nirgends: nicht im Katalog und nicht im Chat.

### Aktionen

<Ui>Aktionen</Ui> listet jede Aktion mit dem Chip <Ui>Lesen</Ui> oder <Ui>Schreiben</Ui>. Je Aktion gibt es zwei Häkchen:

- <Ui>Erlaubt</Ui>: Nehmen Sie das Häkchen weg, bekommt der KI-Assistent die Aktion nicht mehr, für niemanden im Mandanten. Brandt & Söhne nimmt bei Paperboi das Häkchen an <Ui>Eingang archivieren</Ui> weg, bis sich das Archivteam auf die Dokumenttypen geeinigt hat.
- <Ui>Immer bestätigen</Ui>: Die Aktion fragt vor jedem Aufruf nach, auch wenn sie nur liest. Verlangt der Connector die Bestätigung schon selbst, ist das Häkchen gesperrt: <Ui>Diese Aktion fragt immer nach, das lässt sich nicht abschalten.</Ui>

### Berechtigungen

Bei Connectoren mit Berechtigungsgruppen zeigt <Ui>Berechtigungen</Ui> jede Gruppe mit dem, was sie freischaltet. Das Häkchen <Ui>Erlaubt</Ui> entscheidet, ob die Organisation die Gruppe überhaupt anbietet. Abgeschaltete Gruppen fragt nexxus beim Anbieter nicht an und bietet sie im Chat nicht an. Pflichtgruppen sind gesperrt: <Ui>Ohne diese Berechtigung funktioniert der Connector nicht.</Ui>

<Ui>Verbindung prüfen</Ui> meldet Sie einmal mit allem an, was erlaubt ist, und zeigt je Gruppe, was der Anbieter tatsächlich freigibt: <Ui>Freigegeben</Ui>, <Ui>Nicht freigegeben</Ui> oder <Ui>Abgeschaltet</Ui>.

<Screenshot src={shot_plg_detail_permissions} url="/plugins/outlook-mail" alt={"Die Berechtigungsgruppen von Outlook E-Mail mit den Häkchen Erlaubt"} caption={"Jede Gruppe schaltet Aktionen frei. Abgeschaltete Gruppen werden nie angefragt."} />

## Mit API-Schlüssel verbinden

Connectoren mit API-Schlüssel oder Login brauchen keine App beim Anbieter. Jede Person erzeugt dort ihren eigenen Schlüssel, oder Sie hinterlegen einen Schlüssel für alle.

<Steps>

1. Entscheiden Sie auf der Connector-Seite, wem der Schlüssel gehört.

   - Ihr eigener: unter <Ui>Meine Verbindung</Ui> auf <Ui>Verbinden</Ui> klicken.
   - Einer für alle: unter <Ui>Verbindung für alle</Ui> auf <Ui>Für alle verbinden</Ui> klicken. Das gibt es nur bei Connectoren, die eine gemeinsame Verbindung erlauben.

2. Tragen Sie im Dialog <Ui>{'Mit {name} verbinden'}</Ui> beziehungsweise <Ui>{'{name} für alle verbinden'}</Ui> die Felder ein, die der Connector verlangt. Bei Paperboi ist das ein Feld, <Ui>Paperboi-API-Schlüssel</Ui>: der geheime Schlüssel (secretKey) eines Paperboi-API-Schlüssels mit dem Bereich „api“.

   <Screenshot src={shot_plg_dlg_credentials} url="/plugins/paperboi" alt={"Der Dialog, um Paperboi mit einem API-Schlüssel zu verbinden"} caption={"Schlüssel werden verschlüsselt gespeichert und nur für Ihre eigenen Aufrufe benutzt."} />

3. Klicken Sie auf <Ui>Verbinden</Ui>. Es erscheint <Ui>{'{name} ist verbunden.'}</Ui>

</Steps>

Die Angaben werden verschlüsselt gespeichert. Ein persönlicher Schlüssel gilt nur für Ihre eigenen Aufrufe. Einen gemeinsamen Schlüssel benutzen alle, die keinen eigenen verbunden haben. Erlaubt ein Connector beides, gilt immer der eigene Schlüssel der Person.

:::caution[Ein gemeinsamer Schlüssel teilt seine Sicht]
Bei einer Verbindung für alle sieht jede Person mit Zugriff auf den Connector, was dieser Schlüssel beim Anbieter sieht. Legen Sie für ein Archiv oder ein CRM einen eigenen Schlüssel an, der genau die Rechte hat, die die Organisation haben soll, oder lassen Sie jede Person ihren eigenen verbinden.
:::

## Mit OAuth verbinden

OAuth heißt: Jede Person meldet sich mit ihrem eigenen Konto beim Anbieter an, und nexxus bekommt dafür einen Token. Dazu muss der Anbieter nexxus kennen. Sie registrieren dort einmal eine **App**. Die App hat eine Client-ID und ein Client-Secret, nennt die **Weiterleitungs-URI**, zu der der Anbieter die Person zurückschicken darf, und erlaubt die **Berechtigungen** (Scopes), die der Connector anfragt.

<Flow
  steps={[
    { icon: 'app-window', title: 'Sie registrieren eine App', text: 'In der Konsole des Anbieters, mit Weiterleitungs-URI und Berechtigungen von der Connector-Seite.', tone: 'cyan' },
    { icon: 'key-round', title: 'Sie hinterlegen die App in nexxus', text: 'Client-ID und Client-Secret in der Konfiguration des Connectors.' },
    { icon: 'user-check', title: 'Jede Person meldet sich an', text: 'In einem Pop-up beim Anbieter, mit dem eigenen Konto.', tone: 'lavender' },
    { icon: 'circle-check-big', title: 'Der KI-Assistent arbeitet mit diesem Konto', text: 'Tokens bleiben auf dem Server und erneuern sich selbst.' },
  ]}
  caption="Die App registrieren Sie einmal. Alle Microsoft-Connectoren können sich eine App teilen, ebenso alle Google-Connectoren."
/>

<Steps>

1. Öffnen Sie die Connector-Seite und sehen Sie sich <Ui>Einrichtung</Ui> an.

   Oben steht <Ui>{'Bei {name}'}</Ui> mit dem Chip <Ui>Noch keine App eingerichtet</Ui>, ein Knopf zur Konsole des Anbieters und dessen Anleitung. Darunter folgen nummerierte Schritte. Der Schritt mit der Weiterleitungs-URI trägt ein Kopierfeld <Ui>Weiterleitungs-URI (in der App des Anbieters eintragen)</Ui> mit <Ui>Kopieren</Ui>, der Schritt mit den Berechtigungen listet <Ui>Berechtigungen, die die App erlauben muss</Ui>. Schritte, die nur dieser Connector braucht, tragen den Hinweis <Ui>{'Nur für {name}'}</Ui>.

   <Screenshot src={shot_plg_detail_oauth_setup} url="/plugins/outlook-mail" alt={"Die Einrichtungsanleitung für Outlook E-Mail mit Weiterleitungs-URI und Berechtigungen"} caption={"Die Einrichtung zeigt die Schritte des Anbieters mit Weiterleitungs-URI und Berechtigungen."} />

2. Registrieren Sie die App in der Konsole des Anbieters und folgen Sie den Schritten. Die Anleitungen der wichtigsten Anbieter sind [unten](#anleitungen-der-anbieter) zusammengefasst.

3. Tragen Sie zurück in nexxus unter <Ui>Konfiguration</Ui> die <Ui>Client-ID</Ui> und das <Ui>Client-Secret</Ui> ein und klicken Sie auf <Ui>Speichern</Ui>.

4. <Ui>Einrichtung</Ui> zeigt jetzt <Ui>{'{name} ist fertig eingerichtet'}</Ui>. Kopieren Sie die <Ui>Nachricht an Ihre Nutzer</Ui> und schicken Sie sie Ihrem Team. Sie sagt, wo man klickt und dass der Assistent nur sieht, was das eigene Konto sehen darf. Die Anleitung klappt sich zu, <Ui>Anleitung anzeigen</Ui> öffnet sie wieder.

   <Screenshot src={shot_plg_detail_ready} url="/plugins/outlook-mail" alt={"Outlook E-Mail fertig eingerichtet, mit der Nachricht an die Nutzer"} caption={"Ist alles eingerichtet, gibt Ihnen die Seite eine Nachricht für Ihre Nutzer."} />

5. Probieren Sie es selbst aus: Klicken Sie unter <Ui>Meine Verbindung</Ui> auf <Ui>Verbinden</Ui>, haken Sie die Berechtigungsgruppen an, die Sie freigeben wollen, und melden Sie sich im Pop-up an. Kurz danach erscheint <Ui>{'{name} ist verbunden.'}</Ui>

</Steps>

### Die Weiterleitungs-URI

nexxus hat genau eine Weiterleitungs-URI, dieselbe für jeden Connector und jeden Anbieter:

```text
https://<Ihre nexxus-Adresse>/api/plugins/oauth/callback
```

Die Connector-Seite zeigt immer den genauen Wert für Ihre Installation. Kopieren Sie ihn von dort. Bei einer selbst betriebenen Installation bildet nexxus sie aus der öffentlichen Adresse in der Einstellung `sso.issuer` (Umgebungsvariable `NEXXUS_SSO_ISSUER`). Setzen Sie sie auf die öffentliche HTTPS-Adresse Ihres Backends. Sonst nimmt nexxus die Adresse aus der eingehenden Anfrage, und die passt womöglich nicht zu dem, was der Anbieter erwartet.

### Anleitungen der Anbieter

nexxus bringt Einrichtungsanleitungen für 25 OAuth-Anbieter mit. Die Connector-Seite zeigt die passende, mit Weiterleitungs-URI und Berechtigungen an der richtigen Stelle. Das verlangen sie.

#### Microsoft

Eine Entra-App genügt für alle Connectoren, die sich bei Microsoft anmelden: Outlook E-Mail, Outlook Kalender, Microsoft Teams, SharePoint, OneDrive, Excel, Microsoft Planner, Microsoft Entra ID, Azure DevOps, Dynamics 365, Power BI, Microsoft Fabric, Azure Data Explorer, Azure Databricks und Azure Data Factory. Ein Microsoft-Connector ohne eigene Client-ID nimmt die App eines anderen installierten Microsoft-Connectors. Gibt es keine, nimmt er die Entra-App, die Ihre [Anmeldung mit Microsoft](/de/setup/sign-in/) schon nutzt. Lassen Sie dann <Ui>Client-ID</Ui> und <Ui>Client-Secret</Ui> leer und ergänzen Sie an jener App nur Weiterleitungs-URI und Berechtigungen.

1. Im Microsoft Entra Admin Center unter „Entra ID“ › „App registrations“ › „New registration“ eine App anlegen und bei „Supported account types“ „Single tenant only“ wählen. Das entfällt, wenn Sie die App Ihrer Microsoft-Anmeldung nutzen.
2. In der App unter „Authentication“ › „Add Redirect URI“ die Plattform „Web“ wählen und die Weiterleitungs-URI eintragen.
3. Unter „API permissions“ › „Add a permission“ › „Microsoft Graph“ › „Delegated permissions“ die Berechtigungen von der Connector-Seite hinzufügen. Steht bei einer in der Spalte „Admin consent required“ „Yes“, danach auf „Grant admin consent for ...“ klicken, sonst scheitert die Anmeldung mit „Administratorgenehmigung erforderlich“.
4. Unter „Certificates & secrets“ › „Client secrets“ › „New client secret“ ein Secret anlegen und seinen „Value“ sofort kopieren. Er wird nur einmal angezeigt und läuft nach höchstens 24 Monaten ab.
5. Auf der Seite „Overview“ die „Application (client) ID“ und die „Directory (tenant) ID“ kopieren und mit dem Secret unter <Ui>Konfiguration</Ui> eintragen. Die Directory (tenant) ID gehört in <Ui>Entra-Mandant (Domain oder ID)</Ui>.

Azure DevOps hat einen eigenen Schritt: unter „API permissions“ statt Microsoft Graph die API „Azure DevOps“ wählen und `vso.project`, `vso.work_write`, `vso.code`, `vso.build_execute` und `vso.wiki` hinzufügen. Es nimmt nur Geschäfts- und Schulkonten an.

Microsoft Fabric, Azure Data Explorer, Azure Databricks und Azure Data Factory haben ebenfalls je einen eigenen Schritt: unter „API permissions“ statt Microsoft Graph ihre API wählen. Das ist „Power BI Service“ für Microsoft Fabric, „Azure Data Explorer“, „AzureDatabricks“ und „Azure Service Management“ für Azure Data Factory. Welche Berechtigungen dazukommen, steht auf der Seite des Connectors.

#### Google

Eine Google-App genügt für Gmail, Google Kalender, Google Drive, Google Docs, Google Tabellen und BigQuery. Jeder Connector bringt einen eigenen Schritt mit: seine API in der Bibliothek einschalten.

1. In der Google Cloud Console ein Projekt anlegen oder ein bestehendes auswählen.
2. Unter „APIs & Services“ › „Library“ die API einschalten, die der Connector braucht (bei Google Docs die „Google Docs API“).
3. Unter „Google Auth Platform“ › „Branding“ auf „Get started“ klicken, App-Namen und Support-E-Mail eintragen. Bei „Audience“ „Internal“ wählen, wenn sich nur Konten Ihrer Google-Workspace-Organisation verbinden. „External“ gilt für alle anderen Konten. Solange die App im Testmodus ist, tragen Sie unter „Audience“ › „Test users“ jede Person ein, die sich verbinden soll.
4. Nur bei „External“: unter „Google Auth Platform“ › „Data Access“ › „Add or Remove Scopes“ die Berechtigungen von der Connector-Seite hinzufügen und speichern.
5. Unter „Google Auth Platform“ › „Clients“ einen Client vom Typ „Web application“ anlegen und bei „Authorized redirect URIs“ die Weiterleitungs-URI eintragen.
6. Client-ID und Client-Secret sofort kopieren. Google zeigt das Secret nur beim Anlegen vollständig an.
7. Beide Werte unter <Ui>Konfiguration</Ui> eintragen und speichern.

#### Atlassian

Eine App genügt für Jira Cloud und Confluence Cloud.

1. In der Atlassian Developer Console „Create“ › „OAuth 2.0 integration“ wählen und einen Namen vergeben.
2. Unter „Authorization“ neben „OAuth 2.0 (3LO)“ auf „Configure“ klicken, die Weiterleitungs-URI als „Callback URL“ eintragen und speichern.
3. Unter „Permissions“ die API des Connectors (Jira oder Confluence) hinzufügen und über „Configure“ ihre Berechtigungen ergänzen. Für beide dieselbe App verwenden und beide APIs hinzufügen.
4. Unter „Distribution“ „Enable sharing“ einschalten. Sonst kann nur die Person die App benutzen, die sie angelegt hat.
5. Unter „Settings“ die „Client ID“ und das „Secret“ kopieren und unter <Ui>Konfiguration</Ui> eintragen.

#### Weitere Anbieter

Auch für diese Anbieter zeigt die Connector-Seite eine Anleitung. Sie folgen alle demselben Muster: App in der Konsole anlegen, Weiterleitungs-URI eintragen, Berechtigungen hinzufügen, Client-ID und Secret unter <Ui>Konfiguration</Ui> eintragen.

| Anbieter | Wo Sie die App registrieren | Connectoren |
|---|---|---|
| Airtable | Airtable, OAuth integrations | Airtable |
| Asana | Asana Developer Console | Asana |
| Box | Box Developer Console | Box |
| Calendly | Calendly Developer | Calendly |
| Canva | Canva Developer Portal, Your apps | Canva |
| ClickUp | ClickUp, Settings, Apps | ClickUp |
| Close | Close, OAuth Apps | Close |
| Cloudflare | Cloudflare Dashboard, OAuth clients | Cloudflare |
| Dropbox | Dropbox App Console | Dropbox |
| GitHub | GitHub, Developer settings | GitHub |
| HubSpot | HubSpot, Development | HubSpot |
| Linear | Linear, Settings, API | Linear |
| Miro | Miro, Settings, Your apps | Miro |
| monday.com | monday.com Developer Center | monday.com |
| Notion | Notion Developer portal | Notion |
| Pipedrive | Pipedrive Developer Hub | Pipedrive |
| Salesforce | Salesforce Setup, App Manager | Salesforce |
| Slack | Slack API, Your Apps | Slack |
| Todoist | Todoist App Management Console | Todoist |
| Webex | Webex for Developers, My Webex Apps | Webex |
| Wrike | Wrike, Apps & Integrations | Wrike |
| Zoom | Zoom App Marketplace | Zoom |

GitLab hat keine eigene Anleitung. Seine Seite zeigt die allgemeinen OAuth-Schritte: in Ihrer GitLab-Instanz eine OAuth-Anwendung anlegen, die Weiterleitungs-URI eintragen, die Berechtigungen erlauben und Application-ID und Secret zusammen mit der Adresse Ihrer GitLab-Instanz unter <Ui>Konfiguration</Ui> eintragen.

### OAuth ohne App

Zapier meldet sich mit **automatischer Registrierung** an: Beim ersten Verbinden meldet sich nexxus selbst als App beim Anbieter an. <Ui>Einrichtung</Ui> sagt dazu <Ui>Nichts einzurichten: Beim ersten Verbinden meldet sich diese Anwendung selbst als App beim Anbieter an. Jede Person klickt nur auf „Verbinden“.</Ui>

### Client-ID und Secret für die Organisation

Personio und PayPal melden sich als App der Organisation an, nicht als Person. Tragen Sie Client-ID und Secret aus den API-Zugangsdaten des Anbieters unter <Ui>Konfiguration</Ui> ein. <Ui>Verbindung für alle</Ui> zeigt dann <Ui>Verbindet sich selbst mit Client-ID und Client-Secret aus der Konfiguration, beim ersten Aufruf.</Ui> Niemand muss etwas verbinden. Bei PayPal ergänzt die Connector-Seite eigene Schritte: Im PayPal Developer Dashboard muss für die REST-App „Transaction Search“ eingeschaltet sein, sonst lehnt PayPal das Auflisten von Transaktionen ab.

## So verbinden sich Ihre Nutzer

Nach der Einrichtung verbinden sich die Personen an einer von vier Stellen. Überall läuft dieselbe Anmeldung.

- Auf der Connector-Seite unter <Ui>Meine Verbindung</Ui>, dorthin führt der Link in Ihrer <Ui>Nachricht an Ihre Nutzer</Ui>.
- Im Chat: über die Karte <Ui>Verbindung fehlt</Ui>, wenn der KI-Assistent das Konto braucht, über den Knopf <Ui>Verbinden</Ui> im Connector-Menü oder über die Zeile <Ui>Konten verbinden</Ui> unter dem Eingabefeld einer neuen Unterhaltung.
- Unter <MenuPath to="Mein Profil > Verbundene Konten" />, Abschnitt <Ui>Weitere Konten verbinden</Ui>: eine Zeile je Anbieter mit den Connectoren, für die er gilt.
- Am Schreibtisch, der die Connectoren auflistet, die die Organisation für die Person eingerichtet hat, mit einem Klick je Anbieter.

Bei OAuth-Connectoren mit Berechtigungsgruppen sieht die Person zuerst <Ui>{'Was darf der Assistent bei {name}?'}</Ui> und hakt an, was sie freigeben will. Dann öffnet sich die Anmeldung des Anbieters in einem Pop-up. Nach der Anmeldung schließt es sich von selbst.

<Screenshot src={shot_plg_dlg_permissions} url="/plugins/outlook-mail" alt={"Die Auswahl der Berechtigungen vor dem Verbinden von Outlook E-Mail"} caption={"Nur die angehakten Gruppen werden beim Anbieter angefragt."} />

<MenuPath to="Mein Profil > Verbundene Konten" /> listet jedes Konto, das eine Person verbunden hat: den Anbieter, den Status (<Ui>Verbunden</Ui>, <Ui>Abgelaufen</Ui>, <Ui>Widerrufen</Ui>, <Ui>Fehler</Ui>), welche Connectoren es benutzen, welche Berechtigungen es hat und <Ui>{'Gültig bis {at}'}</Ui>. Gemeinsame Verbindungen erscheinen mit <Ui>Verbindung für alle in diesem Mandanten</Ui> und dem Namen der Person, die sie verbunden hat.

<Screenshot src={shot_plg_connected_apps} url="/profil/verbundene-apps" alt={"Die verbundenen Konten einer Person mit einer Verbindung und einem noch nicht verbundenen Connector"} caption={"Jede Verbindung zeigt, welche Connectoren sie benutzen. Darunter stehen die Connectoren, die noch Ihr Konto brauchen."} />

## Wenn jemand nach einem Connector fragt

Wer einen Connector vermisst, muss nicht wissen, wer der Administrator ist. Am Schreibtisch klickt die Person auf <Ui>Fehlt ein Connector? Admin fragen</Ui>, schreibt, was sie braucht (zum Beispiel „Jira für unsere Tickets“), und klickt auf <Ui>Fragen</Ui>. Alle, die Connectoren verwalten dürfen, bekommen einen Eintrag in der Glocke und, wenn sie es nicht abgeschaltet haben, eine E-Mail. Nach demselben Connector kann eine Person einmal am Tag fragen.

Ob die E-Mail kommt, legt jeder Administrator unter <MenuPath to="Mein Profil > Benachrichtigungen" /> fest: <Ui>E-Mail, wenn jemand um einen Connector bittet</Ui>.

## Systeme im eigenen Netz erreichen

Connectoren dürfen standardmäßig nur öffentliche Adressen über HTTPS aufrufen. Das schützt Ihr Netz: Wer einen Connector baut, tippt eine Adresse ein, und ohne diese Regel ließe sich der nexxus-Server auf interne Systeme richten. Soll ein Connector ein internes System bewusst erreichen, etwa Paperboi auf einem Server im Büronetz, geben Sie es frei.

<Steps>

1. Klicken Sie auf der Katalogseite in der Aktionsleiste auf <Ui>Einstellungen</Ui>. Es öffnet sich <Ui>Connector-Einstellungen</Ui>.

2. Tragen Sie unter <Ui>Netz-Freigabe</Ui> ein, was Sie freigeben:

   - <Ui>Adressbereiche (CIDR)</Ui>: einer pro Zeile, zum Beispiel `10.39.0.0/16`.
   - <Ui>Hostnamen</Ui>: einer pro Zeile, genau (`paperboi.intern.brandt.example`) oder mit `*.` davor für alle Unteradressen (`*.intern.brandt.example`).
   - <Ui>Unverschlüsseltes http:// für diese Ziele erlauben</Ui>: Interne Server haben oft kein Zertifikat. Öffentliche Adressen brauchen immer HTTPS.

3. Klicken Sie auf <Ui>Speichern</Ui>.

</Steps>

<Screenshot src={shot_plg_settings} url="/plugins/settings" alt={"Die Netz-Freigabe mit einem internen Adressbereich und Hostnamen"} caption={"Freigegebene Ziele dürfen Connectoren aufrufen, alles andere Interne bleibt gesperrt."} />

Die Freigabe erlaubt, sie verbindet nicht. Das Ziel muss trotzdem vom nexxus-Server aus erreichbar sein, durch Ihre Firewall oder Ihr VPN. Zwei Regeln lassen sich nicht abschalten: Metadaten-Adressen von Cloud-Anbietern bleiben gesperrt, und Weiterleitungen werden bei jedem Sprung neu geprüft. Eine öffentliche Adresse kann eine Anfrage so nicht in Ihr Netz umleiten.

## Prüfen, ob es funktioniert

Für Katalog-Connectoren gibt es keinen einzelnen Test-Knopf, denn ein Connector funktioniert nur mit einem echten Konto. So prüfen Sie es:

1. <Ui>Einrichtung</Ui> zeigt <Ui>{'{name} ist fertig eingerichtet'}</Ui>.
2. Verbinden Sie Ihr eigenes Konto, schalten Sie den Connector in einem Chat ein und fragen Sie den KI-Assistenten etwas, das nur liest, zum Beispiel „Zeig mir meine fünf neuesten Mails“.
3. Bei Connectoren mit Berechtigungsgruppen zeigt <Ui>Verbindung prüfen</Ui> unter <Ui>Berechtigungen</Ui>, welche Gruppen der Anbieter freigegeben hat.
4. <Ui>Letzte Aufrufe</Ui> listet jeden Aufruf mit <Ui>Zeitpunkt</Ui>, <Ui>Aktion</Ui>, <Ui>Person</Ui>, <Ui>Dauer</Ui> und <Ui>Ergebnis</Ui> (<Ui>Erfolgreich</Ui> oder <Ui>Fehler</Ui>, die Fehlermeldung steht im Tooltip). Oben auf der Seite steht die Zahl der Aufrufe der letzten 30 Tage.

Ihre eigenen MCP-Connectoren haben einen Test, siehe [Eigenen Connector bauen](/de/plugins/build/).

<Screenshot src={shot_plg_detail_calls} url="/plugins/paperboi" alt={"Die letzten Aufrufe von Paperboi mit erfolgreichen und fehlgeschlagenen Aufrufen"} caption={"Letzte Aufrufe zeigen, wer welche Aktion aufgerufen hat, ohne Inhalte."} />

## Was im Hintergrund passiert

- **Eine Verbindung je Anbieter und App.** nexxus speichert eine Verbindung zum Anbieter und zur Client-ID, für die die Tokens ausgestellt wurden. Connectoren desselben Anbieters mit derselben App teilen sie sich. Ein Connector mit einer anderen App bekommt eine eigene Verbindung und überschreibt nie die Tokens einer anderen App.
- **Nur das Fehlende anfragen.** Verbindet eine Person einen zweiten Connector desselben Anbieters, fragt die Anmeldung das bereits Freigegebene plus das an, was der neue Connector braucht. Die Zustimmungsseite des Anbieters zeigt nur den neuen Teil.
- **Tokens bleiben auf dem Server.** Tokens und Schlüssel liegen verschlüsselt mit dem geheimen Schlüssel der Installation und gehen nie an das KI-Gateway, das Modell oder den Browser. OAuth-Tokens erneuern sich eine Minute vor Ablauf, ein Hintergrundjob erneuert sie zusätzlich alle 10 Minuten vorab.
- **Jede Anmeldung gilt einmal.** Jede Anmeldung trägt einen Zufallswert, der 10 Minuten gilt und einmal benutzt wird. Abschließen kann sie nur die Person, die sie begonnen hat.
- **Trennen widerruft.** <Ui>Trennen</Ui> bittet den Anbieter, den Zugriff zu widerrufen, wo er das anbietet, und löscht danach die Tokens.
- **Deinstallieren behält Verbindungen.** Die Verbindungen der Personen bleiben bestehen und werden bei einer neuen Installation wieder benutzt.
- **Rechte gelten nach Sekunden.** nexxus prüft die Connector-Rechte bei jedem Aufruf und merkt sich die Antwort 5 Sekunden je Person.

## Wenn etwas nicht klappt

### Der Dialog bei Verbindungsfehlern

Scheitert eine Verbindung, öffnet nexxus einen Dialog statt einer kurzen Fehlermeldung. Er nennt den Grund als Titel, zeigt die Meldung des Anbieters in einem roten Kasten, die Schritte unter <Ui>So lösen Sie das</Ui> und für alle, die den Connector verwalten, die Schritte unter <Ui>Als Administrator</Ui> mit der Weiterleitungs-URI zum Kopieren. Alle anderen lesen <Ui>Das kann nur ein Administrator beheben. Schicken Sie ihm diese Meldung und versuchen Sie es danach erneut.</Ui> Unten stehen der <Ui>Fehlercode</Ui>, <Ui>Schließen</Ui>, <Ui>Erneut verbinden</Ui> und, wo es hilft, <Ui>Connector-Einstellungen öffnen</Ui>.

<Screenshot src={shot_plg_dlg_connect_error} url="/plugins/outlook-mail" alt={"Der Fehlerdialog, wenn keine OAuth-App eingerichtet ist"} caption={"Der Dialog erklärt den Fehler und die Lösung, mit der Weiterleitungs-URI zum Kopieren."} />

| Titel im Dialog | Fehlercode | Was zu tun ist |
|---|---|---|
| <Ui>{'Für {name} ist noch keine Anmeldung eingerichtet'}</Ui> | `OAUTH_APP_MISSING` | Administrator: in der Entwicklerkonsole des Anbieters eine OAuth-App anlegen, die Weiterleitungs-URI genau so eintragen, Client-ID und Client-Secret unter <Ui>Konfiguration</Ui> speichern. Microsoft-Connectoren nehmen die App eines anderen Microsoft-Connectors oder der Microsoft-Anmeldung, wenn es eine gibt. |
| <Ui>{'Der Entra-Mandant für {name} ist ungültig'}</Ui> | `OAUTH_TENANT_INVALID` | Administrator: <Ui>Entra-Mandant (Domain oder ID)</Ui> prüfen. Erwartet wird eine Domain wie firma.onmicrosoft.com oder die Verzeichnis-ID. Speichern und erneut verbinden. |
| <Ui>{'{name} lässt keine automatische Anmeldung zu'}</Ui> | `OAUTH_NO_REGISTRATION` | Administrator: Nimmt der Server auch einen API-Schlüssel oder Token an, den Connector auf eigene Header umstellen. Sonst den Betreiber bitten, die automatische Client-Registrierung freizuschalten. |
| <Ui>{'Die Anmeldung bei {name} ist abgelaufen'}</Ui> | `OAUTH_STATE_EXPIRED` | Auf <Ui>Erneut verbinden</Ui> klicken und die Anmeldung im neuen Fenster innerhalb von zehn Minuten abschließen. |
| <Ui>{'Die Anmeldung bei {name} gehört zu einer anderen Sitzung'}</Ui> | `OAUTH_OTHER_SESSION` | Prüfen, dass Sie in nexxus noch angemeldet sind und das Anmeldefenster im selben Browser geöffnet wurde. Dann erneut verbinden. |
| <Ui>{'Die Anmeldung bei {name} wurde abgelehnt'}</Ui> | `OAUTH_ACCESS_DENIED` | Erneut verbinden und die angefragten Berechtigungen bestätigen. Zeigt der Anbieter „Genehmigung durch Administrator erforderlich“, stimmt ein Administrator Ihrer Organisation der App zu: in Microsoft Entra unter Unternehmensanwendungen, in der Google-Admin-Konsole unter API-Steuerung. |
| <Ui>{'{name} hat die Anmeldung abgebrochen'}</Ui> | `OAUTH_PROVIDER_ERROR` | Die Meldung des Anbieters lesen. Administrator: prüfen, ob die Weiterleitungs-URI genau so eingetragen ist und die App die Berechtigungen des Connectors anfordern darf. |
| <Ui>{'Der Anbieter kennt die App von {name} nicht'}</Ui> | `OAUTH_CLIENT_INVALID` | Administrator: Client-ID und Secret mit der App beim Anbieter vergleichen. Client-Secrets laufen ab, bei Microsoft spätestens nach zwei Jahren. Die Weiterleitungs-URI prüfen. |
| <Ui>{'Der Server erreicht {name} nicht'}</Ui> | `OAUTH_UNREACHABLE` | In ein paar Minuten erneut verbinden. Bleibt der Fehler, Netz-Freigabe und Firewall des Servers prüfen. |
| <Ui>{'{name} hat die Anmeldung nicht bestätigt'}</Ui> | `OAUTH_TOKEN_FAILED` | Erneut verbinden. Administrator: die App beim Anbieter und die Konfiguration des Connectors prüfen. Die Meldung im Dialog nennt die Antwort des Anbieters. |
| <Ui>{'Das Anmeldefenster für {name} wurde blockiert'}</Ui> | `POPUP_BLOCKED` | In der Adressleiste auf das Symbol für blockierte Popups klicken, Popups für nexxus erlauben und erneut verbinden. |
| <Ui>{'{name} konnte nicht getrennt werden'}</Ui> | `DISCONNECT_FAILED` | Seite neu laden und noch einmal trennen. Bleibt der Fehler, die Meldung an einen Administrator schicken. |
| <Ui>{'Mit {name} hat es nicht geklappt'}</Ui> | `UNKNOWN` | Erneut versuchen. Bleibt der Fehler, die Meldung an einen Administrator schicken. |

Konnte das Pop-up nichts zurückmelden, etwa weil die Seite des Anbieters die Verbindung zu nexxus gekappt hat, fragt nexxus beim Server nach, was aus der Anmeldung geworden ist, und zeigt denselben Dialog.

### Weitere Meldungen

| Meldung | Bedeutung und Lösung |
|---|---|
| `Pflichtfelder fehlen: ...` | Pflichtfelder sind leer. Die genannten Felder ausfüllen. |
| `Client-Secret und Client-ID sind gleich. Beim Anbieter steht das Secret in einem eigenen Feld; bitte dieses eintragen.` | Meist hat ein Passwortmanager den falschen Wert eingesetzt. Das Secret aus seinem eigenen Feld beim Anbieter kopieren. |
| `... ist für den Mandanten noch nicht verbunden; das richtet ein Administrator auf der Connector-Seite ein.` | Der Connector arbeitet nur mit einer gemeinsamen Verbindung, und die fehlt. Unter <Ui>Verbindung für alle</Ui> verbinden. |
| `... steht Ihnen nicht zur Verfügung.` | Die Person darf den Connector nicht benutzen: <Ui>Nur für Rollen</Ui>, <Ui>Nur für Geschäftseinheiten</Ui> und das Recht `ai.plugin.use` prüfen. |
| `Keine Berechtigung (ai.plugin.connect).` | Der Person fehlt das Recht, ein Konto zu verbinden. `ai.plugin.connect` zu ihrer Rolle hinzufügen. |
| `Die Anmeldung ist abgelaufen. Bitte neu verbinden.` | Der Anbieter nimmt den Token nicht mehr an. Die Person klickt auf <Ui>Neu verbinden</Ui>. |
| `...: Ziel gesperrt: ...` | Die Netzregeln haben einen Aufruf gesperrt. Das Ziel unter <Ui>Netz-Freigabe</Ui> freigeben oder HTTPS verwenden. |
| `Verbindung fehlgeschlagen` im Pop-up | Die Anmeldung ist gescheitert, und das Pop-up konnte nexxus nicht Bescheid geben. Das Pop-up nennt den Grund. Mit „Fenster schließen“ schließen und erneut verbinden. |

## Nächste Schritte

<CardGrid>
  <LinkCard title="Connector-Katalog" description="Jeder Connector, der mit nexxus kommt, und wie er sich anmeldet." href="/de/plugins/catalog/" />
  <LinkCard title="Eigenen Connector bauen" description="Ihren eigenen MCP-Server oder Ihre Schnittstelle anbinden, mit Verbindungstest." href="/de/plugins/build/" />
  <LinkCard title="Rollen" description="Personen die Connector-Rechte geben, die sie brauchen." href="/de/setup/roles/" />
</CardGrid>