> ## Documentation Index
> Fetch the complete documentation index at: https://docs.anny.co/llms.txt
> Use this file to discover all available pages before exploring further.

# OAuth2 / OpenID Connect SSO

> Richte einen Unternehmenslogin über OAuth2 beziehungsweise OpenID Connect in anny ein, inklusive Callback-URL, Scopes und Attributzuordnung.

In diesem Artikel erfährst du, wie du einen Unternehmenslogin über OAuth2 beziehungsweise OpenID Connect bei anny einrichtest. Das ist die richtige Wahl, wenn dein Identity Provider kein SAML unterstützt oder du OAuth2 bevorzugst.

<Info>
  Unterstützt dein Identity Provider SAML 2.0, empfehlen wir diesen Weg, da mehr Funktionen wie SCIM und föderierte Anmeldungen zur Verfügung stehen. Eine Anleitung findest du unter [Generisches SAML 2.0 SSO](/generic-saml-sso).
</Info>

## Vorbereitung

Die SSO Verbindung kannst du selbstständig in deinem anny [Admin Bereich](https://app.anny.co/organization/settings/sso?o=) unter SSO & Sicherheit hinterlegen. Neben den anny Admin Rechten benötigst du administrativen Zugang zu deinem Identity Provider, um dort eine OAuth2-Anwendung anzulegen.

Lege zuerst in deinem Identity Provider eine neue OAuth2-Anwendung (teilweise auch "Client" oder "App" genannt) an. Du erhältst dabei eine Client ID und ein Client Secret.

## Einrichtung

<Steps>
  <Step title="Identity Provider in anny anlegen">
    Gehe in die [SSO Einstellungen](https://app.anny.co/organization/settings/sso?o=), wähle "IDP hinzufügen" und dann als Provider "Custom OAuth2". Vergib einen Namen, zum Beispiel "Unternehmenslogin".
  </Step>

  <Step title="Zugangsdaten und URLs eintragen">
    Trage Client ID, Client Secret sowie die drei Endpunkte deines Identity Providers ein. Welche Werte gemeint sind, erklärt die Tabelle unten. Speichere anschließend.
  </Step>

  <Step title="Callback-URL bei deinem Identity Provider hinterlegen">
    Nach dem Speichern zeigt anny dir die Callback-URL an. Kopiere sie und trage sie in deinem Identity Provider als erlaubte Redirect-URL ein.
  </Step>

  <Step title="Verbindung testen und aktivieren">
    Aktiviere den Identity Provider über die drei Punkte > Aktivieren und teste den Login über "Test Connection".
  </Step>
</Steps>

<Warning>
  **Wichtig:** Die Callback-URL steht erst nach dem ersten Speichern zur Verfügung, da sie die ID des Identity Providers enthält. Solange die URL bei deinem Identity Provider nicht hinterlegt ist, bricht der Login mit einer Fehlermeldung wie "redirect\_uri mismatch" ab.
</Warning>

Die Callback-URL folgt diesem Muster, wobei `{id}` die ID des angelegten Identity Providers ist:

Callback-URL: [**https://auth.anny.co/identity-provider/\{id}/oauth/callback**](https://auth.anny.co/identity-provider/\{id}/oauth/callback)

## Pflichtfelder

| Feld in anny          | Beschreibung                                                                                                         |
| --------------------- | -------------------------------------------------------------------------------------------------------------------- |
| **Client ID**         | Die Kennung der OAuth2-Anwendung, die du in deinem Identity Provider angelegt hast.                                  |
| **Client Secret**     | Das zugehörige Geheimnis. anny speichert es verschlüsselt.                                                           |
| **Authorization URL** | Der Endpunkt, zu dem anny deine Nutzer:innen zum Login weiterleitet. Endet häufig auf `/authorize`.                  |
| **Token URL**         | Der Endpunkt, über den anny den Access Token abruft. Endet häufig auf `/token`.                                      |
| **User Info URL**     | Der Endpunkt, über den anny die Nutzerdaten abruft. Endet häufig auf `/userinfo`.                                    |
| **Scopes**            | Die angefragten Berechtigungen, getrennt durch Leerzeichen. Bei OpenID Connect üblicherweise `openid profile email`. |

<Tip>
  Viele Identity Provider veröffentlichen ihre Endpunkte unter `https://<dein-provider>/.well-known/openid-configuration`. Dort findest du die Werte für Authorization URL, Token URL und User Info URL gebündelt.
</Tip>

## Erweiterte Optionen

Die erweiterten Optionen brauchst du nur, wenn dein Identity Provider vom Standard abweicht. Du findest sie im Formular unter "Erweiterte Optionen".

| Feld in anny                              | Beschreibung                                                                                                              |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| **PKCE verwenden**                        | Aktiviere diese Option, wenn dein Identity Provider Proof Key for Code Exchange voraussetzt.                              |
| **Scope-Trennzeichen**                    | Zeichen, mit dem die Scopes in der Anfrage getrennt werden. Die meisten OpenID-Connect-Anbieter erwarten ein Leerzeichen. |
| **Token-Anfrage als JSON senden**         | Fordert den Access Token mit einem JSON-Body statt einer Formular-Kodierung an.                                           |
| **Basic-Auth-Benutzername und -Passwort** | Werden als HTTP-Basic-Authentifizierung an den Token-Endpunkt gesendet, falls dein Identity Provider das verlangt.        |
| **Attribut-Felder**                       | Legen fest, aus welchen Feldern der User-Info-Antwort anny ID, E-Mail, Vor- und Nachname liest.                           |

### Attribute zuordnen

Standardmäßig erwartet anny die Felder `id`, `email`, `firstname` und `lastname`. Viele Identity Provider nutzen abweichende Namen. Bei OpenID Connect sind zum Beispiel folgende Werte üblich:

| Feld in anny             | Typischer Wert bei OpenID Connect |
| ------------------------ | --------------------------------- |
| **Benutzer-ID-Attribut** | `sub`                             |
| **E-Mail-Attribut**      | `email`                           |
| **Vorname-Attribut**     | `given_name`                      |
| **Nachname-Attribut**    | `family_name`                     |

Liegen die Werte verschachtelt in der Antwort, kannst du den Pfad mit Punkten angeben, zum Beispiel `data.user.id`.

<Note>
  Diese Felder steuern nur, woher anny die Nutzerdaten liest. Wenn du Nutzer:innen zusätzlich automatisch Communities zuordnen möchtest, nutze dafür das [Attribute Mapping](/attribute-mapping).
</Note>

## Nach der Einrichtung

* Über die drei Punkte kannst du dir einen Wayfless-Link erzeugen. Damit landen deine Nutzer:innen direkt im Login deines Identity Providers.
* Mit [Attribute Mapping](/attribute-mapping) ordnest du Nutzer:innen automatisch Communities zu.

## Troubleshooting

<AccordionGroup>
  <Accordion title="404: Seite nicht gefunden">
    Der Identity Provider ist noch nicht aktiviert. Aktiviere ihn über die drei Punkte > Aktivieren. Solange er deaktiviert ist, sind Login und Callback bewusst nicht erreichbar.
  </Accordion>

  <Accordion title="redirect_uri mismatch">
    Die Callback-URL ist bei deinem Identity Provider nicht oder nicht exakt hinterlegt. Kopiere sie erneut aus anny und achte darauf, dass sie zeichengenau übereinstimmt, inklusive `https://` und ohne abschließenden Schrägstrich.
  </Accordion>

  <Accordion title="Login funktioniert, aber es fehlen Nutzerdaten">
    Prüfe die Attribut-Felder in den erweiterten Optionen. Wenn dein Identity Provider zum Beispiel `given_name` statt `firstname` liefert, muss der Wert dort entsprechend hinterlegt sein. Prüfe außerdem, ob die angefragten Scopes ausreichen, um E-Mail und Namen zu erhalten.
  </Accordion>

  <Accordion title="Fehler beim Abrufen des Tokens">
    Kontrolliere Client ID und Client Secret sowie die Token URL. Verlangt dein Identity Provider HTTP-Basic-Authentifizierung oder einen JSON-Body, aktiviere die passenden erweiterten Optionen.
  </Accordion>
</AccordionGroup>

Eine allgemeine Übersicht zu SSO findest du hier: [SSO Übersicht](/sso-overview)