Anbindung Microsoft Entra ID (vormals Azure Active Directory, Azure AD) – Quiply Hilfe-Center

Inhaltsverzeichnis

Mapping von Microsoft Entra ID-Properties zu Quiply-Nutzerdaten

Einführung

Für die Anmeldung und Berechtigung eines Nutzers stehen aktuell zwei Varianten zur Verfügung. Zum einen die Anmeldungen direkt über das Quiply-System und zum anderen die Anmeldung über Microsoft Entra ID (vormals Azure Active Directory, Azure AD). Wenn nicht alle Nutzer in Microsoft Entra ID gepflegt werden, lässt sich Microsoft Entra ID mit der Quiply-Anmeldung kombinieren, d. h. die Nutzer, die nicht in Microsoft Entra ID vorhanden sind, nutzen die Quiply-Anmeldung.

Wenn Sie die Anmeldung über Microsoft Entra ID für Ihr Unternehmen aktivieren und einrichten möchten, kontaktieren Sie bitte Ihren Quiply-Ansprechpartner.
⚠️ Hinweis: Microsoft Entra ID ist eine Cloud-Lösung und unterscheidet sich von einem lokalen Active Directory (On-Premise). Der folgende Artikel kann als Einstieg dienen, um ein lokales Active Directory an Microsoft Entra ID anzubinden: https://docs.microsoft.com/de-de/azure/architecture/reference-architectures/identity/azure-ad.

⚠️ Hinweis: Der Name "Azure Active Directory" wurde von Microsoft zu "Microsoft Entra ID" geändert: https://learn.microsoft.com/en-us/entra/fundamentals/new-name.

Einrichtung Microsoft Entra ID

Vorraussetzung: Für die Anbindung von Microsoft Entra ID an das Quiply-System muss der Kunde Zugang zu Microsoft Entra ID haben. Falls ein entsprechendes Konto nicht besteht, muss dieses bei Microsoft beantragt werden: https://azure.microsoft.com/de-de/account/.

App-Registrierung in Microsoft Entra ID

Mit Hilfe der App-Registrierung erlaubt man dem Quiply-System bestimmte Aktionen auszuführen, um Daten zwischen Microsoft Entra ID und Quiply auszutauschen und zu überprüfen. Es wird die OAuth 2.0 Variante „Impliziter OAuth 2.0-Gewährungsablauf“ verwendet.

Die nachstehende Anleitung zeigt die Schritte zur App-Registrierung in vereinfachter Form. Weitere Details und Hilfe finden sich auf den jeweiligen Seiten im Azure Portal.

Melden Sie sich im Azure Portal an.
Wechseln Sie in die Microsoft Entra ID-Ansicht
Klicken Sie auf App registrations und dann auf New registration
Tragen Sie einen Namen ein, wählen Sie die Option wie unten angezeigt und klicken Sie dann auf Register
Notieren Sie sich die Application (client) ID ("Anwendungs-ID") und die Directory (tenant) ID ("Verzeichnis-ID"). Diese müssen Sie später in der Administrationsoberfläche in Quiply für die Einrichtung der Microsoft Entra ID-Anbindung eintragen. Klicken Sie dann auf Add a Redirect URI.
Im Bereich Authentication klicken Sie auf Add a platform und wählen Web und tragen Sie die folgenden URIs ein.
- Für Android/iOS: http://localhost/callback (in App-Browser auf dem Endgerät).
- Für die Web-App von Professional-Kunden: https://<ihr_unternehmen>.quiply.io (nutzen Sie hierfür die URL Ihrer Webpage).
- Für die Web-App von Essential-Kunden: https://app.quiply.io.
Wähen Sie außerdem die Optionen Access tokens und ID tokens.
Klicken Sie im linken Seitenmenü auf API permissions und dann auf Add a permission. Wählen Sie die die Permissions openid und User.Read vom Typ Delegated und User.Read.All vom Typ Application.
Fügen Sie ein Client Secret hinzu, indem Sie auf Certificates & secrets klicken und mit New client secret ein Secret erzeugen. Geben Sie bei Description eine Beschreibung ein und wählen Sie eine Gültigkeitsdauer mit Expires.
Kopieren Sie schließlich Ihr Client Secret, da dies nur direkt nach dem Erstellen möglich ist.

Damit ist die Einrichtung von Microsoft Entra ID für die Quiply-App abgeschlossen. Als nächstes muss das Quiply-System konfiguriert werden.

Anbindung Microsoft Entra ID in Quiply

Öffnen Sie in der Quiply-App die App-Administration.
Wählen Sie im linken Seitenmenü Active Directory / Entra ID aus (in älteren App-Versionen kann der Menüpunkt noch Active Directory heißen)
Tragen Sie die Werte in der Maske ein
- National Cloud: Bitte wählen Sie hier die entsprechende Microsoft Cloud aus, in der sich Ihr Microsoft Entra ID befindet. In Abhängigkeit der Cloud ändern sich die verwendeten URLs, die von Microsoft bereitgestellt werden.
  Hinweis: Hier sollten Sie im Normalfall "Azure AD (global service)" auswählen. "Microsoft Cloud Germany" war eine Sonderlösung für den deutschen Markt, die inzwischen eingestellt wurde (s. https://docs.microsoft.com/en-us/azure/germany/germany-welcome).
- Verzeichnis-ID (Mandant/Tenant): Tragen Sie hier die Directory (tenant) ID aus Microsoft Entra ID ein, die Sie zuvor notiert haben (falls nicht finden Sie diese unter App-Registrierungen im Azure Portal).
- Anwendungs-ID (Client): Tragen Sie hier die Application (client) ID ein, die Sie zuvor notiert haben (falls nicht finden Sie diese unter App-Registrierungen im Azure Portal).
- Client Secret: Tragen Sie hier das Client Secret (geheimer Clientschlüssel) für den Client aus Microsoft Entra ID ein, den Sie zuvor notiert haben oder erstellen Sie in Microsoft Entra ID einen neuen.
- ⚠️ Hinweis: Die Gültigkeit des Client Secrets ist zeitlich begrenzt. Ein neues Client Secret sollte vor Ablauf erstellt und hinterlegt werden. Eine automatische Erinnerung an das Ablaufdatum des Client Secret erfolgt seitens Microsoft nicht, sodass wir Ihnen empfehlen, ein eigenes Monitoring hierüber zu erstellen.
- ⚠️ Hinweis: Da der Zugriff auf die App über zu Microsoft Entra ID nach Ablauf des Client Secret blockiert ist, empfehlen wir Ihnen dringend mindestens einen (1) App-Administrator als externen Nutzer anzulegen! Dieser Nutzer kann sich in der Quiply-App ohne Microsoft Entra ID einloggen und ein neues Client Secret setzen, sollte die fristgemäße Verlängerung des Client Secret einmal versäumt werden.
- Rollen-Mapping: Hier können Sie die Microsoft Entra ID-Gruppen komma-separiert hinterlegen und festlegen, welche dieser Gruppen den Quiply-Rollen App-Administrator bzw. App-Superior entsprechen. Im Screenshot als Beispiel die Microsoft Entra ID-Gruppen „Development-Admin“ und „Development-Superior“. Sie können jede Microsoft Entra ID-Gruppe verwenden, der in Microsoft Entra ID existiert. Alle Nutzer innerhalb dieser Microsoft Entra ID-Gruppe erhalten in Quiply die entsprechende App-Adminstrator-Rolle oder App-Superior-Rolle. Wenn ein Nutzer die Microsoft Entra ID-Gruppe verlässt, wird ihm auch automatisch in Quiply die App-Administrator-Rolle oder App-Superior-Rolle entzogen.
- Bei bestimmten Konfiguration kann es vorkommen, dass vom Microsoft Entra ID keine Gruppennamen übermittelt werden. Für diese Fälle können Sie statt einem Gruppennamen wie „Development-Admin“ auch die Object Id einer Gruppe angeben, beispielsweise „eb333286-013a-4352-ad83-902bb4aba011“. (Aus Sicherheitsgründen werden Gruppennamen, die dem Schema einer Object Id entsprechen, ignoriert.)
- Falls Sie die Verwaltung der Rollen App-Administrator und App-Superior über Microsoft Entra ID unterbinden wollen, können Sie Rollen-Mappings leer lassen. So können Sie beispielsweise auch Nutzern, die ansonsten über Microsoft Entra ID verwaltet werden, manuell die Rollen App-Administrator oder App-Superior zuteilen. Beachten Sie daher, dass zum Entziehen der Rollen App-Administrator oder App-Superior, die über Microsoft Entra ID vergeben wurden, Rollen-Mappings eingetragen sein müssen. Hierbei ist es möglich, z. B. nicht vorhandene Gruppennamen oder sogar freie Bezeichner wie „deaktiviert“ oder „wird-nicht-mehr-verwendet“ zu verwenden.

Mapping von Microsoft Entra ID Properties in Quiply-Nutzerdaten

Folgende Nutzerdaten aus dem Microsoft Entra ID werden nach einer festen Zuordnung in Quiply-Nutzerdaten transformiert und können nicht angepasst werden:

Microsoft Entra ID Property	Quiply-Nutzerdaten	Bemerkung
userPrincipalName	username	Die E-Mail des Nutzers in Microsoft Entra ID. Wird zum Login benötigt.
givenName	firstname	Der Vorname des Nutzers.
surname	lastname	Der Nachname des Nutzers.
displayName	alias	Der Anzeigename des Nutzers.

Die Zuordnung der Microsoft Entra ID Properties bezieht sich dabei auf die REST-Schnittstelle V 1.0 der offiziellen Microsoft Graph API.

Andere Properties aus Microsoft Entra ID können dynamisch in die entsprechenden Quiply-Nutzer-Profilfelder übersetzt werden. Somit ist es möglich Werte in den Multi-Select-Attributfeldern mit bestehenden Microsoft Entra ID-Gruppen, die einem Nutzer zugeordnet sind, zu synchronisieren. Diese Option ermöglicht es, dass existierende Berechtigungen aus Microsoft Entra ID in das Quiply System übernommen werden und damit für die Steuerung von Abläufen in der Quiply-App herangezogen werden können.

Wählen Sie hierzu ein Nutzer-Profilfeld aus vom Typ Multi-Select und setzen Sie an dem jeweiligen Auswahlwert die entsprechende Microsoft Entra ID-Gruppe, die dem Wert in Quiply entspricht. Das folgende Beispiel illustriert dies an Hand eines kundenspezifischen Profilfeld Rolle.

Das Profilfeld Rolle hat verschiedene Auswahlwerte. Hier im Beispiel ist dem Auswahlwert „Spezial – (Test und Doku)“ eine Microsoft Entra ID-Gruppe "Development_Spezial" zugeordnet, so dass jeder Nutzer, der sich in dieser Microsoft Entra ID-Gruppe befindet, in Quiply den Auswahlwert „Spezial – (Test und Doku)“ erhält.

Alle Profilfelder, die nicht vom Typ Multi-Select sind, z.B. Text, Telefon etc., können mit einem Mapping auf eine Microsoft Entra ID-Property hinterlegt werden. Hier erfolgt die Zuordnung an Hand der Properties, wie diese in der REST-Schnittstelle von Microsoft angegeben sind. Das folgende Beispiel zeigt dies für die Microsoft Entra ID-Property „mobilePhone“, welches in ein Quiply-Profilfeld „Telefon Geschäft“ übersetzt wird. Damit das Mapping aktiviert ist, muss man in dem Feld „Profile Mapping“ die Microsoft Entra ID-Property eintragen.

⚠️ Hinweis: Manche Properties erfordern bestimmte Microsoft-Lizenzen wie etwa SharePoint Online. Leider macht Microsoft keine genauen Angaben welche Properties welche Lizenzen benötigen. Eine Anfrage mit einer Property zu der keine Lizenz vorhanden ist, schlägt fehl. In diesen Fällen wird auf eine Anfrage mit den sogenannten Common Properties (allgemeine Eigenschaften) zurück gefallen.

Common Properties sind (Stand 09.03.2022):