Quelltext der Seite Authentifizierung mit OAuth2

== Was ist OAuth2? ==
OAuth2 ist ein Authentifizierungsmechanismus, bei dem der Benutzername + Passwort nicht mehr in jeder Applikation hinterlegt werden muss.

Stattdessen gibt man einzelnen Applikationen Berechtigungen. Die Berechtigung wird als Token in der Applikation gespeichert, mit dessen Hilfe sich die Applikation beim jeweiligen Service authentifiziert und Aktionen ausführen kann, z.B. Mailversand.

Das Token kann man also als temporäre Zugangsdaten ansehen, die nur für diese Applikation generiert werden. Sie haben auch nur eine begrenzte Gültigkeit. Nach Ablauf kann die Applikation selbstständig aus dem erhaltenen Token ein sogenanntes Refresh Token anfordern. Das funktioniert aber nur, sofern die Berechtigung seitdem nicht widerrufen wurde.

[[Datei:OAuth2-Berechtigungsanfrage.png|ohne]]

Beispiel Berechtigungsanfrage von einer Test-Applikation bei Microsoft 365
# Account, für welchen die Applikation eine Berechtigung haben möchte
# Applikations-Name
# Applikations-Hersteller URL
# Angefragte Berechtigungen
# Anfrage akzeptieren oder ablehnen


== Redirect URI / Umleitungs-URI ==
Vor dem Erstellen einer Applikation müssen Sie sich vorab für eine Redirect URI entscheiden.

Die Redirect URI ist die Zieladresse, wohin Microsoft die Antwort auf die Berechtigungsanfrage senden kann. Diese kann auch auf localhost führen, da es sich um eine Weiterleitung innerhalb des Browsers handelt.

Die jeweilige Applikation muss bei einer Authentifizierung einen Webserver starten, sodass sie diese Antwort empfangen kann.

Die Redirect-URI kann von Ihnen frei gewählt werden und kann auch einen von Ihnen gewählten Port enthalten. Bitte achten Sie darauf, dass der Port auf der jeweiligen Maschine freigegeben ist und nicht schon von anderen Applikationen belegt ist.

Wir können beispielsweise folgende Redirect URI wählen:

http://localhost:4564/auth-response

Die Applikation muss also auf dem Port 4564 einen Webserver starten und per HTTP GET auf /auth-response die Berechtigungs-Antwort empfangen können.


== Erstellen einer Applikation (Microsoft 365) ==
Um OAuth2 mit einer Applikation nutzen zu können, muss diese zunächst bei Microsoft registriert werden. Da es sich hier um lokale Client-Applikationen handelt, kann dies leider nicht von uns übernommen werden.

Zum Registrieren einer Applikation hat Microsoft hier eine detaillierte Anleitung veröffentlicht:

https://docs.microsoft.com/de-de/azure/active-directory/develop/quickstart-register-app

Im Folgenden eine Zusammenfassung dessen, sowie abgekürzt auf die Erfordernisse unserer Applikationen.

=== Registrierung im Azure Portal ===
Sie können das Azure Portal über diese URL erreichen:

https://portal.azure.com

Gehen Sie dann auf Azure Active Directory -> App Registrierungen -> Neue Registrierung

Sie können nun einen Namen für die Applikation frei wählen, z.B. Mailer.

Unter Unterstützte Kontotypen wählen Sie „Nur Konten in diesem Organisationsverzeichnis“, sofern möglich. Falls später für die Authentifizierung ein Microsoft 365 Account verwendet werden soll, der sich nicht in Ihrer Microsoft 365 Organisation befindet, können Sie eine der anderen Option wählen. Bitte beachten Sie dann aber die ggf. zusätzlichen Anforderungen seitens Microsoft.

Für die Umleitungs-URI tragen Sie als Platform „Web“ ein und tragen als URI die vorher festgelegte Redirect URI ein.

[[Datei:OAuth2-App-erstellen.PNG|ohne]]


=== Anwendungs-ID / Client ID ===
Im nächsten Fenster wird die Anwendungs-ID angezeigt. In diesem Beispiel beginnend mit „1e0ad[…]“. Bitte notieren Sie sich diese ID.

Sie erreichen dieses Fenster auch in der Übersicht der gerade registrierten Applikation.

[[Datei:OAuth2-Client-ID.png|ohne]]


=== Geheimer Clientschlüssel / Client Secret ===
Gehen Sie als nächstes zum Menüpunkt Zertifikate & Geheimnisse und erstellen Sie einen neuen geheimen Clientschlüssel.

Die Beschreibung können Sie beliebig wählen, z.B. das heutige Datum. Als „Gültig bis“ wählen Sie einen Zeitraum, der für Sie akzeptabel ist. Hinweis: Sie müssen vor Ablauf ein neues Client Secret erstellen und erneut in der jeweiligen Applikation eintragen.

Sie sehen nun '''einmalig''' den Wert des Clientschlüssels (in diesem Beispiel beginnend mit 4sU8Q~[…]). '''Bitte notieren Sie sich diesen Wert jetzt''', da er später nicht mehr sichtbar sein wird. Bitte bewahren Sie diesen Schlüssel auch sicher auf, d.h. es darf kein Unbefugter Zugriff auf diesen Schlüssel erhalten.

[[Datei:OAuth2-Client-Secret.png|ohne]]

=== API-Berechtigungen ===
Gehen Sie als nächstes in das Menü API-Berechtigungen. Hier legen Sie fest, was die Applikation machen darf. Drücken Sie auf „Berechtigung hinzufügen“ und fügen Sie unter „Microsoft Graph“ -> „Delegierte Berechtigungen“ folgende Berechtigungen hinzu (Sie können die Suchfunktion verwenden): 

* email
* IMAP.AccessAsUser.All
* offline_access
* POP.AccessAsUser.All
* SMTP.Send

Die finalen Berechtigungen sollten so aussehen:
[[Datei:OAuth2-Berechtigungen.png|ohne]]


=== Besitzer ===
Im Menüpunkt Besitzer empfiehlt es sich, weitere Kollegen hinzufügen, sodass diese auch bei Abwesenheit die registrieren Applikation administrieren und ggf. ein neues Client Secret erstellen können.


== Konfigurieren der Applikation ==
Beim Erstellen einer neuen Token Konfiguration benötigen Sie folgende Parameter:

Konfigurations-ID – Hier können Sie selbst eine ID festlegen. Sie muss eindeutig sein. Idealerweise der gleiche Name wie die registrierte App

Vorlage – Hier wählen Sie aus, welcher Service verwendet werden soll. Für Azure Apps mit Kontotyp „Nur Konten in diesem Organisationsverzeichnis“ wählen Sie „SMTP – Microsoft 365 (Organizations)“.

Umleitungs-URI – Hier die gleiche URL eintragen, welche Sie bei der [[#Registrierung_im_Azure_Portal|Registrierung der App]] verwendet haben.

Anwendungs-ID – Die Client ID beim [[#Anwendungs-ID_/_Client_ID|Erstellen der App]]

Geheimer Clientschlüssel – Das einmalig angezeigte [[#Geheimer_Clientschlüssel_/_Client_Secret|Client-Secret]]

[[Datei:OAuth2-Token-Konfiguration.png|ohne]]

== Token Anfragen ==
Sobald Sie eine Token-Konfiguration gespeichert haben, können Sie über „Token Status“ den aktuellen Status eines Tokens abfragen und die Applikation auch gleich autorisieren.

[[Datei:OAuth2-Token-Status.png|ohne]]