# Anmeldung und OAuth

> Wie sich Personen bei nexxus anmelden und was „OAuth“ hier alles bedeuten kann. Mit der vollständigen Anleitung zur Anmeldung über Microsoft Entra ID samt exakter Umleitungs-URI, der Umleitungs-URI für Connectoren, KI-Clients wie Claude Code, nexxus als Identitätsanbieter für andere Anwendungen und dem, was nicht unterstützt wird.

Personen melden sich bei nexxus mit einem Passwort an, mit einem Einmal-Link per E-Mail oder mit ihrem Microsoft-Konto. Welche Wege Ihr Team nutzt, entscheiden Sie. Arbeitet Ihr Unternehmen schon mit Microsoft 365, erspart die Microsoft-Anmeldung allen ein eigenes Passwort, und neue Kolleginnen und Kollegen bekommen ihr Konto beim ersten Klick.

Das Wort „OAuth“ taucht in nexxus an mehreren Stellen auf und meint jedes Mal etwas anderes. Diese Seite ordnet das und führt dann Schritt für Schritt durch die Einrichtung mit Microsoft.

## Wie sich Personen anmelden

<Screenshot src={shot_signin_login_page} url="/login" alt={"Die Anmeldeseite mit Passwortformular und Anmelde-Link"} caption={"Die Schaltfläche für die Microsoft-Anmeldung erscheint, sobald die Microsoft-Anmeldung eingerichtet ist."} />

