Wie funktionieren OAuth-Clients in Inxmail?

Beim ersten Zugriff auf eine Integrationsanwendung müssen Deine Benutzer·innen sich einmalig in Inxmail einloggen und der Integration erlauben, im eigenen Namen mit Inxmail zu interagieren (Consent Screen).

Voraussetzung: Deine Benutzer·innen müssen im Navigationspunkt Benutzer·innen von Inxmail angelegt sein und alle Rechte haben, die sie für die Bedienung der Integrationsanwendung benötigen.

1. Deine Benutzer·innen greifen innerhalb der Integration auf eine Ressource zu, die Zugriff auf die Inxmail API benötigt.

2. Die Integration leitet Deine Benutzer·innen an Inxmail weiter, um die initiale Autorisierung der Benutzer·innen anzufordern.

3. Deine Benutzer·innen authentifizieren sich mit ihren Inxmail Zugangsdaten und erlauben der Integration, in ihrem Namen zu agieren (Consent Screen).

   Hintergrund: Die Integration arbeitet im Namen Deiner Benutzer·innen. Die Integration darf alles, was der·die jeweilige Benutzer·in darf. Wenn Du die Rechte für eine Integration weiter einschränken möchtest, empfehlen wir Dir, eine speziellen Integrations-Benutzerin zu verwenden.

   Die Integration startet den Authorization Code Grant, um die Integration zu autorisieren, im Namen Deiner Benutzer·innen zu handeln.

4. Nach erfolgreicher Authentifizierung bekommt die Integration von Inxmail ein Refresh Token und ein Access Token. Mit Hilfe des (langlebigen) Refresh Tokens kann die Integration künftig (kurzlebige) Access Tokens bei Inxmail anfragen.

   Schütze Dein Refresh Token: Da es möglich ist, mit Hilfe eines Refresh Tokens ohne weitere User-Interaktion neue Access Tokens anzufordern, musst Du das Refresh Token ähnlich wie ein Passwort behandeln und geschützt speichern.

5. Mit Hilfe des (kurzlebigen) Access Tokens ruft die Integration die Inxmail API auf. Inxmail erlaubt den Zugriff auf die angefragte Inxmail Ressource.

Bei späteren Aufrufen der Integrationsanwendung vereinfacht sich der Prozess: Die Integration hat bereits ein (langlebiges) Refresh Token. Die Anforderung des (kurzlebigen) Access Token findet im Hintergrund statt. Dadurch entsteht für Deine Benutzer·innen das Gefühl einer nahtlosen Integration (kein weiterer Inxmail User-Login mehr erforderlich).

1. Deine Benutzer·innen greifen innerhalb der Integration auf eine Ressource zu, die Zugriff auf die Inxmail API benötigt.

2. Die Integration fordert mit Hilfe des (langlebigen) Refresh Tokens ein (kurzlebiges) Access Token bei Inxmail an.

3. (Schritt 3 entfällt)

4. (Schritt 4 entfällt)

5. Die Integration ruft die Inxmail API mit Hilfe des Access Token authentifiziert auf.

   Der Aufruf via Access Token geschieht mit Hilfe eines URL-Fragments, z.B. https://<space>.my-api.inxmail.de/<resource>.

   Dein Refresh Token läuft nach 30 Tagen Inaktivität ab: Wenn das Refresh Token 30 Tage lang nicht genutzt wird, muss ein neues Refresh Token per Authorization Code Grant angefordert werden. Eine Integration muss damit rechnen, dass ein Refresh Token für eine·n bestimmte·n Benutzer·in nicht mehr gültig sein kann.

   Dein Access Token läuft nach 5 Minuten ab: Da das Access Token über eine definierte Lebensdauer von 5 Minuten verfügt, muss die Integration sicherstellen, dass das Access Token für die Dauer der Nutzung gültig ist. Sobald ein Access Tokens abgelaufen ist, muss die Integration die API-Anfrage mit einem neu angeforderten Access Token wiederholen. Diese Funktionalität wird von vielen OAuth-Bibliotheken standardmäßig bereitgestellt.