Integration of 3rd party Identity Providers

For Enterprise subscribers TrustSource provides the option to integrate any oAuth capable Identity Provider like Apple, Microsoft AD (Entra) or comparable. This article will introduce you to the general concept and help you to setup the integration on Azure AD side.

The basic idea 

TrustSource is a simple web application. The capabilities the application provides to you highly depend on the role(s) you are assigned to. To get roles granted (authorization) you first will need to identify yourself (authentication). For small teams this could be done simply by joining the members of your team manually and manage all through TrustSource Account UI. For larger organisations this becomes cumbersome and the effort of keeping up with the changes piles up. 

Thus we provide also an integration to external Identity Providers, such as Azure AD or some OID/SAML providers. In this scenario you leave the management of employees/members to the existing procedures and add these internal sources as the identity providers for authentication and authorization. Following diagram lines out the overall architectural design as well as the primary flows. 

(Source: Microsoft Azure Documentation)

In this scenario 

1. the user opens his web browser and
2. navigates to TrustSource app, e.g. https://login.trustsource.io/MYCORP
3. This will automatically redirect the user to its corporate active directory server, which will present a login page.
4. Into this page the user enters his authentication details and sends them back to Azure.
5. Azure verifies the user, ideally using some multi factor authentication, and - if positive - puts his claims (roles) into a secure access token.  In addition the "re-direct-url" is presented  by AD to the browser.
6. The browser now takes the token and presents it to the applications re-direct-url.
7. The web application (TrustSource) verifies the token and - if positive - forwards the user to the application setting his rights according to the claims found in the token.

Given the TrustSource roles are defined in the Security groups of the AD, the user will receive his TrustSource roles accordingly. 

Configure the Azure AD (Entra) Side

In Azure Services go to APP REGISTRATIONS. There select the "New registration" option on the upper left side. You may find additional (and maybe more recent) description in the microsoft help.

In the next screen define a name, best something that will remind you of which external application is addressed with this access. Manke sure, you will select "Accounts in this organisational directory only". If you have a multi-tenant environment, you most likely know, what to do. It will not hurt the integration to select multi-tenant, but you should be sure, that it is required.

Set the Client ID

TrustSource requires a handful of parameters from your solution. Mainly it is a set of IDs we require, so that we may identify the roles and rights you did assign to your users. but before this can happen, we also must ensure, that we can reach and identify your Active Directory. Therefor we need to know the client ID and client Secret of the app you just created in the step before.

Please note this down, you will need the ID later for TrustsSource definition. 

Set the App URLs 

After creating the app, you will have to enter the valid callback URLs. Right next to the "Application (client) ID" you will see the "Redirect URIs" entry. Click on the link and add a Web URL. A dialogue like shown below will appear:  

The URL will contain your TrustSource company ID. In general, you should receive this URL from our support team, given you have a valid subscription. 

However, you may retrieve a list of all endpoints TrustSource is providing for your identity management, call the following URL:

https://idm.trustsource.io/realms/YOUR-COPANY-ID/.well-known/openid-configuration

PLEASE NOTE: This URL will be available not before our Team has setup the realm for your company. This will require, that you ordered the SSO-extension or an Enterprise subscription. Please contact sales (sales@trustsource.io) or your account manager for more details. 

Configure the access tokens

In a next step you will define, what goes in the access token. In the page where you defined the Redirect UR, please ensure to check both: access tokens and ID tokens. TrustSource makes use of both. 

Then proceed to the token configuration. On the lefthand menu select TOKEN CONFIGURATION and create the "groups" entry. Please ensure that spelling is correct. Defining only "group" for example would not succeed.  

The name of the parameter that contains the claims will be used in the role mapping definition on TrustSource side. The default is "groups" . If you select  something different, we need to know that. 

Please also ensure, that "emit groups as role claims" is not set. If you select it, the ids transported will be transported as role. 

Create the required Security Groups

Now it is time to prepare for the rights management. Make sure you selected Security Groups! There are M365 and other groups available. You need to use the Security Groups!  

The object IDs  of these groups need to be available for our (TrustSource) admin to setup the role mapping. Currently TrustSource supports the following roles: 

• Developer (default)
• Manager
• Portfolio Manager
• Compliance Manager
• Account Administrator
• Company Security Manager
• Company Component Manager
• Poweruser 

Finally you need to add your users to one or more of these groups. It i possible to own several roles. Most often roles can be aligned with ranks in companies. But this must not be the case for all roles. , e.g. "Compliance Manager" must not always be a senior manager in your corporate hierarchy.

However, feel free to reach out to your account manager or support, if you feel this is getting complicated. But it is actually simpler, than you may think. 

Question & Answers

Q: Starting from July 14th, my users can't login using the AD anymore. What went wrong?

A: We upgraded the underlying IDM. This comes with a breaking change in the URL pattern. Unfortunately this has been fixed by DEV and not reported as breaking change. Thus, this may lead to "age unknown" issues during login.

To fix this, you will have to remove the /auth part of the defined redirect URL. Follow these steps to get it solved:

1. Login to Azure
2. Select the TrustSource App
3. Go to "Redirect URIs"

4. Modify the URI by removing the /auth segment from the given URL, e.g.

   https://idm.trustsource.io/auth/realms/MY-CORP-ID/broker/oidc/endpoint

   into

5. https://idm.trustsource.io/realms/MY-CORP-ID/broker/oidc/endpoint

6. Save our changes and you are done.