| Weg | Was die Person tut | Eingerichtet von |
|---|---|---|
| **Passwort** | Gibt Benutzername und Passwort ein, auf Wunsch mit Haken bei <Ui>Angemeldet bleiben</Ui> | Nichts einzurichten. Das Passwort kommt aus der [Einladung](/de/setup/invite-users/) |
| **Anmelde-Link per E-Mail** | Klickt auf <Ui>Anmelde-Link per E-Mail</Ui>, gibt die E-Mail-Adresse ein und öffnet den Link | Funktioniert, sobald der Mailversand eingerichtet ist |
| **Microsoft** | Klickt auf <Ui>Mit Microsoft anmelden</Ui> | Ein Administrator, einmalig, [wie unten beschrieben](#anmeldung-mit-microsoft-entra-id) |

Alle drei Wege führen zur selben Art von Sitzung mit denselben Rollen. Hat das Konto eine Authenticator-App, fragt nexxus nach dem Passwort und nach dem Anmelde-Link deren Code ab. Bei Microsoft-Anmeldungen überlässt nexxus die Mehr-Faktor-Authentifizierung Microsoft. Codes, gemerkte Browser und Sitzungen erklärt [Sicherheit](/de/setup/security/).

:::note[Benutzername, nicht E-Mail]
Das erste Feld der Anmeldung heißt <Ui>E-Mail-Adresse</Ui>, nexxus sucht das Konto aber über den **Benutzernamen**. Bei Sammeleinladungen und bei Konten aus einer Microsoft-Anmeldung ist der Benutzername die E-Mail-Adresse, dort geht beides. Alle anderen geben den Benutzernamen ein.
:::

Skripte und Werkzeuge melden sich ohne Browser an, mit einem persönlichen API-Token. Siehe [Sicherheit](/de/setup/security/#persönliche-api-tokens).

## Fünf Dinge, die OAuth heißen

<Hub
  inputsLabel="Anmeldung bei nexxus"
  inputs={[
    { icon: 'log-in', title: 'Mit Microsoft anmelden', text: 'Ihr Entra ID bestätigt, wer die Person ist' },
    { icon: 'bot', title: 'KI-Clients (MCP)', text: 'Claude Code und andere MCP-Clients arbeiten als die Person' },
  ]}
  core={{
    title: 'nexxus',
    text: 'Ein Backend, eine öffentliche Adresse',
    items: ['/api/entra/code', '/api/plugins/oauth/callback', '/oauth2', '/api/mcp'],
  }}
  outputsLabel="nexxus meldet sich woanders an"
  outputs={[
    { icon: 'plug-zap', title: 'Connector-Verbindungen', text: 'Der KI-Assistent handelt in Microsoft 365, Google, Slack mit dem Konto der Person' },
    { icon: 'cable', title: 'MCP-Connectoren mit OAuth', text: 'Externe MCP-Server, die selbst anmelden' },
    { icon: 'app-window', title: 'Andere Anwendungen', text: 'Anmeldung mit dem nexxus-Konto (nur per API)' },
  ]}
  caption="Jede der fünf hat ihre eigene Adresse. Nur für die Anmeldung mit Microsoft und für Connector-Verbindungen registrieren Sie selbst eine App."
/>

| Bedeutung | Was sie tut | Wo Sie sie einrichten | Adresse, die Sie eintragen |
|---|---|---|---|
| **Anmeldung mit Microsoft** | Personen melden sich mit ihrem Microsoft-Konto bei nexxus an | <MenuPath to="Administration > Betrieb > Einrichtung" />, Schritt <Ui>Microsoft Entra</Ui>, oder die Systemkonfiguration | `https://<Ihre nexxus-Adresse>/api/entra/code` |
| **Connector-Verbindungen** | Der KI-Assistent arbeitet mit dem eigenen Konto der Person in einem anderen Dienst | <MenuPath to="KI > KI einrichten > Connectoren" />, auf der Seite des Connectors | `https://<Ihre nexxus-Adresse>/api/plugins/oauth/callback` |
| **MCP-Connectoren mit OAuth** | Der KI-Assistent nutzt einen externen MCP-Server, der selbst anmeldet | <MenuPath to="KI > KI einrichten > Connectoren" />, Reiter <Ui>Meine Connectoren</Ui> | Nichts: nexxus registriert sich selbst beim Server |
| **nexxus als Identitätsanbieter** | Eine andere Anwendung lässt Personen sich mit ihrem nexxus-Konto anmelden | Nur per API, keine Seite in der Anwendung | Die eigene Umleitungs-URI der anderen Anwendung, eingetragen in nexxus |
| **KI-Clients (MCP)** | Claude Code oder ein anderer MCP-Client arbeitet in nexxus als die angemeldete Person | <MenuPath to="Administration > Betrieb > Systemkonfiguration" />, danach jede Person unter <MenuPath to="Mein Profil > KI-Clients" /> | Nichts: der Client registriert sich selbst bei nexxus |

`<Ihre nexxus-Adresse>` ist die öffentliche Adresse des nexxus-Backends. Bei den meisten Installationen teilen sich Anwendung und Backend eine Adresse, etwa `https://nexxus.example.com`. Der Einrichtungsschritt und die Connector-Seite zeigen den genauen Wert mit einem Knopf <Ui>Kopieren</Ui>, Sie müssen ihn also nie abtippen.

## Anmeldung mit Microsoft (Entra ID)

Mit der Microsoft-Anmeldung zeigt die Anmeldeseite einen Knopf <Ui>Mit Microsoft anmelden</Ui>. Die Person meldet sich bei Microsoft an, wie sie es von Outlook oder Teams kennt, kommt zu nexxus zurück und ist angemeldet. Kennt nexxus die Person noch nicht, legt es das Konto sofort an, mit der Standardrolle aus Ihrer Einrichtung.

<Flow
  steps={[
    { icon: 'mouse-pointer-click', title: 'Klick', text: 'Mit Microsoft anmelden auf der Anmeldeseite von nexxus.' },
    { icon: 'log-in', title: 'Microsoft', text: 'Die Person meldet sich bei Microsoft an, mit MFA, wenn Ihr Verzeichnis sie verlangt.', tone: 'cyan' },
    { icon: 'user-round-check', title: 'nexxus findet das Konto', text: 'Über die Microsoft-Identität, dann über die E-Mail-Adresse, oder legt ein neues an.', tone: 'lavender' },
    { icon: 'circle-check-big', title: 'Angemeldet', text: 'Mit den Rollen aus nexxus. Microsoft sagt nur, wer die Person ist.' },
  ]}
  caption="Die Rechte bleiben in nexxus. Das Verzeichnis beantwortet, wer jemand ist, nie, was er darf."
/>

### Bevor Sie anfangen

- Sie haben in nexxus die Systemrolle ADMIN.
- Jemand darf in Ihrem Microsoft-Entra-Verzeichnis eine Anwendung registrieren. Meist ist das Ihre IT. Sie braucht von Ihnen einen Wert (die Umleitungs-URI) und gibt Ihnen drei Werte zurück.
- Sie kennen die öffentliche Adresse von nexxus. Der Einrichtungsschritt zeigt die daraus gebildete Umleitungs-URI.
- Ihre Installation hat einen Mandanten. Bei mehreren Mandanten bietet die Anmeldeseite die Microsoft-Anmeldung nicht an.

### Schritt 1: App in Microsoft Entra registrieren

Diese Schritte erledigen Sie im Microsoft Entra Admin Center, dessen Menüs englisch sind.

<Steps>

1. Öffnen Sie das Microsoft Entra Admin Center unter `https://entra.microsoft.com` und gehen Sie zu **Entra ID** › **App registrations** › **New registration**. Geben Sie der App einen Namen, den Ihre Leute wiedererkennen, etwa „nexxus“. Wählen Sie unter **Supported account types** die Option **Single tenant only**.

2. Öffnen Sie in der neuen App **Authentication** › **Add Redirect URI**, wählen Sie die Plattform **Web** und tragen Sie die Umleitungs-URI ein:

   ```text
   https://<Ihre nexxus-Adresse>/api/entra/code
   ```

   Sie muss genau übereinstimmen, mit `https` und ohne Schrägstrich am Ende. Kopieren Sie sie am besten aus dem Einrichtungsschritt in nexxus (Schritt 2).

3. Öffnen Sie **API permissions**. nexxus braucht die delegierte Microsoft-Graph-Berechtigung **User.Read**, die das eigene Profil der angemeldeten Person liest. Fehlt sie in der Liste, fügen Sie sie unter **Add a permission** › **Microsoft Graph** › **Delegated permissions** hinzu.

4. Öffnen Sie **Certificates & secrets** › **Client secrets** › **New client secret**. Kopieren Sie den **Value** sofort: Microsoft zeigt ihn nur einmal. Notieren Sie das Ablaufdatum. Secrets laufen nach höchstens 24 Monaten ab, und dann funktioniert die Anmeldung nicht mehr.

5. Kopieren Sie auf der Seite **Overview** die **Application (client) ID** und die **Directory (tenant) ID**.

</Steps>

:::tip[Eine App für Anmeldung und Microsoft-Connectoren]
Die Microsoft-Connectoren (Outlook, Teams, SharePoint, OneDrive und andere) können diese App mitbenutzen. Tragen Sie die Connector-Umleitungs-URI `https://<Ihre nexxus-Adresse>/api/plugins/oauth/callback` als zweite **Web**-Umleitungs-URI in dieselbe App ein und lassen Sie beim Einrichten des Connectors die Client-ID leer. Siehe [Einen Connector einrichten](/de/plugins/set-up/).
:::

### Schritt 2: Werte in nexxus eintragen

<Screenshot src={shot_signin_entra_setup} url="/einrichtung" alt={"Der Einrichtungsschritt für die Microsoft-Anmeldung mit Beispielwerten"} caption={"Ausgefüllt, vor dem Test."} />

<Steps>

1. Öffnen Sie <MenuPath to="Administration > Betrieb > Einrichtung" /> und wählen Sie den Schritt <Ui>Microsoft Entra</Ui>. Die Seite heißt <Ui>Anmeldung mit Microsoft</Ui>.

2. Tragen Sie in der Karte <Ui>App-Registrierung in Entra</Ui> die drei Werte von Microsoft ein:

   | Feld in nexxus | Wert von Microsoft |
   |---|---|
   | <Ui>Verzeichnis-ID (Tenant)</Ui> | Directory (tenant) ID |
   | <Ui>Anwendungs-ID (Client)</Ui> | Application (client) ID |
   | <Ui>Geheimer Clientschlüssel</Ui> | Der Value des Client Secrets |

   Der Schlüssel <Ui>Wird verschlüsselt gespeichert und nie wieder angezeigt.</Ui> Nach dem Speichern bleibt das Feld leer: lassen Sie es leer, um den gespeicherten Schlüssel zu behalten.

3. Prüfen Sie <Ui>Umleitungs-URI, in Entra eintragen</Ui>. nexxus füllt sie aus seiner eigenen Adresse. Sie muss mit der Umleitungs-URI in der Microsoft-App identisch sein. Mit <Ui>Kopieren</Ui> geben Sie sie weiter.

4. Klicken Sie auf <Ui>Verbindung testen</Ui>. nexxus fragt bei Microsoft, ob es das Verzeichnis gibt und ob die App mit diesem Schlüssel ein Token bekommt. Drei Prüfungen erscheinen:

   | Prüfung | Gutes Ergebnis | Wenn sie scheitert |
   |---|---|---|
   | <Ui>Angaben</Ui> | | „Verzeichnis-ID, Anwendungs-ID und Geheimnis müssen gespeichert sein.“ |
   | <Ui>Verzeichnis</Ui> | „Verzeichnis gefunden.“ | „Microsoft kennt diese Verzeichnis-ID nicht.“ |
   | <Ui>Anwendung und Geheimnis</Ui> | „Anwendung und Geheimnis angenommen.“ | Die Fehlerbeschreibung von Microsoft, etwa bei einem falschen oder abgelaufenen Schlüssel |

5. Klicken Sie auf <Ui>Speichern</Ui>. Die Meldung <Ui>Anmeldung mit Microsoft gespeichert</Ui> bestätigt es. Das Speichern hier schaltet auch den Knopf auf der Anmeldeseite ein.

</Steps>

Nutzen Sie kein Microsoft 365, wählen Sie unter <Ui>Später erinnern</Ui> die Option <Ui>Nicht benötigt</Ui>. Der Schritt verschwindet, und Einladungen und der Anmelde-Link per E-Mail genügen Ihrem Team.

### Schritt 3: Feinheiten in der Systemkonfiguration

Dieselben Einstellungen und zwei weitere finden Sie unter <MenuPath to="Administration > Betrieb > Systemkonfiguration" />, Abschnitt <Ui>Microsoft Entra ID Anmeldung</Ui>. Änderungen gelten sofort, ohne Deployment.

<Screenshot src={shot_signin_entra_sysconfig} url="/system-config" alt={"Die Einstellungen der Microsoft-Anmeldung in der Systemkonfiguration"} />

| Feld | Bedeutung |
|---|---|
| <Ui>„Login via Microsoft“ anzeigen</Ui> | Schaltet den Knopf ein oder aus (<Ui>Wird angezeigt</Ui> / <Ui>Ausgeblendet</Ui>). Aus heißt, der Server liefert gar keine Anmeldeadresse mehr. |
| <Ui>Verzeichnis-ID (Tenant)</Ui>, <Ui>Anwendungs-ID (Client)</Ui>, <Ui>Client-Secret</Ui> | Wie im Einrichtungsschritt. <Ui>Gespeichertes Secret entfernen</Ui> löscht den gespeicherten Schlüssel beim nächsten Speichern. |
| <Ui>Redirect-URI (Callback)</Ui> | <Ui>Muss exakt so in der App-Registrierung des Kunden als Redirect-URI hinterlegt sein.</Ui> |
| <Ui>Ziel nach der Anmeldung</Ui> | Wohin der Browser nach einer erfolgreichen Anmeldung geht. Leer heißt: die Adresse der Anwendung. |
| <Ui>Rolle für neue Konten</Ui> | Die Systemrolle, die Konten aus einer Microsoft-Anmeldung bekommen. STAFF, solange Sie nichts ändern. Sie muss existieren. |

Ist der Knopf eingeschaltet, fehlen aber Verzeichnis-ID, Anwendungs-ID oder Redirect-URI, warnt die Seite, und der Knopf bleibt ausgeblendet, bis alle drei gesetzt sind.

### Schritt 4: Ausprobieren

Melden Sie sich ab oder öffnen Sie ein privates Browserfenster und gehen Sie zur Anmeldeseite. Unter dem Passwortformular steht <Ui>Mit Microsoft anmelden</Ui>. Melden Sie sich mit einem Microsoft-Konto Ihres Verzeichnisses an. Sie landen in nexxus, und der Reiter <Ui>Aktivität</Ui> der Person verzeichnet die Anmeldung <Ui>über Microsoft</Ui>.

### Wer ein Konto bekommt

Bei jeder Microsoft-Anmeldung sucht nexxus das passende Konto in dieser Reihenfolge:

1. **Über die Microsoft-Identität.** Ein Konto, das sich schon einmal mit Microsoft angemeldet hat, findet nexxus über seine Microsoft-Objekt-ID.
2. **Über die Adresse.** Sonst vergleicht nexxus die Microsoft-Adresse (das Feld `mail` oder den User Principal Name) mit den Benutzernamen und dann mit den E-Mail-Adressen vorhandener Konten. Eine Person, die Sie vorher eingeladen haben, wird so mit ihrer Microsoft-Identität verbunden, ohne zweites Konto.
3. **Neues Konto.** Passt nichts, legt nexxus ein Konto an: Benutzername ist der User Principal Name, die Namen kommen von Microsoft, es bekommt die Systemrolle aus <Ui>Rolle für neue Konten</Ui> und mandantenweit die Standardrolle aus der Einrichtung. Ein nutzbares Passwort hat es nicht; die Person meldet sich immer über Microsoft an.

Jede Person Ihres Verzeichnisses, die sich bei dieser App anmelden darf, bekommt bei der ersten Anmeldung ein Konto. Wenn nur bestimmte Personen die Microsoft-Anmeldung nutzen sollen, schränken Sie in Microsoft Entra ein, wer die App verwenden darf.

Das Konto bleibt ein gewöhnliches nexxus-Konto. Rollen vergeben Sie wie gewohnt in nexxus (siehe [Rollen und Rechte](/de/setup/roles/)). Standardmäßig merkt sich der Browser eine Microsoft-Anmeldung 30 Tage, sodass sich niemand jeden Morgen neu anmelden muss.

### Zwei-Faktor-Authentifizierung mit Microsoft

Bei Microsoft-Anmeldungen fragt nexxus keinen eigenen Authenticator-Code ab. Die Mehr-Faktor-Authentifizierung für diese Anmeldungen richten Sie in Microsoft Entra ein, wo Ihre IT sie für Outlook und Teams ohnehin verwaltet.

Eine Regel gilt trotzdem: Steht eine Rolle in der <Ui>Zwei-Faktor-Pflicht</Ui> und hat das Konto noch keine Authenticator-App, führt nexxus die Person nach der Microsoft-Anmeldung durch deren Einrichtung. Siehe [Sicherheit](/de/setup/security/#zwei-faktor-pflicht-je-rolle).

### Wenn die Microsoft-Anmeldung scheitert

Fehler auf dem Rückweg von Microsoft erscheinen als kurze englische Texte im Browser.

| Was Sie sehen | Ursache und Abhilfe |
|---|---|
| Kein Knopf <Ui>Mit Microsoft anmelden</Ui> | Der Schalter <Ui>„Login via Microsoft“ anzeigen</Ui> ist aus, oder Verzeichnis-ID, Anwendungs-ID oder Redirect-URI fehlen. Bei Installationen mit mehreren Mandanten wird der Knopf nicht angeboten. |
| Microsoft meldet, dass die Umleitungs-URI nicht passt | Die Umleitungs-URI in der Microsoft-App weicht von der in nexxus ab. Kopieren Sie sie erneut aus nexxus und tragen Sie sie genau so ein. |
| `Token exchange with Microsoft failed` | Der Client-Secret ist falsch oder abgelaufen. Legen Sie bei Microsoft einen neuen an und tragen Sie ihn in nexxus ein. |
| `Could not load the Microsoft profile` | nexxus konnte das Profil der Person nicht aus Microsoft Graph lesen. Prüfen Sie, ob die App die delegierte Berechtigung User.Read hat. |
| `Sign-in could not be mapped to an account` | Die Adresse gehört zu einem nexxus-Konto, das schon mit einer anderen Microsoft-Identität verbunden ist, oder die Rolle unter <Ui>Rolle für neue Konten</Ui> existiert nicht. |
| `Invalid state` | Die Anmeldung wurde in einem anderen Browser begonnen, oder der Browser hat unterwegs seine Sitzung verloren, etwa weil Cookies gelöscht wurden. Beginnen Sie neu auf der Anmeldeseite. |
| Bei Microsoft abgebrochen | nexxus kehrt zur Anmeldeseite zurück. Als Fehler wird nichts verbucht. |

## Connector-Verbindungen

Mit einem Connector arbeitet der KI-Assistent in einem anderen Dienst, liest etwa Mails in Outlook oder schreibt in Slack, und zwar mit dem Konto der Person, die fragt. Die Person verbindet ihr Konto einmal per OAuth; nexxus bewahrt die Tokens verschlüsselt auf und gibt sie nie an das KI-Modell weiter.

Dafür registrieren Sie einmal eine App beim Anbieter, mit **einer Umleitungs-URI für alle Connectoren und Anbieter**:

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

Die Connector-Seite zeigt sie unter <Ui>Einrichtung</Ui> als <Ui>Weiterleitungs-URI (in der App des Anbieters eintragen)</Ui>, zusammen mit einer Schritt-für-Schritt-Anleitung für den Anbieter und den Berechtigungen, die die App erlauben muss. Einen Connector installieren und seine Client-ID und sein Secret eintragen braucht den Schlüssel `ai.plugin.admin`, das eigene Konto verbinden das Recht <Ui>Eigenes Konto verbinden</Ui> (`ai.plugin.connect`).

Die vollständige Anleitung je Connector, auch für die Apps bei Microsoft, Google und Slack, steht unter [Einen Connector einrichten](/de/plugins/set-up/).

## MCP-Connectoren mit OAuth

Manche MCP-Server melden Personen selbst per OAuth an. Wenn Sie einen solchen Server unter <Ui>Meine Connectoren</Ui> › <Ui>Neu</Ui> › <Ui>MCP-Connector</Ui> hinzufügen, wählen Sie unter <Ui>Anmeldung</Ui> die Option <Ui>OAuth (dynamische Registrierung)</Ui>. Von Hand ist nichts zu registrieren: bei der ersten Verbindung findet nexxus den Anmeldedienst des Servers, registriert sich dort als Anwendung „Nexxus“ und führt die Person durch die Anmeldung des Servers. Die Umleitungs-URI ist dieselbe `/api/plugins/oauth/callback`.

## KI-Clients wie Claude Code

nexxus ist ein MCP-Server. Claude Code, claude.ai und andere MCP-Clients verbinden sich mit `https://<Ihre nexxus-Adresse>/api/mcp`, melden die Person per OAuth an und arbeiten danach mit deren Rechten. Eine Administratorin oder ein Administrator erlaubt das einmal für die Organisation, jede Person verbindet ihren eigenen Client. Die ganze Anleitung steht unter [Claude Code verbinden](/de/mcp/connect/).

## nexxus als Identitätsanbieter für andere Anwendungen

nexxus kann die Anmeldung für andere Anwendungen Ihres Unternehmens übernehmen, über Standard-OpenID-Connect (Authorization Code Flow, mit PKCE für Browser- und Mobil-Apps). Wer schon bei nexxus angemeldet ist, kommt direkt durch, ohne das Passwort erneut einzugeben.

:::note[Nur per API]
Dafür gibt es keine Seite in der Anwendung. Anwendungen registrieren Sie als Administrator über die REST-API.
:::

### Endpunkte

| Endpunkt | Zweck |
|---|---|
| `/.well-known/openid-configuration` | Discovery-Dokument. Darauf zeigen Sie die andere Anwendung. |
| `/oauth2/authorize` | Startet die Anmeldung |
| `/oauth2/token` | Tauscht den Code gegen Tokens |
| `/oauth2/jwks` | Öffentliche Schlüssel zur Prüfung der Token-Signatur (RS256) |
| `/userinfo` | Profil der angemeldeten Person |
| `/connect/logout` | Abmeldung, ausgelöst von der anderen Anwendung |
| `/oauth2/consent` | Die Zustimmungsseite, wenn die Anwendung um Zustimmung bittet (`requireConsent`) |
| `/oauth2/register` | Selbstregistrierung (RFC 7591), nur für [KI-Clients](/de/mcp/connect/). Eigene Anwendungen registrieren Sie über die API unten. |

Wer bei nexxus noch nicht angemeldet ist, kommt auf die normale Anmeldeseite von nexxus und danach zurück zur anfragenden Anwendung. Die Anmeldung läuft wie überall sonst: mit dem Code aus der Authenticator-App, dem Anmelde-Link oder Microsoft.

Die Zustimmungsseite kommt vom Server. Sie nennt die Anwendung, das Konto, als das sie sich anmeldet, und was sie sehen darf, etwa „Ihre E-Mail-Adresse sehen“. <Ui>Verbinden</Ui> stimmt zu, <Ui>Abbrechen</Ui> lehnt ab.

### Eine Anwendung registrieren

Rufen Sie die API als Administrator auf, zum Beispiel mit dem [API-Token](/de/setup/security/#persönliche-api-tokens) eines Administrators:

```bash
curl -X POST "https://<Ihre nexxus-Adresse>/api/sso-client/" \
  -H "Authorization: Bearer cx_..." \
  -H "Content-Type: application/json" \
  -d '{
        "name": "Wiki",
        "redirectUris": "https://wiki.example.com/oauth/callback",
        "scopes": "openid,profile,email"
      }'
```

Die Antwort enthält die erzeugte `clientId` (beginnt mit `sso_`) und bei vertraulichen Clients das Secret in `generatedClientSecret`. Das Secret steht **nur in dieser Antwort**; nexxus speichert einen Hash. Ein neues erzeugen Sie später so:

```bash
curl -X POST "https://<Ihre nexxus-Adresse>/api/sso-client/action/regenerateSecret" \
  -H "Authorization: Bearer cx_..." -H "Content-Type: application/json" \
  -d '{"id": 3}'
```

| Feld | Typ | Pflicht | Bedeutung |
|---|---|---|---|
| `name` | String | ja | Name der Anwendung |
| `redirectUris` | String | ja, außer der Client nutzt nur Client Credentials | Erlaubte Umleitungs-URIs, eine pro Zeile, exakter Vergleich |
| `clientId` | String | nein | Wird erzeugt, wenn leer (`sso_` plus 24 Zeichen). Später nicht änderbar. |
| `postLogoutRedirectUris` | String | nein | Wohin die andere Anwendung Personen nach der Abmeldung schicken darf, eine pro Zeile |
| `scopes` | String | nein | Durch Kommas getrennt. Standard `openid,profile,email` |
| `publicClient` | Boolean | nein | `true` für Browser- und Mobil-Apps: kein Secret, PKCE Pflicht. Standard `false` |
| `requireConsent` | Boolean | nein | Fragt die Person bei der ersten Anmeldung nach ihrer Zustimmung. Standard `false` |
| `allowClientCredentials` | Boolean | nein | Erlaubt zusätzlich Maschine-zu-Maschine-Tokens (nur vertrauliche Clients). Standard `false` |
| `enabled` | Boolean | nein | Standard `true`. Ein abgeschalteter Client meldet niemanden an. |
| `accessTokenTtlSeconds` | Zahl | nein | Lebensdauer der Access Tokens. Standard 900 (15 Minuten) |
| `refreshTokenTtlSeconds` | Zahl | nein | Lebensdauer der Refresh Tokens. Standard 2592000 (30 Tage). Jedes Auffrischen stellt ein neues Refresh Token aus. |
| `description` | String | nein | Freitext |

Vertrauliche Clients weisen sich am Token-Endpunkt mit `client_secret_basic` oder `client_secret_post` aus.

### Was in den Tokens steht

Das ID-Token enthält diese Claims. `/userinfo` gibt davon nur die OpenID-Standardclaims der angefragten Scopes zurück (`sub`, E-Mail, Namen, `preferred_username`).

| Claim | Scope | Wert |
|---|---|---|
| `sub` | immer | Der Benutzername. Nach dem Löschen eines Kontos kann er an ein neues Konto gehen. |
| `user_id` | immer | Die Kennung der Person in nexxus. Sie wird nie neu vergeben: Verknüpfen Sie Konten Ihrer Anwendung damit, nicht mit `sub`. |
| `amr` | immer, wenn bekannt | Wie die Sitzung angemeldet wurde ([RFC 8176](https://www.rfc-editor.org/rfc/rfc8176)): `pwd` Passwort, `otp` Code aus der Authenticator-App, `swk` Browser, auf dem der Code in den letzten 30 Tagen eingegeben wurde, `email` Anmelde-Link, `fed` Microsoft, `mfa` zwei Faktoren. Fehlt bei einer Sitzung aus <Ui>Angemeldet bleiben</Ui> und während jemand als eine andere Person arbeitet. |
| `auth_time` | mit `amr` | Wann die Sitzung angemeldet wurde, in Sekunden seit 1970 |
| `preferred_username` | immer | Der Benutzername in nexxus |
| `email`, `email_verified` | `email` | E-Mail-Adresse und ob sie bestätigt ist |
| `name`, `given_name`, `family_name` | `profile` | Namen |
| `roles` | `profile` | Die Systemrollen der Person |
| `tenant_id` | `profile` | Der Mandant der Person |

## Was nicht unterstützt wird

- **Andere Identitätsanbieter für die nexxus-Anmeldung.** Google, Okta, Keycloak oder ein anderer OpenID-Connect-Anbieter lassen sich für die Anmeldung bei nexxus nicht verwenden. Microsoft Entra ID ist die einzige externe Anmeldung.
- **SAML** wird in keiner Richtung unterstützt.
- **SCIM** oder eine andere automatische Übernahme aus einem Verzeichnis. Konten entstehen durch Einladung, direktes Anlegen oder die erste Microsoft-Anmeldung.
- **Selbstregistrierung.** <Ui>Noch kein Konto?</Ui> <Ui>Administrator kontaktieren</Ui> auf der Anmeldeseite öffnet kein Registrierungsformular. Jedes Konto legt ein Administrator an.
- **Anwendungen für nexxus als Identitätsanbieter in der Anwendung registrieren.** Das geht nur per API, wie oben beschrieben.

## Was im Hintergrund passiert

<Sequence
  actors={[
    { name: 'Browser', icon: 'monitor' },
    { name: 'nexxus', icon: 'server' },
    { name: 'Microsoft Entra', icon: 'key-round' },
    { name: 'Microsoft Graph', icon: 'contact' },
  ]}
  steps={[
    { from: 0, to: 1, label: 'Klick auf „Mit Microsoft anmelden“' },
    { from: 0, to: 2, label: 'Weiter zur Microsoft-Anmeldung, mit PKCE-Challenge' },
    { from: 2, to: 2, label: 'Die Person meldet sich an, bei Bedarf mit MFA' },
    { from: 2, to: 1, label: 'Zurück an /api/entra/code mit einem Einmal-Code' },
    { from: 1, to: 2, label: 'Code eintauschen, mit Client-Geheimnis und PKCE-Verifier' },
    { from: 1, to: 3, label: 'Profil der Person lesen' },
    { from: 1, to: 1, label: 'Konto finden oder anlegen' },
    { from: 1, to: 0, label: 'Bei nexxus angemeldet' },
  ]}
  caption="Der Code-Tausch läuft zwischen den Servern. Der Browser sieht das Client-Geheimnis nie, und nexxus behält keine Tokens von Microsoft."
/>

- **Die Microsoft-Anmeldung** nutzt den Authorization Code Flow mit PKCE. nexxus tauscht den Code auf dem Server mit dem Client-Secret ein und liest dann das Profil der Person aus Microsoft Graph. Die Tokens von Microsoft behält nexxus nicht.
- **Das Client-Secret** der Entra-App liegt verschlüsselt mit dem Geheimnisschlüssel der Installation und wird nur für den Tausch entschlüsselt.
- **Der Anmeldeknopf** erscheint nur, wenn der Server der Anmeldeseite eine Microsoft-Anmeldeadresse liefert. Das tut er, wenn der Schalter an ist und Verzeichnis-ID, Anwendungs-ID und Redirect-URI gesetzt sind.
- **Der Identitätsanbieter** signiert seine Tokens mit einem RSA-Schlüssel (RS256). Die angemeldete nexxus-Sitzung ist die Single-Sign-on-Sitzung: wer in der nexxus-Anwendung angemeldet ist, kommt ohne neue Anmeldung durch, und wer sich auf dem Weg zu einer anderen Anwendung anmeldet, ist danach auch in der nexxus-Anwendung angemeldet.
- **Autorisierungen** (der Vermerk, dass eine Person einer Anwendung zugestimmt hat, samt deren Refresh-Tokens) liegen in der Datenbank. nexxus speichert jeden Token-Wert nur als SHA-256-Prüfsumme, ein Abzug der Datenbank enthält also kein brauchbares Token.

:::note[Für Selbstbetreiber]
| Einstellung | Zweck |
|---|---|
| `NEXXUS_SSO_ISSUER` | Die öffentliche HTTPS-Adresse des Backends. Sie ist das `iss` der Tokens des Identitätsanbieters, die Basis der Connector-Umleitungs-URI und die Basis der MCP-Adresse (`/api/mcp`). Setzen Sie sie in jeder ausgerollten Installation; leer leitet nexxus sie aus der eingehenden Anfrage ab. |
| `NEXXUS_SSO_RSA_PRIVATE_KEY` | RSA-Signaturschlüssel für den Identitätsanbieter, PKCS#8 PEM (`openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048`). Leer erzeugt nexxus bei jedem Start einen neuen Schlüssel, und alle ausgestellten Tokens werden beim Neustart ungültig. |
| `NEXXUS_SECRETS_KEY` | Verschlüsselt das Entra-Secret, Connector-Secrets und andere gespeicherte Zugangsdaten (`openssl rand -base64 32`). |
| `APP_FRONTEND_BASEURL` | Wohin der Browser nach einer Microsoft-Anmeldung geht, wenn <Ui>Ziel nach der Anmeldung</Ui> leer ist. |
| `app.cors.allowedOrigins` | Browser-Anwendungen, die `/oauth2/token` direkt aufrufen, brauchen hier ihren Origin. |
:::

## Wie es weitergeht

<CardGrid>
  <LinkCard title="Sicherheit" description="Zwei-Faktor-Authentifizierung, Sitzungen, API-Tokens und das Änderungsprotokoll." href="/de/setup/security/" />
  <LinkCard title="Einen Connector einrichten" description="Die App beim Anbieter registrieren und Konten verbinden." href="/de/plugins/set-up/" />
  <LinkCard title="Benutzer einladen" description="Konten für alle, die sich nicht mit Microsoft anmelden." href="/de/setup/invite-users/" />
</CardGrid>