Single Sign-On with Microsoft Entra ID

Entra ID integration requires a Connectware Enterprise license.

You can configure Microsoft Entra ID (formerly Azure Active Directory) as the identity provider for single sign-on in Connectware.

Configuring Single Sign-On with Entra ID

In order to set up single sign-on with Entra ID, you must complete the following tasks:

1. Configure Entra ID in the Microsoft Entra admin center for Connectware authentication.

2. Update the Connectware configuration with the Entra ID information.

   • For Kubernetes setups, modify your values.yaml file.

   • For Docker setups, modify your .env file.

3. Configure Connectware to use Entra ID as the identity provider.

For more information on Microsoft Entra, see the Microsoft Entra documentation.

Prerequisites

• Connectware Enterprise license required. For more information, see cybus.io.

• Access to the Microsoft Entra admin center (https://entra.microsoft.com).

• Access to the Connectware configuration file.

  • If you're running Connectware on Kubernetes, you must update your values.yaml file.

  • If you're running Connectware on Docker, you must update your .env file.

Multi-factor authentication is not available when using Entra ID as your authentication provider.

Entra ID Information to Provide to Connectware

When configuring Entra ID, you will obtain the following information that you must note down for configuring the Entra ID setup in Connectware at a later stage of the setup procedure.

Information	Description
Application (client) ID	The application (client) ID in Entra ID is a unique identifier that is assigned to Connectware when you register it in Entra ID. It is used to identify Connectware to Entra ID when users sign in.
Directory (tenant) ID	The directory (tenant) ID in Entra ID is a unique identifier that represents your organization's directory instance.
Client secret	The client secret in Entra ID is a confidential key that Connectware uses together with the Application (client) ID to authenticate itself with Entra ID when requesting tokens.
Redirect URI	A URI (Uniform Resource Identifier) that specifies where users should be redirected after authenticating with Entra ID. In Connectware's configuration, you'll use this URI as the callBackDomain parameter.

Connectware Entra ID Parameters

Configure the following environment variables to enable Entra ID authentication. Parameters differ between Kubernetes and Docker deployments.

Kubernetes Parameters

Kubernetes Entra ID Parameters

Helm value	Description	Status
global.authentication.entraId.enabled	If set to true, Entra ID is enabled. If set to false, Entra ID is disabled. Default: false Schema type: boolean	Required
global.authentication.entraId.clientId	Your Application (client) ID as provided by Entra ID Schema type: string	Required
global.authentication.entraId.tenantId	Your Directory (tenant) ID as provided by Entra ID Schema type: string	Required
global.authentication.entraId.clientSecret	Confidential key (in plain text) for authenticating with Entra ID. clientSecret is ignored if existingClientSecret is defined. Schema type: string	Required*
global.authentication.entraId.existingClientSecret	Name of an existing Kubernetes secret containing the client secret Schema type: string	Required*
global.authentication.entraId.callbackDomain	Specifies the Connectware domain where users will be redirected after authenticating through Entra ID Schema type: string	Required
global.authentication.entraId.issuerUrl	Identity provider's token issuing URL Schema type: string	Optional
global.authentication.entraId.usernameMappingField	User attribute to use as username. If not set, the default value is used. Default: preferred_username Allowed values:name , oid, preferred_username Schema type: string	Optional

* You must provide either clientSecret or existingClientSecret. For enhanced security, use existingClientSecret instead of clientSecret.

Docker Parameters

Docker Entra ID Parameters

Environment variable	Description	Status
CYBUS_MS_ENTRA_ID_ENABLED	If set to true, Entra ID is enabled. If set to false, Entra ID is disabled. Default: false Schema type: boolean	Required
CYBUS_MS_ENTRA_ID_CLIENT_ID	Your Application (client) ID as provided by Entra ID Schema type: string	Required
CYBUS_MS_ENTRA_ID_TENANT_ID	Your Directory (tenant) ID as provided by Entra ID Schema type: string	Required
CYBUS_MS_ENTRA_ID_CLIENT_SECRET	Confidential key (in plain text) for authenticating with Entra ID. To use the client secret in your .env file, you must encode it to base64. Schema type: string	Required
CYBUS_MS_ENTRA_ID_CALLBACK_DOMAIN	Specifies the Connectware domain where users will be redirected after authenticating through Entra ID Schema type: string	Required
CYBUS_MS_ENTRA_ID_ISSUER_URL	Identity provider's token issuing URL Schema type: string	Optional
CYBUS_MS_ENTRA_ID_USERNAME_MAPPING_FIELD	User attribute to use as username. If not set, the default value is used. Default: preferred_username Allowed values:name , oid, preferred_username Schema type: string	Optional

Configuring Entra ID

This section guides you through the required configuration steps in the Microsoft Entra admin center.

1

Registering Connectware in Entra ID

1. Go to the Microsoft Entra admin center (https://entra.microsoft.com) and log in.

2. In the sidebar, select Identity > Applications > App registrations.

3. Click New registration.

4. Enter the Name of your registration. For example, connectware.

5. Click Register.

6. In the Overview section, note down the following values. You will need these values for configuring your Connectware setup. For more information, see Entra ID Information to Provide to Connectware.

   • Application (client) ID

   • Directory (tenant) ID

2

Defining the Redirect URI

You must define a redirect URI (Uniform Resource Identifier) that the user is redirected to after entering the Entra ID credentials. This redirect URI will be used later in the configuration process as the value for the callBackDomain parameter in Connectware's Entra ID setup.

1. Click Authentication.

2. In the Platform configurations section, click Add platform.

3. In the Configure platforms section, click Web.

4. In the Redirect URIs field, enter your redirect URI. For example, https://<baseUrl>/api/msEntraId/redirect.

5. Click Configure.

6. In the Implicit grant and hybrid flows section, activate ID tokens (used for implicit and hybrid flows).

7. Click Save.

3

Creating Client Secrets

Credentials enable confidential applications to identify themselves to the authentication service when receiving tokens at a web addressable location.

1. Click Certificates & secrets.

2. In the Client secrets section, click New client secret.

3. In the Add a client secret section, enter a description and the expiration time period.

4. Click Add.

5. Note down the client secret key displayed in the Value column.

After initial setup, you cannot see the client secret key. If you did not record the client secret key, you must generate a new one.

4

Changing the Token Configuration

You must configure optional claims in Entra ID. Optional claims are used to configure additional information which is returned in one or more tokens.

1. Click Token configuration.

2. In the Optional claims section, click Add groups claim.

3. In the Select group types section, select your group type. We suggest to use Security groups.

4. In the Customize token properties by type section, click ID and select Group ID.

5. Click Add.

Configuring Connectware to Support Entra ID

This section shows you how to update your Connectware configuration files to integrate with Entra ID.

To use Entra ID with a new Connectware installation or with your existing Connectware setup, you must update your Connectware configuration file. The update procedure depends on your current installation method.

• If you're running Connectware on Docker, you must update your .env file.

• If you're running Connectware on Kubernetes, you must update your values.yaml file.

During the following update procedure, you need to enter the Entra ID information that you have noted down during the Entra ID configuration in the Microsoft Entra admin center.

Kubernetes Configuration

Entra ID Configuration for Kubernetes

1. Open the values.yaml file.

   • Now you must configure the helm file to enable Entra ID. For this, you need the Entra ID information that were provided when configuring Entra ID.

2. Configure the following helm values to enable and configure Entra ID. For a list of all Kubernetes Entra ID parameters, see Kubernetes Entra ID Parameters:

global:
    authentication:
        entraId:
            enabled: true
            clientId: <your-client-id>
            tenantId: <your-tenant-id>
            existingClientSecret: <your-kubernetes-secret>
            callbackDomain: <your-callback-domain>

You must provide either clientSecret or existingClientSecret. For enhanced security, use existingClientSecret instead of clientSecret.

1. Optional: Customize the username mapping field via the following environment variable:

global:
    authentication:
        entraId:
            enabled: true
            # Specify custom field mappings (optional)
            usernameMappingField: <mapping-fields>

1. After configuring your values.yaml file, deploy or update Connectware using the following command:

helm upgrade --install  connectware cybus/connectware -f values.yaml

Docker Configuration

Entra ID Configuration for Docker

1. Navigate to your Connectware installation directory. If you have used the default values during installation, this is the installation folder: /opt/connectware. The directory contains an .env file that is loaded when starting Connectware.

2. Open the .env file.

   • Now you must configure the .env file to enable Entra ID. For this you need the Entra ID information that were provided when configuring Entra ID.

3. Configure the following environment variables to enable and configure Entra ID. Make sure that you have encoded your client secret as base64. For a list of all Docker Entra ID parameters, see Docker Entra ID Parameters:

environment:
    # Enable Entra ID authentication
    CYBUS_MS_ENTRA_ID_ENABLED=true

    # Entra ID application credentials
    CYBUS_MS_ENTRA_ID_CLIENT_ID=<your-client-id>
    CYBUS_MS_ENTRA_ID_CLIENT_SECRET=<your-client-secret-encoded-as-base64>
    CYBUS_MS_ENTRA_ID_TENANT_ID=<your-tenant-id>

    # Authentication callback URL
    CYBUS_MS_ENTRA_ID_CALLBACK_DOMAIN=<your-callback-domain>

1. Optional: Customize the user name mapping field via the following environment variable:

environment:
    # Specify custom field mappings (optional)
    CYBUS_MS_ENTRA_ID_USERNAME_MAPPING_FIELD=<mapping-fields>

1. After configuring the environment variables, restart Connectware by running docker compose up -d in your installation directory.

For a list of all environment variables for Docker Compose, see Docker Compose.

Configuring User Groups

This section explains how to configure user group permissions through the Connectware admin UI.

In order to use user groups with Entra ID, you must create user groups in the Microsoft Entra admin center that match their intended Connectware roles. These groups enable role synchronization between Entra ID and Connectware, ensuring users have appropriate permissions when accessing the system.

You can create flexible mappings between Entra ID groups and Connectware roles through a many-to-many relationship:

• You can assign a single Entra ID group to multiple Connectware roles

• You can link a single Connectware role to multiple Entra ID groups

Example: For Connectware, you want to give your IT department admin permissions and your engineering department restricted permissions. In Entra ID, you have defined the groups it and engineering. In Connectware, you then assign the it ID to the connectware-admin role and the engineering ID to the minimum-access role. Now, when someone from the IT department logs into Connectware, the Connectware admin permissions are granted. If someone from engineering logs into Connectware, minimum access permissions are granted.

1

Creating Groups in Entra ID

You can create new groups in Entra ID for each Connectware role that you need. Changes in Entra ID group membership are reflected in Connectware upon next user login.

If you already have existing groups in Entra ID that you want to use with Connectware, you can skip this section and proceed to Configuring Roles in Connectware.

1. In the Microsoft Entra admin center, select Identity > Groups > Overview.

2. Click New group.

3. Enter a Group type, Group name, and Membership type.

4. Click Create.

5. Repeat these steps for each group that you need to create for your Connectware roles.

2

Configuring Roles in Connectware

1. In Connectware, click User on the navigation panel.

2. Select the Roles tab.

3. Click the role that you want to synchronize with an Entra ID group.

4. In the Edit Role dialog, enter the ID of the Entra ID group in the ObjectID of Entra field and press Enter. To link multiple Entra ID groups to a role, enter the group IDs of the Entra ID groups as a comma-separated list without spaces. Example: id-1,id-2,id-3

5. Click Update.

3

Verifying the Group Setup

• After configuring user groups, make sure to verify the permissions by testing with users from different departments.

Signing in with Entra ID

After Entra ID configuration is complete, you can access Connectware using your Entra ID credentials.

• To log in with your Entra ID login, click Sign in with Entra ID on the Connectware login screen.

Configuring Entra ID in Connectware via API

Besides configuring Entra ID via the Connectware UI, you can also configure Entra ID in Connectware via the Connectware API. For more information, see the API Definition for user management configurations.