Press Ctrl/Cmd + P to print
or save as PDF

Azure Active Directory

Authentifizieren von GAPTEQ-Usern über das Azure Active Directory (Azure AD)

GAPTEQ unterstützt die Authentifizierung Ihrer GAPTEQ-User über Azure AD. Um Ihr Azure AD mit GAPTEQ zu nutzen, müssen zunächst einige Einstellungen vorgenommen werden.

Ihre Vorteile

  • Reduzierter Verwaltungsaufwand im User-Management.
  • Nutzung von Unternehmensidentitäten und Azure AD-Usergruppen in den Access Rights Ihrer GAPTEQ-Applikation.
  • Automatisiertes Erstellen der GAPTEQ-User bei Anmeldung eines Azure AD-Users möglich.

So geht’s Schritt für Schritt: 

  • Einstellungen im Azure AD
  • Konfiguration von GAPTEQ-Web
  • SSL-Zertifikat für IIS erstellen

 

Wichtig: Damit Azure AD korrekt eingerichtet werden kann, muss die GAPTEQ-Web-Engine per Internet erreichbar sein und benötigt unbedingt SSL. (Ausnahme: Wenn alles auf einer Maschine installiert ist und GAPTEQ-Web nur über https://localhost/GAPTEQForms aufgerufen wird. Mehr dazu weiter unten unter „SSL-Zertifikat für IIS erstellen, falls GAPTEQ über ‚localhost‘ gestartet wird“.)

1. Einstellungen im Azure AD

1.1 App-Registrierung 

Die Nutzung des Azure AD für eine Applikation erfordert eine App-Registrierung. Gehen Sie dazu ins Azure-Portal und legen eine neue App-Registrierung wie folgt an:

 

  1. Gehen Sie auf die Ressourcengruppe „App-Registrierungen“ und klicken Sie auf „Neue Registrierung“.
  2. Geben Sie als Name z.B. „GAPTEQ-TEST“ (→ der Name ist nicht relevant für die Konfiguration, Sie können auch einen anderen Namen angeben)
  3. Bei dem Reiter „Unterstützte Kontotypen“ wählen Sie „Nur Konten aus in diesem Organisationsverzeichnis (…)“. Bei „Umleitungs-URL (optional)“ wählen Sie bei „Plattform auswählen“ den Punkt „Web“ Im Eingabefeld daneben geben Sie an, wie Ihre Installation von GAPTEQ per Web erreichbar ist, mit der Erweiterung „/oidc/signin-oidc“, also z.B.:

„https://www.firmenname.de/gapteqforms/oidc/signin-oidc“

oder

„https://localhost/gapteqforms/oidc/signin-oidc“.

→ WICHTIG: alles in Kleinbuchstaben angeben!

  1. Mit Klick auf „Registrieren“ schließen Sie die App-Registrierung ab.

 

Sie sehen anschließend eine Übersicht der App-Registrierung.

Tipp: Hier sind zwei Angaben wichtig, die Sie am besten gleich in einen Text-Editor kopieren: Anwendungs-ID (Client) und Verzeichnis-ID (Mandant). Diese zwei Werte sind später für die Konfiguration von GAPTEQ relevant.

1.2. Tokenkonfiguration 
Die Tokenkonfiguration gibt an, was ein authentifizierter User der Applikation aus dem Azure AD auslesen darf. Für GAPTEQ sind untenstehende Einstellungen notwendig. Klicken Sie dazu in der Übersicht der App-Registrierung im linken Bereich auf „Tokenkonfiguration“.

Optionalen Anspruch hinzufügen

  1. Klicken Sie auf „Optionalen Anspruch hinzufügen“. Es öffnet sich im rechten Seitenbereich ein Fenster, wobei Sie bei „Tokentyp“ den Wert „ID“ auswählen.
  2. Es erscheint eine Liste – wählen Sie darin die Werte

„email“, „family_name“, „given_name“, „verfied_primary_email“, „verified_secondary_email”

aus und klicken Sie auf „Hinzufügen“.

  1. Es erscheint erneut ein Fenster. Markieren Sie dort das Kästchen Aktivieren Sie die Microsoft Graph-Berechtigung (…) und klicken Sie auf „Hinzufügen“.

Gruppenanspruch hinzufügen

  1. Um einen Gruppenanspruch hinzuzufügen, klicken Sie auf „Gruppenanspruch hinzufügen“
  2. Es öffnet sich im rechten Seitenbereich ein Fenster. Wählen Sie dort „Sicherheitsgruppen“ und klicken Sie auf „Hinzufügen“.

1.3. API-Berechtigungen 
Die API-Berechtigung legt fest, was eine Client-Applikation aus dem Azure AD auslesen darf. Damit der GAPTEQ-Designer User und Usergruppen auslesen kann, sind folgende Einstellungen notwendig. Gehen Sie dazu in der Übersicht der App-Registrierung im linken Bereich auf „Authentifizierung“.

Plattform hinzufügen

  1. Klicken Sie auf „Plattform hinzufügen“. Im rechten Bereich erscheint ein Fenster. Wählen Sie „Mobilgerät und Desktopanwendungen“.
  2. Es erscheint ein weiteres Fenster, wählen Sie „https://login.microsoftonline.com/common/oauth2/nativeclient“ und klicken Sie auf „Hinzufügen“.

API-Berechtigungen setzen

Klicken Sie auf „API-Berechtigungen“ im linken Bereich der Übersicht der App-Registrierung. Sie sehen bereits eine Liste von API-Berechtigungen. Um Berechtigungen hinzufügen, gehen Sie wie folgt vor:

  1. Klicken Sie auf „Berechtigung hinzufügen“, es erscheint im rechten Bereich ein Fenster, wählen Sie dort „Microsoft Graph“.
  2. Im folgenden Fenster wählen Sie „Delegierte Berechtigungen“, unten erscheint eine gruppierte Liste.
  3. Wählen Sie in der Liste in „OpenId-Berechtigungen“ die Felder

„email“, „openid“ und „profile“ aus.

Weiter unten in der Liste in der Gruppe „Group“ wählen Sie „Group.Read.All“. Nochmals weiter unten in der Liste in der Gruppe „User“ wählen Sie „User.Read“ und „User.Read.All“ aus.

  1. Klicken Sie dann auf „Berechtigung hinzufügen“. Sie sehen dann eine Liste aller Berechtigungen.

 

Tipp: Für manche Einträge ist die Administratoreinwilligung notwendig. Sie sehen das in der Spalte „Status“. Um die Administratoreinwilligung zu erteilen, klicken Sie auf „Administratorzustimmung für (…) erteilen“. Bei der folgenden Frage klicken Sie auf „Ja, weitere gewährte Berechtigungen zu konfigurierten Berechtigungen hinzufügen“ und klicken Sie auf „Speichern und weiter“. Es kommt eine weitere Abfrage, bestätigen Sie diese.

2. Konfiguration von GAPTEQ-Web

Im Installationsverzeichnis liegt die Datei appsettings.json vor. Diese Datei muss folgendermaßen angepasst werden (die fett markierten Werte müssen bearbeitet werden):

Tipp: Die Datei kann nur von einem Benutzer mit Administrator-Berechtigung gespeichert werden. Starten Sie Ihren Editor (z.B. Notepad) mit „Als Administrator ausführen“ und öffnen Sie dann diese Datei. Nur so können Sie die Datei auch speichern.

„AllowedAuthentication“: {

„Internal“: true,

„AzureAd“: true,

„TrustedHeader“: false,

„IntegratedSecurity“: false

},

„AzureAd“: {

„Instance“: „https://login.microsoftonline.com/“,

„Domain“: „<your domain>„,

„TenantId“: „<your TenantId>„,

„ClientId“: „<your ClientId>„,

„CallbackPath“: „/oidc/signin-oidc“

},

WICHTIG: In „AllowedAuthentication“ darf neben „Internal“ nur EINE Einstellung auf true stehen. Die weiteren Einstellungen hängen von Ihrer Installation bzw. von Ihrem Azure AD ab. Tragen Sie bei „<your domain>“ ein, wie Ihre Installation erreichbar ist, z.B. „www.firmenname.de/gapteqforms“. (OHNE die weiter oben genannte Erweiterung)

WICHTIG: Tragen Sie ALLES in KLEINBUCHSTABEN ein. Bei „TenantId“ (= Verzeichnis-ID/Mandant) und „ClientId“ (= Anwendungs-ID/Client) müssen die Werte aus Ihrer Azure AD App-Registrierung eingetragen werden (siehe oben bei „App-Registrierung erstellen“).

Bitte beachten Sie: Wenn diese Datei angepasst wurde, muss der IIS neu gestartet werden.

3. SSL-Zertifikat für IIS

falls GAPTEQ über ‚localhost‘ gestartet wird 

Falls Sie eine Test-Installation betreiben, bei der ALLE GAPTEQ Komponenten auf Ihrer Maschine installiert sind und der Browser NUR über localhost (https://localhost/GAPTEQForms) geöffnet wird, können Sie ein SSL-Zertifikat für localhost erstellen. Das ist für Azure AD immer notwendig. Gehen Sie dazu wie folgt vor:

  1. Windows PowerShell als Administrator starten
  2. Command ausführen (eine Zeile)

New-SelfSignedCertificate -DnsName „localhost“ -CertStoreLocation „cert:\LocalMachine\My“ -NotAfter (Get-Date).AddYears(100)

  1. Command ausführen

mmc.exe

  1. In der MM-Console:

„File“ „Add or Remove Snap-ins“ „Certificates“ „Add“ „Computer account“ „Local computer“ „Finish“

In der Console “Certificates (Local Computer)/Personal/Certificates” per Copy & Paste das Zertifikat “localhost” nach “Certificates (Local Computer/Trusted Root Certification Authorities/Certificates” kopieren.

  1. Starten Sie den IIS Manager.
  2. In der betroffenen Web Site (Default Web Site): „Edit Bindings“ „Add“, dann „HTTPS“ auswählen und unten das Zertifikat „localhost“ auswählen „OK“