- Introduction
- Prerequisites
- General concept of OAuth 2.0 and OpenID Connect
- Azure configuration
- Reltio configuration
- Secure your Postman API requests with SSO
- Troubleshooting
Introduction
In today’s modern data-driven world, businesses rely heavily on platforms like Reltio to manage their information assets. One critical aspect is ensuring secure access and authentication and that is why the adoption of authentication methods such as Single Sign-On (SSO) plays an important role. In this article we are going to focus on OpenID Connect (OIDC) and the integration of Reltio’s platform with OIDC.
The article can also serve as a step-by-step tutorial on how to configure SSO with OIDC in your Reltio tenant including establishing the configuration on Azure’s and Postman’s side.
Prerequisites
Before going through this page, make sure you have:
- an active Azure account with permission to manage applications in Microsoft Entra ID
- an active Reltio account
- Postman downloaded
General concept of OAuth 2.0 and OpenID Connect
OAuth 2.0 is an open standard protocol that ensures highly secure delegated authorization whereas OpenID is an identity layer on top of OAuth that is used for authentication. It is noteworthy to mention here that OAuth is not used for authentication as it does not have a standard way for extracting user information such as username or email.
The purpose of OAuth 2.0 is to grant access to your API endpoint and get access to user data in your targeted systems. The purpose of OpenID Connect is to log the user in and make account data available in the targeted systems.
Let’s look the diagram below that shows OAuth 2.0 and OpenID Connect flow in the context of Reltio:
Notes:
- We are using Authorization code flow as it combines the best from both front and back channels.
- Front channel (in blue) – for example your browser; the less secure channel as sensitive information can be leaked from the browser; used mainly for user interaction – login and consent screens
- Back channel (in red) – highly secure channel, for example private server where communication is established over HTTPs and SSL encryption
- Some terms that we are using and their meaning:
- Resource owner – the user whose data the app wants to access
- Client – the app that asks for the user’s data
- Authorization server – the system to which the users gives permissions for authorization
- Resource server – the API endpoint that the client asks for
- Redirect URI – the place where the authorization server will go back to
- Access token – the access token to use when accessing the resource server
- ID token – JWT token with information on who the authenticated user is
- Scope – what permissions does the client want
Azure configuration
In this section, we are going to look into the steps on how to register a new app in Microsoft Entra ID.
Register new application
- Log in to the Microsoft Azure portal and search for Microsoft Entra ID
- Once you have selected Microsoft Entra ID, click on App registrations on the left panel, under Manage
- Click on the + New registration button and:
- Name section – provide a name for your application, in our case, it will be “Reltio”
- Supported account types section – choose the first option, “Account in this organizational directory only”
- Redirect URI section
- choose “Web” for application type
- for the URI itself, you need to go to Reltio → open a new tab in the browser and go to Reltio Console → SSO configuration → Configure OIDC → Endpoints settings; From the Info panel there, copy the callback endpoint and back in Azure put it in the Redirect URI field
- Click Register and you should land on the Overview page of your app and you should see this:
Client secret
Once, you have registered the new app, you should create a client secret.
Client secret is a secret string used by the application to prove its identity when requesting a token. Sometimes it is referred as an application password.
- Again on the left panel, under Manage, choose Certificates & secrets and click on the + New client secret
- In the Add client secret window, add a proper Description and choose an Expiration for your client’s secret
- Copy Value (client secret) and save it somewhere on your device
- Note: The client’s secret value will be shown only once, immediately after creation. After you leave the page, this value cannot be viewed or copied anymore, so make sure you have saved it
Back on the Overview page, there is an Endpoints tab. If you copy the OpenID Connect metadata document URL, you can find information about all the endpoints that will be needed for our next section – Reltio configuration.
Reltio configuration
In this section, we are going to cover the main aspects of configuring an SSO in Reltio.
This configuration can be created either from the SSO configuration app in Reltio Console or through an HTTP API call. In this article we are going to do it through an API call in Postman. For a step-by-step tutorial on SSO OIDC configuration from the Reltio UI, please refer to Reltio’s documentation portal: SSO Configuration Based on OIDC
Let’s continue with our Postman settings:
First, you should create the following API request:
PUT https://auth.reltio.com/oauth/customers/<Customer_ID>/externalProviderConfig/<Tenant_ID>
Authorization: Bearer <Access_Token>
Content-Type: application/json
In the Body tab, choose raw JSON format, put the following configuration and fill in with your corresponding parameter values:
SSO Configuration
{
"providerId": "azure_<Tenant_ID>",
"vendor": "azure_v2",
"loginEndpoint": "https://login.microsoftonline.com/<Azure_Directory_ID>/oauth2/v2.0/authorize",
"tokenEndpoint": "https://login.microsoftonline.com/<Azure_Directory_ID>/oauth2/v2.0/token",
"userInfoEndpoint": "https://graph.microsoft.com/oidc/userinfo",
"callbackEndpoint": "https://auth.reltio.com/oauth/callback",
"revokeEndpoint": "https://login.microsoftonline.com/<Azure_Directory_ID>/oauth2/v2.0/logout",
"clientId": "<Azure_Client_ID>",
"clientSecret": "<Azure_Client_Secret>",
"scope": "openid profile email User.Read",
"userIdMapping": "email",
"userEmailMapping": "email",
"defaultNewUserRoleList": [],
"tenants": [
"<Tenant_ID>"
],
"jwt": true,
"jwtSignatureConfig": {
"algorithm": "RSA256",
"issuer": "https://login.microsoftonline.com/<Azure_Directory_ID>/v2.0",
"jwksURL": "https://login.microsoftonline.com/<Azure_Directory_ID>/discovery/v2.0/keys"
},
"defaultGroups": [],
"rolePerTenantSsoEnabled": false,
"sendClientCredentialsInBody": false
}
Notes:
- The following parameter values come from Microsoft Azure:
| Reltio setting | Azure setting | |
| Name | Name | Where you can find it |
| Default Settings | ||
| “clientId” | Application (client) ID | Overview page of your app in Microsoft Entra ID |
| “clientSecret” | Client secret Value | This is the value from Step 3 Client secret section above |
| Endpoint Settings | ||
| “loginEndpoint” | authorization_endpoint | OpenID Connect metadata document |
| “revokeEndpoint” | end_session_endpoint | OpenID Connect metadata document |
| “tokenEndpoint” | token_endpoint | OpenID Connect metadata document |
| “userInfoEndpoint” | userinfo_endpoint | OpenID Connect metadata document or Microsoft documentation |
| “issuer” | issuer | OpenID Connect metadata document |
| “jwksURL” | jwks_uri | OpenID Connect metadata document |
- For Vendor we will set “azure_v2”
- When you set up the configuration through Reltio UI, the drop-down menu shows “azure” as an option. Be careful, because this can lead to an error. If you receive an “undefined” error, update this parameter to “azure_v2” in the configuration through the API.
- The Scope parameter is marked as optional, but you will most likely receive an error if you do not configure it (check the Troubleshooting section below). The value that we used is “openid profile email User.Read” and:
- openid – required; indicates that the app uses OIDC to verify the user’s identity
- profile – allows the app to access the End-User’s default profile claims (such as name, nickname, etc.)
- email – allows the app to access the End-User’s email and email_verified claims
- User.Read – allows the app to read the End-User’s profile
- For User email mapping and User ID mapping parameters, we use “email” as a value
- The management of roles and groups is a complex task, so we advise you to manage them inside Reltio as there are Reltio-specific roles that do not exist in Azure and you will have to spend much more time configuring them in Azure first
- JSON Web Token Settings
- It is not mandatory to configure this section. If you do want to configure it though, you should know that the JWT will be verified and decrypted in Reltio Auth server itself. If you leave “jwt” parameter as false – the default value, Reltio Auth server will verify and decrypt the JWT in the SSO provider server.
- Reltio supports only RSA256 algorithm which is used to sign and secure the JWT.
- For SSO configuration for RDM tenant, use the same configuration as above, just put the RDM tenant ID in the “tenants” parameter and in the API request.
Secure your Postman API requests with SSO
There is a possibility to configure Reltio OIDC SSO configuration for Postman for your API requests. Reltio has provided a very useful documentation on this topic – Obtain an Access Token for SSO users. Please, be aware that if you haven’t configured first the OIDC SSO in Reltio, you won’t be able to configure it for Postman itself.
For creating Reltio Client ID and Client Secret, go to the Console App → Client Credentials and follow the steps described here – Add new Client Credentials
For accessing the Client Credentials app, you must have ROLE_ADMIN_CUSTOMER. If you have this role and you still can’t see the app in the Console, use the following link:
https://console.reltio.com/client-credentials?env=<env>&tenant=<MDMTenant>
Troubleshooting
Here is a helpful guide through some of the most common errors that may appear while configuring the SSO OIDC:
Error AADSTS70011: The provided request must include a ‘scope’ input parameter. The provided value for the input parameter ‘scope’ is not valid. The scope email is not valid. openid scope is required.
Fix You didn’t provide a value for your scope parameter for the SSO configuration. Add it through an API request like we showed in our Reltio configuration section above.
Error AADSTS700016: Application with identifier ‘xxx-xxx-xxx’ was not found in the directory ‘your-directory’. This can happen if the application has not been installed by the administrator of the tenant or consented to by any user in the tenant. You may have sent your authentication request to the wrong tenant.
Fix You set the wrong client ID. Go to the Overview tab of your app registration in Microsoft Azure and copy the Application (client) ID.
Error You open the login screen and enter your Microsoft details. You approve the permissions. You receive an error saying just “undefined”.
Fix There are a couple of possibilities that you should investigate before you find the real error:
- Check whether your Reltio email and your Microsoft email are written exactly the same upper/lower case. Reltio is case-sensitive.
- Make sure that you have added “User.Read” in your scope parameter as this reads the Azure’s user information that is needed to be accessed in order for the authorization to be successful.
- Make sure that your “vendor” parameter value is “azure_v2”.
- Make sure that you set your “clientSecret” value every time when you update the configuration.
Error You set up your configuration for your RDM tenant and in the “tenants” section you put the correct “RDM_Tenant_ID”, but it doesn’t update.
Fix Make sure that you have referred to the RDM tenant ID in the API request.
PUT https://auth.reltio.com/oauth/customers/<Customer_ID>/externalProviderConfig/<RDM_Tenant_ID>
Authorization: Bearer <Access_Token>
Content-Type: application/json
