Configure SSO

Overview of SSO for CluedIn

SSO for CluedIn can be enabled in one of the following modes:

SSO with local CluedIn role membership management – all users from the directory can sign in to the CluedIn application. After the user signs in for the first time, CluedIn roles can be assigned in the usual way in the CluedIn UI.
SSO with Azure AD group-managed role membership – Azure AD application roles are created within your Azure application registration and they can be mapped to your AD groups or users. This mode requires Automatic Role Synchronization to be enabled in the Administration Settings page in CluedIn.

Configuring SSO for CluedIn using Azure AD involves three main steps:

Register an application in the Azure portal
Create Kubernetes secret and enable SSO via Helm
(Optional) Create custom role mappings

Important! Before configuring SSO, make sure that you have configured DNS and TLS.

Register an application in the Azure portal

Registering your application establishes a trust relationship between your application and the Microsoft identity platform. The trust is unidirectional: your application trusts the Microsoft identity platform, and not the other way around. After you create the application, it cannot be moved between different tenants.

To register an application in the Azure portal

In the Azure portal, go to the tenant in which you want to register the application.
Search for and select Azure Active Directory.
Under Manage, select App registrations > New registration.
Enter a display Name for your application.
Select the account types that can use the application.
Select Register.
When the registration finishes, the Azure portal displays the Overview pane of the application registration. Here you can see the Application (client) ID. This value uniquely identifies your application. You’ll need it to enable SSO via Helm.

After you register the application, complete the following steps:

Create a client secret
Add redirect URIs
Add API permissions
Expose an API
Map Azure AD application roles to CluedIn roles

Create a client secret

A client secret is used to configure CluedIn to communicate with your Azure AD.

To create client secret

In the Azure portal, in App registrations, select your application.
Select Certificates & secrets > Client secrets > New client secret.
Add a description for your client secret and an expiration date.
Select Add.
Copy and save Value and the Secret ID because they will be used later in your CluedIn Helm configuration.

For more information about the client secret, see Microsoft documentation.

Add redirect URIs

Redirect URI is the location to which the Microsoft identity platform redirects the user’s client and sends security tokens after authentication.

To add redirect URIs

