# Single Sign-On with Microsoft Entra ID

{% hint style="info" %}
Entra ID integration requires a Connectware Enterprise license.
{% endhint %}

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.
   * **Kubernetes**: Modify the `values.yaml` file.
   * **Docker**: Modify the `.env` file.
3. Configure Connectware to use Entra ID as the identity provider.

For more information on Microsoft Entra, see the [Microsoft Entra documentation](https://learn.microsoft.com/en-us/entra/).

## Prerequisites

* **License**: Connectware Enterprise license required. For more information, see [cybus.io](https://www.cybus.io/en/product/licenses/).
* **Microsoft Entra admin center**: Access to the Microsoft Entra admin center (<https://entra.microsoft.com>).
* **Configuration**: Access to the Connectware configuration file.
  * **Kubernetes**: Modify the `values.yaml` file.
  * **Docker**: Modify the `.env` file.

{% hint style="warning" %}
[Multi-factor authentication](https://docs.cybus.io/2-0-6/documentation/user-management/multi-factor-authentication) is not available when using Entra ID as your authentication provider.
{% endhint %}

## 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 the Connectware URL that users will be redirected to after authenticating with Entra ID. When configuring Connectware for Entra, you'll set this URI via the `callBackDomain` parameter (Kubernetes) or the `CYBUS_MS_ENTRA_ID_CALLBACK_DOMAIN`parameter (Docker). |

## Connectware Entra ID Parameters

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

{% tabs %}
{% tab title="Kubernetes Parameters" %}

### Kubernetes Entra ID Parameters

| Helm value                                           | Description                                                                                                                                                                                                                                       | Status                                         |
| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
| `global.authentication.entraId.enabled`              | <p>If set to <code>true</code>, Entra ID is enabled. If set to <code>false</code>, Entra ID is disabled.<br><br>Default: <code>false</code><br>Schema type: boolean</p>                                                                           | **Required**                                   |
| `global.authentication.entraId.clientId`             | <p>Your Application (client) ID as provided by Entra ID<br><br>Schema type: string</p>                                                                                                                                                            | **Required**                                   |
| `global.authentication.entraId.tenantId`             | <p>Your Directory (tenant) ID as provided by Entra ID<br><br>Schema type: string</p>                                                                                                                                                              | **Required**                                   |
| `global.authentication.entraId.clientSecret`         | <p>Confidential key (in plain text) for authenticating with Entra ID. <code>clientSecret</code> is ignored if <code>existingClientSecret</code> is defined.<br><br>Schema type: string</p>                                                        | **Required**<mark style="color:red;">\*</mark> |
| `global.authentication.entraId.existingClientSecret` | <p>Name of an existing Kubernetes secret containing the client secret<br><br>Schema type: string</p>                                                                                                                                              | **Required**<mark style="color:red;">\*</mark> |
| `global.authentication.entraId.callbackDomain`       | <p>Specifies the Connectware URL that users will be redirected to after authenticating with their Entra ID credentials<br>Schema type: string</p>                                                                                                 | **Required**                                   |
| `global.authentication.entraId.issuerUrl`            | <p>Identity provider's token issuing URL<br><br>Schema type: string</p>                                                                                                                                                                           | Optional                                       |
| `global.authentication.entraId.usernameMappingField` | <p>User attribute to use as username. If not set, the default value is used.<br><br>Default: <code>preferred\_username</code><br>Allowed values:<code>name</code> , <code>oid</code>, <code>preferred\_username</code><br>Schema type: string</p> | Optional                                       |

{% hint style="danger" %}
\\\* You must provide either \`clientSecret\` or \`existingClientSecret\`. For enhanced security, use \`existingClientSecret\` instead of \`clientSecret\`.
{% endhint %}
{% endtab %}

{% tab title="Docker Parameters" %}

### Docker Entra ID Parameters

| Environment variable                       | Description                                                                                                                                                                                                                                       | Status       |
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ |
| `CYBUS_MS_ENTRA_ID_ENABLED`                | <p>If set to <code>true</code>, Entra ID is enabled. If set to <code>false</code>, Entra ID is disabled.<br><br>Default: <code>false</code><br>Schema type: boolean</p>                                                                           | **Required** |
| `CYBUS_MS_ENTRA_ID_CLIENT_ID`              | <p>Your Application (client) ID as provided by Entra ID<br><br>Schema type: string</p>                                                                                                                                                            | **Required** |
| `CYBUS_MS_ENTRA_ID_TENANT_ID`              | <p>Your Directory (tenant) ID as provided by Entra ID<br><br>Schema type: string</p>                                                                                                                                                              | **Required** |
| `CYBUS_MS_ENTRA_ID_CLIENT_SECRET`          | <p>Confidential key (in plain text) for authenticating with Entra ID. To use the client secret in your <code>.env</code> file, you must encode it to base64.<br><br>Schema type: string</p>                                                       | **Required** |
| `CYBUS_MS_ENTRA_ID_CALLBACK_DOMAIN`        | <p>Specifies the Connectware URL that users will be redirected to after authenticating with their Entra ID credentials<br>Schema type: string</p>                                                                                                 | **Required** |
| `CYBUS_MS_ENTRA_ID_ISSUER_URL`             | <p>Identity provider's token issuing URL<br><br>Schema type: string</p>                                                                                                                                                                           | Optional     |
| `CYBUS_MS_ENTRA_ID_USERNAME_MAPPING_FIELD` | <p>User attribute to use as username. If not set, the default value is used.<br><br>Default: <code>preferred\_username</code><br>Allowed values:<code>name</code> , <code>oid</code>, <code>preferred\_username</code><br>Schema type: string</p> | Optional     |
| {% endtab %}                               |                                                                                                                                                                                                                                                   |              |
| {% endtabs %}                              |                                                                                                                                                                                                                                                   |              |

## Redirect URIs in Microsoft Entra Authentication

When authenticating users, you must configure a redirect URI for Microsoft Entra authorization. This redirect URI serves as a critical security mechanism that ensures authentication codes and tokens reach only their intended destination.

A redirect URI (or response URL) specifies where Microsoft Entra will send users after authenticating with their Entra ID credentials. For Connectware, the redirect URI must point to the endpoint where your Connectware instance is running.

## Configuring Entra ID

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

{% stepper %}
{% step %}

#### 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](#entra-id-information-to-provide-to-connectware).
   * **Application (client) ID**
   * **Directory (tenant) ID**
     {% endstep %}

{% step %}

#### Defining the Redirect URI

You must define a redirect URI (Uniform Resource Identifier). This is the Connectware URL that users will be redirected to after authenticating with their Entra ID credentials. When configuring Connectware for Entra ID in a later step, you will need to enter the redirect URI as the value for the `callBackDomain` parameter (Kubernetes) or the `CYBUS_MS_ENTRA_ID_CALLBACK_DOMAIN` parameter (Docker).

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. This is the Connectware URL that users will be redirected to after authenticating with their Entra ID credentials.
5. Click **Configure**.
6. In the **Implicit grant and hybrid flows** section, activate **ID tokens (used for implicit and hybrid flows)**.
7. Click **Save**.
   {% endstep %}

{% step %}

#### 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.

{% hint style="danger" %}
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.
{% endhint %}
{% endstep %}

{% step %}

#### 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**. Depending on your Entra ID setup, you may need to select **Groups assigned to the application**. This option is recommended for large enterprise companies to avoid exceeding the limit on the number of groups a token can emit. If you are unsure which group type to select, consult your Entra ID administrator.
4. In the **Customize token properties by type** section, click **ID** and select **Group ID**.
5. Click **Add**.
   {% endstep %}
   {% endstepper %}

## 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.

{% hint style="info" %}
During the following update procedure, you need to enter the [Entra ID information](#entra-id-information-to-provide-to-connectware) that you have noted down during the [Entra ID configuration](#configuring-entra-id) in the Microsoft Entra admin center.
{% endhint %}

{% tabs %}
{% tab title="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](#entra-id-information-to-provide-to-connectware) that were provided when [configuring Entra ID](#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](#kubernetes-entra-id-parameters):

{% code lineNumbers="true" %}

```yaml
global:
  authentication:
    entraId:
      enabled: true
      clientId: <your-client-id>
      tenantId: <your-tenant-id>
      existingClientSecret: <your-kubernetes-secret>
      callbackDomain: <your-redirect-uri>
```

{% endcode %}

{% hint style="danger" %}
You must provide either `clientSecret` or `existingClientSecret`. For enhanced security, use `existingClientSecret` instead of `clientSecret`.
{% endhint %}

3. Optional: Customize the username mapping field via the following Helm value:

{% code lineNumbers="true" %}

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

{% endcode %}

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

{% hint style="info" %}
Note: Replace `repository` with your specific repository path where the Connectware Helm chart is stored. The exact command will depend on your specific installation configuration.
{% endhint %}

{% code lineNumbers="true" %}

```yaml
helm upgrade --install connectware <repository>/connectware -f values.yaml
```

{% endcode %}
{% endtab %}

{% tab title="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](#entra-id-information-to-provide-to-connectware) that were provided when [configuring Entra ID](#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](#docker-entra-id-parameters):

{% code lineNumbers="true" %}

```yaml
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-redirect-uri>
```

{% endcode %}

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

{% code lineNumbers="true" %}

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

{% endcode %}

5. After configuring the environment variables, [restart Connectware](https://docs.cybus.io/2-0-6/documentation/installation-and-upgrades/restarting-connectware).

For a list of all environment variables for Docker Compose, see [Docker Compose](https://docs.cybus.io/2-0-6/environment-variables#docker-compose).
{% endtab %}
{% endtabs %}

## Configuring User Groups

This section explains how to configure user group permissions through the [Admin UI](https://docs.cybus.io/2-0-6/getting-started/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.

{% stepper %}
{% step %}

#### 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](#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.
   {% endstep %}

{% step %}

#### 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**.
   {% endstep %}

{% step %}

#### Verifying the Group Setup

* After configuring user groups, make sure to verify the permissions by testing with users from different departments.
  {% endstep %}
  {% endstepper %}

## Signing in with Entra ID

After [Entra ID configuration](#configuring-single-sign-on-with-microsoft-entra-id) 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.

<figure><img src="https://639096190-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfDpOJO2upcq5EpoSahvK%2Fuploads%2Fgit-blob-0984b040b7b4fae79fd4ccf71a52ac4569f246d4%2Fentra-id-login.png?alt=media" alt=""><figcaption></figcaption></figure>

## 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](https://docs.cybus.io/2-0-6/reference/api-reference/api-definition) for user management configurations.