API / OAuth2-Schnittstelle

Dokumentation der HiOrg-Server API: https://api.hiorg-server.de/docs

Zur Nutzung der API ist (in den meisten Bereichen) die Angabe von Client Credentials notwendig. Wenn Sie die API mit Ihrem Client nutzen wollen, senden Sie bitte eine E-Mail an support@hiorg-server.de mit Angabe folgender Daten, um dann entsprechende Client-Zugangsdaten zu erhalten:

• geplanter Einsatzzweck
• Bezeichnung Ihres Client
• Kontakt-E-Mail-Adresse des technischen Betreuers Ihrer Clientsoftware
• gültige Redirect-URL (siehe Beschreibung des OAuth2-Protokolls)
• ggf. auf welche Organisationen (bitte Org.-Kürzel nennen) die Nutzung dieser Credentials begrenzt werden soll

• Brent Shaffer
• An Introduction to OAuth2
• Durch Integration in die Bibliothek ScribeJava kann diese Schnittstelle mit dem OpenSource Single-Sign-On CAS (Wikipedia zu CAS) genutzt werden
• Mit der Java-Bibliothek "pac4j" (ab Version 3.2.0) lässt sich die OAuth-Schnittstelle in beliebigen Java-Anwendungen nutzen

Als Redirect URL muss „https://deine-domain.de/index.php/apps/sociallogin/custom_oidc/hiorg“ (deine-domain.de entsprechend ersetzen) angeben werden.

Um OAuth2 (genauer gesagt OpenID Connect) in der Nextcloud zu nutzen, muss nun die App „Social Login“ aus dem Appstore installiert und aktiviert werden. Anschließend findet der Admin in den Einstellungen einen neuen Reiter „Social Login“. In diesem kann eine neue „Benutzerdefinierte OpenID Connect Anbindung“ durch ein Klicken auf das „+“ definiert werden. Dort müssen folgende Einstellungen getätigt werden:

• Interner Name: „hiorg“ (falls hier ein anderer Name gewählt wird, muss die Redirect URL am Ende entsprechend angepasst werden)
• Anzeigename: „HiOrg-Server“ (Dieser Text wird später auf der Login Seite angezeigt: „Login über HiOrg-Server“)
• Authorize-URL: „https://api.hiorg-server.de/oauth/v1/authorize?ov=XXXX“ (XXXX durch das Kürzel des eigenen HiOrg-Server ersetzen)
• Token URL: „https://api.hiorg-server.de/oauth/v1/token“
• Display name claim: (kann leer bleiben)
• Userinfo-URL: „https://api.hiorg-server.de/oauth/v1/userinfo“
• Logout-URL: (kann leer bleiben)
• Client ID: Diese Information bekommt ihr von support@hiorg-server.de
• Client Secret: Diese Information bekommt ihr von support@hiorg-server.de
• Scope: „openid groups“
• Groups claim: „groups“
• Stil der Schaltfläche: „Keine“ auswählen
• Standardgruppe: Hier kann eine Standardgruppe für neue Benutzer, welche sich über den HiOrg-Server bei der Nextcloud anmelden, festgelegt werden. Alternativ „Keine“ wählen.
• Gruppen-Mapping hinzufügen: Hier kann optional eine Gruppe im HiOrg-Server einer bestehenden Gruppe in der Nextcloud zugeordnet werden. Dazu links den Namen der Gruppe im HiOrg-Server eintragen und rechts die Gruppe in der Nextcloud wählen.

Mit den nun getätigten Einstellungen können sich Benutzer des HiOrg-Server in der Nextcloud anmelden. Außerdem werden Gruppen des HiOrg-Server automatisch in die Nextcloud übernommen. Sollte dies nicht gewünscht sein, einfach bei den Einstellungen den Scope „groups“ weglassen und das Feld Groups claim leer lassen.

Es ist empfehlenswert, ganz oben die Option „Benutzerprofil nach jeder Anmeldung aktualiseren“ zu aktivieren, damit auch bei bestehenden Benutzern die Gruppen entsprechend gesetzt bzw. bei einer Änderung aktualisiert werden. Weiterhin muss „Nicht existierende Gruppen automatisch erstellen“ aktiviert sein, wenn die Gruppen aus dem HiOrg-Server in der Nextcloud verwendet werden sollen. Wird hingegen Gruppen-Mapping verwendet, ist diese Option ggf. nicht notwendig.