GAPTEQ supports the authentication of your GAPTEQ users via Azure Active Directory (Azure AD) and thus reduces your administrative effort in user management.
In this article you will read the following content:
Note! In order for Azure AD to be set up correctly, the GAPTEQ web engine must be accessible via the Internet and requires SSL.
Exception: If everything is installed on one machine and GAPTEQ-Web is only accessed via https://localhost/GAPTEQForms. More on this below under “Create SSL certificate for IIS if GAPTEQ is started via ‘localhost’”).
1. Settings in Azure AD
1.1 App registration
The use of Azure AD for an application requires an app registration.
- To do this, go to the Azure portal and create a new app registration as follows:
Go to the “App registrations” resource group and click on “New registration”. - For example, enter “GAPTEQ-TEST” as the name (→ the name is not relevant for the configuration, you can also enter a different name).
- On the “Supported account types” tab, select “Only accounts from in this organization directory (...)”.
- For “Redirect URL (optional)”, select “Web” under “Select platform” In the input field next to it, enter how your installation of GAPTEQ can be accessed via the web, with the extension “/oidc/signin-oidc”, e.g:
„https://www.companyname.de/gapteqforms/oidc/signin-oidc“ oder
„https://localhost/gapteqforms/oidc/signin-oidc“.
Important! Enter everything in lower case!
- Mit Klick auf „Registrieren“ schließen Sie die App-Registrierung ab.
Tip! Two details are important here, which are best copied directly into a text editor: Application ID (client) and Directory ID (client). These two values are later relevant for the configuration of GAPTEQ.
1.2 Token configuration
The token configuration specifies what an authenticated user of the application is allowed to read from the Azure AD. The following settings are required for GAPTEQ.
- To do this, click on “Token configuration” in the app registration overview on the left-hand side.
- Click on “Add optional entitlement”. A window opens in the right-hand side area, where you select the value “ID” for “Token type”.
- A list appears - select the values “email”, “family_name”, “given_name”, “verfied_primary_email”, “verified_secondary_email” and click on “Add”.
- Another window will appear. Check the box “Activate Microsoft Graph authorization (...)” and click on “Add”.
Adding a group entitlement
- To add a group entitlement, click on “Add group entitlement”.
- A window opens on the right-hand side. Select “Security groups” and click on “Add”.
1.3 API authorizations
The API authorization defines what a client application is allowed to read from the Azure AD. The following settings are required so that the GAPTEQ Designer can read users and user groups.
- To do this, go to “Authentication” in the app registration overview on the left-hand side.
Add platform
- Click on “Add platform”.
- A window appears in the right-hand area. Select “Mobile device and desktop applications".
Another window appears, select “https://login.microsoftonline.com/common/oauth2/nativeclient” and click on “Add”.
Set ID token
- Once you have added the platform, you can set the ID token under the “Authentication” tab by checking the checkbox "ID tokens (used for implicit and hybrid flows)".
Set API authorizations
- Click on “API permissions” in the left-hand area of the app registration overview. You will already see a list of API permissions. To add permissions, proceed as follows:
- Click on “Add permission”, a window will appear in the right-hand area, select “Microsoft Graph” there.
- In the following window, select “Delegated permissions”, a grouped list appears at the bottom.
- Select the fields “email”, “openid” and “profile” in the list in “OpenId authorizations”. Further down in the list in the “Group” group, select “Group.Read.All”. Again further down in the list in the “User” group, select “User.Read” and “User.Read.All”.
- Then click on “Add authorization”. You will then see a list of all authorizations.
Tip! Administrator consent is required for some entries. You can see this in the “Status” column. To grant administrator consent, click on “Grant administrator consent for (...)”. In the following question, click on “Yes, add further granted authorizations to configured authorizations” and click on “Save and continue”. Another prompt appears, confirm it.
2. Configuration of GAPTEQ-Web
The appsettings.json file is located in the installation directory. This file must be adapted as follows (the values marked in bold must be edited):
Tip! The file can only be saved by a user with administrator authorization. Start your editor (e.g. Notepad) with “Run as administrator” and then open this file. This is the only way to save the file.
…
„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“
},
…
Note! In “AllowedAuthentication”, only ONE setting next to “Internal” may be set to true. The other settings depend on your installation or your Azure AD. Under “<your domain>”, enter how your installation can be reached, e.g. “www.firmenname.de/gapteqforms”. (WITHOUT the extension mentioned above)
Notiz! 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“).
Attention! If this file has been customized, the IIS must be restarted.
3. SSL certificate for IIS
If you are running a test installation in which all GAPTEQ components are installed on your machine and the browser is only opened via localhost (https://localhost/GAPTEQForms), you can create an SSL certificate for localhost - this is always necessary for Azure AD. To do this, proceed as follows:
- Start Windows PowerShell as administrator
- Execute command (one line)
New-SelfSignedCertificate -DnsName „localhost“ -CertStoreLocation „cert:\LocalMachine\My“ -NotAfter (Get-Date).AddYears(100)
- Execute command with mmc.exe
- in the MM-Console click on “File” → “Add or Remove Snap-ins” → “Certificates” → “Add” → “Computer account” → “Local computer” → “Finish”
- In the “Certificates (Local Computer)/Personal/Certificates” console, copy and paste the “localhost” certificate to “Certificates (Local Computer/Trusted Root Certification Authorities/Certificates”.
- Start the IIS Manager.
- In the relevant web site (Default Web Site), select: “Edit Bindings” → ‘Add’, then ‘HTTPS’ and below the certificate ‘localhost’ → ‘OK’.