In the Azure portal, in App registrations, select your application.
Select Authentication > Add a platform.
In the right pane, select Web.
In the Configure Web pane, specify the following:
1. In Redirect URIs, add a redirect URI for your application (for example, https://app.yourdomain.com).
2. In Front channel logout URI, add a logout URL for your application (for example, https://app.yourdomain.com/logout).
3. In the Implicit grant and hybrid flows section, select the ID tokens checkbox, and then select Configure.
In the Platform configurations section, in Web, add additional URIs (for example, https://departmentX.yourdomain.com, https://app.yourdomain.com/auth/signin-oidc).
At the bottom of the page, select Save.

For more information about redirect URIs, see Microsoft documentation.

Add API permissions for Microsoft Graph

When you register an application in the Azure portal, the Microsoft Graph API with the User.Read permission is added automatically. You need to add additional permissions for Microsoft Graph.

To add API permissions for Microsoft Graph

In the Azure portal, in App registrations, select your application.
Select API permissions.
In the Configured permissions section, select Microsoft Graph.
In the right pane, select the following permissions: email, offline_access, openid, and profile. At the bottom of the pane, select Update permissions. The API permissions for Microsoft Graph are updated.

For more information about API permissions, see Microsoft documentation.

Expose an API

You need to register a web API with the Microsoft identity platform and expose it to the client app by adding a scope. By registering your web API and exposing it through scope, you can provide permissions-based access to authorized users that access your API.

To expose the API

In the Azure portal, in App registrations, select your application.
Select Expose an API.
In the Scopes defined by this API section, select Add a scope.
Specify the following scope attributes:
- Scope name – https://www.cluedin.net/sso/user_impersonation
- Who can consent – Admins and Users
- Authorized client applications – https://www.cluedin.net/sso/user_impersonation

For detailed instructions on how to configure an app to expose web API, see Microsoft documentation.

Map Azure AD application roles to CluedIn roles

After you have created your application registration and attached it to your CluedIn instance, you can create the application roles on the Azure AD side. These roles will be translated into the CluedIn platform roles and assigned to the users after they sign in to the application for the first time.

To map Azure AD application roles to CluedIn roles

In the Azure portal, in App registrations, select your application.
Select App roles.
On the menu, select Create app role.
Enter the details of the role. See CluedIn roles for recommended values.
Select Apply to save your changes. The role is added to the App roles list.
Repeat steps 3-5 to add all roles.

In the CluedIn application, you can find all CluedIn roles by navigating to Administration > Roles.

Any changes made in the application registration will be saved in your Azure subscription. We do not impose strict requirements on how app roles are set up, so you can follow your organization’s internal requirements.

CluedIn roles

The following table provides a list of the CluedIn application roles and recommended values to use when creating your Azure app roles with your application registration.

Display name	Value	Description
Data Governance Administrator	DataGovernanceAdministrator	Role responsible for approving changes made by Data Governance users
Data Compliance	DataCompliance	Role responsible for daily operations around data compliance
Data Steward	DataSteward	Role dedicated to cleaning data using Clean and Prepare modules
Data Compliance Administrator	DataComplianceAdministrator	Role responsible for approving changes made by Data Compliance users
Admin	Admin	Administrator for the whole system
Guest	Guest	Guest User with minimal, read-only permissions
User	User	User who can view all modules as read-only
Data Architect	DataArchitect	Role responsible for designing an Organizations enterprise data strategy
Deduplication Reviewer	DeduplicationReviewer	Role responsible for reviewing Deduplication Project results and approving the groupings
Organization User	OrganizationUser	User within an Organization who can view all modules as read-only
Data Governance	DataGovernance	Role responsible for monitoring and maintaining data quality
Report Manager	ReportManager	User who can generate reports for compliance matters such as breach, subject request, and retention
Organization Admin	OrganizationAdmin	Administrator within the Organization
Deduplication Administrator	DeduplicationAdministrator	Role responsible for creating and maintaining Deduplication Projects and merging the results back into the system
Data Steward Administrator	DataStewardAdministrator	Role responsible for approving changes made by Data Stewards

Create Kubernetes secret and enable SSO via Helm

After you complete the Azure application registration and app roles configuration, you need to enable the SSO feature on the CluedIn platform. Thus, SSO will become available to users when signing in to CluedIn.

Prerequisites

You should be comfortable working in either PowerShell or bash terminal via Azure Cloud Shell.
You should be connected to your AKS cluster.
See Connect to CluedIn cluster for detailed instructions.
Your Helm repository is set up.

If you have any questions, you can request CluedIn support by sending an email to support@cluedin.com (or reach out to your delivery manager if you have a committed deal).

Once you have connected to your cluster and you are able to issue commands using kubectl and Helm, complete the following procedure to enable SSO for CluedIn.

To create Kubernetes secret and enable SSO via Helm

Create a new Kubernetes secret with your Azure app registration secret by running the following command:
```
kubectl create secret generic "myorg-sso-cs" -n cluedin --from-literal=clientSecret="1234-5678-9ABC"
```
In the command, replace 1234-5678-9ABC with your Azure app registration secret.
In Azure Cloud Shell, run the following command to create a new empty file:
```
nano Cluedin-SSO-Config.yaml
```

In the file, paste the following configuration:

apiVersion: api.cluedin.com/v1
kind: Feature
metadata:
  name: myorg-sso
spec:
  enableSso:
 clientId: "0cXXXX-XXXX-XXXX-XXX-XXXXXX575"
 organizationName: "myorg"
 clientSecretName: "myorg-sso-cs"
 clientSecretKey: "clientSecret"

Change the name and organizationName values to match your CluedIn organization/tenant name.
Change the clientId value to the client ID from your Azure app registration.
Save the file.
Apply your SSO configuration by running the following command in Azure Cloud Shell:
```
kubectl apply -n cluedin -f Cluedin-SSO-Config.yaml
```
Verify that the SSO feature has been enabled successfully by running the following command in Azure Cloud Shell:
```
kubectl get features -n cluedin
```

If your SSO feature has been successfully applied, you should see something similar to the screenshot below.

If the Phase is not in the Active state, wait for 5 minutes and run the command again. If nothing changes, reach out to CluedIn support at support@cluedin.com for help in enabling your SSO.

(Optional) Create custom role mapping

After the app roles have been created, gain access to CluedIn’s internal SQL Authentication database and begin mapping CluedIn roles to app roles.

To create custom role mapping

Gain access to the internal database using Kubernetes port forwarding capability. You need to complete this process on a PC/server where you have access to a SQL client application. You will need it to query and execute SQL commands.
Use the following server address in your SQL client application: 127.0.0.1\mcr.microsoft.com/mssql/server,1433.
Alternatively, you can request CluedIn support by sending an email to support@cluedin.com or reach out to your delivery manager.

Use the following SQL insert statement (or populate the values manually by editing the table).

USE [DataStore.Db.Authentication]
INSERT INTO [dbo].[SingleSignOnRoleMappings] (Id, SingleSignOnId, RoleId, MappedTo)
VALUES ('<single sign on id>', '<cluedin role id>', '<app role value field>')

Replace the following values:
- single sign on id – corresponds to the Id column in the SingleSignOn table.
- cluedin role id – corresponds to the Id column in the AspNetRoles table.
- app role value field – corresponds to the Value assigned in your app role in App Registration.

The following example shows the mapping of OrganizationAdmin CluedIn role to CluedIn App Admin AD app role.