OpenID - Azure Guide

[Version: 2021]
[Build: 19184]

At a glance, getting TARGIT to use OpenID for user authentication does seem like a rather technical process. In this guide, I will try to remove the fuzz by going through the necessary processes step-by-step.

My example is based on using Azure as the OpenID provider. TARGIT can rely on many other OpenID providers, such as Google, Amazon, SalesForce, Microsoft ADFS ... and many others. So, please bear in mind that the procedures related to Azure in this guide may need to be replaced by other, similar procedures on one of the OpenID platforms.

Overview

To get TARGIT up and running with Azure OpenID authentication, the general steps you need to go through are these:

1. Make sure that Public URLs have been set in TARGIT Management.
2. Log on to the Azure portal to register TARGIT as an Application with the OpenID provider.
3. Obtain (copy) the necessary Client ID, Client Secret, Authorization Endpoint, Token Endpoint and Scope as part of the registration.
4. Open the TARGIT Management client and use these values to configure the Identity Provider on the TARGIT Server.
5. When configured, the URIs for TARGIT Anywhere and TARGIT Server can be obtained (copied) from the Identity Provider, and back in the Azure portal, these two URI must be registered in the Authentication settings.
   
   At this point, TARGIT has in principle been set up to use OpenID authentication. If you don't have any specific Roles and Rights, i.e. if 'Everyone' has full access to everything, then you should be able to log on to TARGIT with a user from the Azure AD. You can perfectly test it in this way, at this point, if you like.
   
   To set up proper Roles and Rights, you will need one more steps:
   
   
6. You will need to add Azure AD group IDs as manual groups to your Roles and Rights. And you will need to activate a Script on the Identity Provider to map the group IDs to the Roles and Rights groups.

Step-by-step guide

With a new installation of TARGIT (2021 version or later), you should be able to follow these instructions step-by-step.

1. TARGIT Management - Public URLs

Before adding an external identity provider, make sure that Public URLs for the TARGIT Server and the Anywhere component are set up correctly. This is done in the TARGIT Management client, in Setup / Back-end:

Note: Replace “localhost” with the correct server name or IP address within your organization. Also note that the Anywhere component (on the IIS) and the TARGIT server are not necessarily installed on the same server.

2. Azure portal - App registration

1. Log on to http://portal.azure.com
2. Locate and click the Azure service called Azure Active Directory:
   
   
   
   
   
3. Go to App registrations and add a New registration:
   
   
   
   
   
4. Give the new registration a proper name (this can be changed later) and click Register:
   
   
   
   

3. Azure portal - Copy ID, Secret etc. from Azure

1. Copy the Application (client) ID and paste it in e.g. Notepad. You will need the ID later:
   
   
   
   
   
2. Go to Certificates and Secrets to add a New client secret (the description can be anything you choose it to be):
   
   Note: The client secret will expire after 24 months. When expired, users won't be able to log in to TARGIT. It is important to create a new secret and replace the old secret before it expires.
   
   
3. Copy the Client Secret Value and paste it in e.g. Notepad. You will not be able to retrieve it later.
   
   
   
   
   
4. Go to Add permissions and Add a permission: Microsoft Graph:
   
   
   
   
   
5. Select Delegated permissions:
   
   
   Note: On-prem solutions works with "Delegated permissions". Select "Application permissions" for Cloud solutions.
   
   
6. Scroll down to Group and put a check mark in Group.Read.All. Finalize with Add permissions:
   
   
   Note: If your TARGIT solution is a TARGIT Cloud solution (as opposed to a TARGIT On-prem solution), you will need to enable permission for User.Read.All as well. Furthermore, read this article for expanded options regarding the OpenID script: https://community.targit.com/hc/en-us/articles/10737339128989-OpenID-script-samples
   
   
7. Go to Manifest.
   Change "groupMembershipClaims": null to "groupMembershipClaims": "All" and Save it:
   
   
   
   
   
8. Go to Overview and Endpoints. Copy the OpenID Connect metadata document and paste it into e.g. Notepad:
   
   
   
   

4. TARGIT Management - Configure Identity Provider

1. Open the TARGIT Management client and go to Security to Configure Identity Providers:
   
   
   
   
   
2. Create a New Identity Provider and start out with Fetch from OpenID Discovery. Paste the saved OpenID Connect metadata document URL into the OpenID field and click Fetch:
   
   
   
   This will pre-fill the Authorization Endpoint and Token Endpoint fields:
   
   
   
   
   
3. Checkmark Active and fill in Client ID and Client Secret from your Notepad copies:
   
   
   Note: The client secret will expire after 24 months. When expired, users won't be able to log in to TARGIT. It is important to create a new secret and replace the old secret before it expires.
   
   - The ID field should be filled in with a name of your own choice. This ID is later used as part of the redirect URIs.
   - Scope has been pre-filled from the previous step.
   - Styling Icon and Name are what the end-user will see on their TARGIT login dialog. You are free to choose your own image and text.
   - Save the Identity Provider settings once all of above has been filled in.
   
   
   
4. Select your newly created Identity Provider and click the See Redirect URIs button:
   
   
   These two URIs are used in the next step to finalize the Azure configuration.
   
   

5. Azure portal - Redirect URIs

1. Go to Authentication, Add a platform: Web.
   
   
   
   
   
2. Paste in the first URI and click Configure:
   
   
   
   
   
3. Add the second URI and click Save:
   
   
   
   

This completes the OpenID configuration on Azure and on the TARGIT Server. You can test it from the Identity Provider in the TARGIT Management Client by clicking the Test button. You will need to provide a username and password (alvarobennett@targitdemo.com / BigBlueWhale22) - and if all goes well, it will succeed:

6. Adding Azure AD Groups as Manual groups, activating Script

1. Log on to the Azure portal, open the Azure Active Directory and go to Groups:
   
   
   
   
2. Copy the Object IDs of the necessary groups:
   
   
   
   
3. Open the TARGIT Management client and go to Roles to add a Manual group to one of your roles:
   
   
   
   
4. Paste the Object ID into the ID field and give the group a proper Name:
   
   
   
5. Likewise, add manual groups to Rights:
   
   
   
   
6. Go back to your Identity provider and Manage Script:
   
   
   
   
7. Do a Test Login (alvarobennett@targitdemo.com / BigBlueWhale22). If succesful, the Tokens, Keys and Values should be filled:
   
   
   
   
8. Copy the following script into the upper half of the Script window:
   Use this script for TARGIT 2023 version or later:
   

   async function interactive_login (idToken) {
       return {
           user_name: idToken["preferred_username"],
           user_id: idToken["sub"],
           user_groups: idToken["groups"]
       };
   }

   Use this script for versions earlier than the TARGIT 2023 version:
   

   async function(idToken) {
       return {
           user_name: idToken["preferred_username"],
           user_id: idToken["sub"],
           user_groups: idToken["groups"]
       };
   }

   Note: If your TARGIT solution is a TARGIT Cloud solution (as opposed to a TARGIT On-prem solution), you should read this article for expanded options regarding the OpenID script: https://community.targit.com/hc/en-us/articles/10737339128989-OpenID-script-samples
   
   
9. Run the script:
   
   
   
   
10. Click the Look up user permissions to verify that the user is mapped to the proper Role(s):
    
    
    
    
    
    
11. Save the Script and close the Management client.

Finally, you can of course try to log on to the TARGIT Windows client with the AD user, using your new OpenID authentication method: