LogoLogo
Contact Uscybus.io
Connectware 1.11.0
Connectware 1.11.0
  • Getting Started
    • Introduction
    • System Requirements
    • Connectware Admin UI
    • Basic Components of Connectware
    • Connecting your First Machine
      • Your First Service Commissioning File
  • Documentation
    • Installation and Upgrades
      • Installing Connectware
        • Installing Connectware (Kubernetes)
        • Installing Connectware (Docker)
      • Upgrading Connectware
        • Upgrading Connectware (Kubernetes)
          • Version-Specific Upgrades (Kubernetes)
        • Upgrading Connectware (Docker)
          • Version-Specific Upgrades (Docker)
      • Uninstalling Connectware
        • Uninstalling Connectware (Kubernetes)
        • Uninstalling Connectware (Docker)
      • Licensing
      • Restarting Connectware
    • User Management
      • Users and Roles View
      • Users
      • Roles
      • Permissions
      • Password Policy Rules
      • Default Admin User
      • MQTT Users
      • Adding a MQTT Publish Prefix for Users
      • Multi-Factor Authentication
      • Single Sign-On (SS0)
        • Single Sign-On with Microsoft Entra ID
        • Single Sign-On with LDAP
      • JSON Web Tokens
      • Access Permissions for Admin-UI
        • UI Access
        • Minimum Access Role Pages
    • Services
      • Service Overview
      • Service Resources View
        • Service Links View
        • Servers View
        • Containers View
        • Volumes View
        • Connections View
        • Endpoints View
        • Mappings View
      • Service Details View
      • Service Commissioning Files
        • Version
        • Description
        • Metadata
        • Parameters
        • Definitions
        • Resources
          • Cybus::Connection
          • Cybus::Container
            • Docker Problem with Network Changes
          • Cybus::Endpoint
          • Cybus::File
          • Cybus::IngressRoute
          • Cybus::Link
          • Cybus:Mapping
          • Cybus::Node
          • Cybus::Role
          • Cybus::Server
          • Cybus::User
          • Cybus::Volume
      • Setting Up and Configuring Services
        • Installing Services
        • Enabling Services
        • Updating Services
        • Disabling Services
        • Deleting Services
      • FlowSync
        • Example 1 - Node with Transaction Mode (HTTP)
        • Example 2 - Node Responds (HTTP)
        • Example 3 - Node with Error (HTTP)
        • Example 4 - Node with Timeout Error Code and Error Message (HTTP)
        • Example 5 - Full Transactional Data Flow (HTTP)
        • Example 6 - Full Transactional Data Flow (OPC UA)
      • ServiceID
      • Inter-Service Referencing
      • Deviations
      • Service Logs
        • Logs of Individual Services
        • Logs of All Services
      • Rule Engine
        • Data Processing Rules
        • Rule Sandbox
      • Shared Subscriptions
        • Setting Up Shared Subscriptions
    • Agents
      • Agents View
      • Installing Agents
        • Installing Agents via Docker
        • Installing Agents via Docker Compose
        • Installing Agents via Kubernetes
        • Using Mutual TLS for Agents
      • Registering Agents in Connectware
      • Using Agents
      • Monitoring Agents
      • Agents in Kubernetes
        • Adding Agents Inside your Connectware Installation
        • Remote Agents with the connectware-agent Helm Chart
        • Kubernetes Cluster Requirements for the connectware-agent Helm Chart
        • Installing Connectware Agents using the connectware-agent Helm Chart
        • Installing Connectware Agents without a License Key Using the connectware-agent Helm Chart
        • Upgrading the connectware-agent Helm Chart
        • Uninstalling Connectware agents with the connectware-agent Helm chart
        • Configuration Principles for the connectware-agent Helm Chart
        • Configuring Agents with the connectware-agent Helm Chart
          • Configuring Target Connectware for the connectware-agent Helm Chart
          • Configuring Agent Persistence for the connectware-agent Helm Chart
          • Configuring Compute Resources for the connectware-agent Helm Chart
          • Using a Custom Image Registry for the connectware-agent Helm Chart
          • Configuring Image Pull Policy for the connectware-agent Helm Chart
          • Using Mutual Transport Layer Security (mTLS) for agents with the connectware-agent Helm chart
          • Configuring image name and version for the connectware-agent Helm chart
          • Configuring Environment Variables for the connectware-agent Helm Chart
          • Configuring Labels and Annotations for the connectware-agent Helm Chart
          • Configuring podAntiAffinity for the connectware-agent Helm Chart
          • Assigning Agents to Kubernetes Nodes for the connectware-agent Helm Chart
          • Configuring Security Context for the connectware-agent Helm Chart
          • Controlling the Name of Kubernetes Objects for the connectware-agent Helm Chart
      • Troubleshooting Agents
    • Client Registry
      • Implicit Flow
      • Explicit Flow
      • Granting Access
    • Certificates
      • Certificates View
      • Adding Certificates
      • Removing Certificates
    • Monitoring
      • Data Explorer
      • Live Data
    • Node-RED Workbench
    • System Status
      • Info
      • Metrics
      • Status
      • Retrieving More System Information
      • System Health
    • Backup and Restore
      • Volumes
      • User Database
    • CybusMQ
      • Configuring CybusMQ
    • Connectware on Kubernetes
      • Connectware Helm Chart
      • Resizing Broker Volumes in Kubernetes
      • Configuring Core Services
      • LDAP Authentication
        • Configuring LDAP Authentication
        • Enabling TLS for LDAP Authentication
        • Manual Kubernetes Secret for LDAP Authentication Bind User
        • Customizing the Search Filter for LDAP Authentication
        • Customizing the User RDN for LDAP Authentication
      • Troubleshooting Connectware on Kubernetes
    • Environment Variables
    • Industry Protocol Details
      • ADS
        • ADS Connection Properties
        • ADS Endpoint Properties
      • BACnet
        • BACnet Connection Properties
        • BACnet Endpoint Properties
      • Custom Connectors
        • Developing Custom Connectors
        • Deploying Custom Connectors
        • Using Custom Connectors
      • EtherNet/IP
        • EtherNet/Ip Connection Properties
        • EtherNet/Ip Endpoint Properties
      • FOCAS
        • FOCAS Connection Properties
        • FOCAS Endpoint Properties
      • Hottinger Baldwin Messtechnik (HBM)
        • HBM Connection Properties
        • HBM Endpoint Properties
      • Heidenhain DNC
        • Heidenhain DNC Connection Properties
        • Heidenhain DNC Endpoint Properties
      • HTTP/REST
        • HTTP/REST Connection Properties
        • HTTP/REST Endpoint Properties
      • HTTP Server/Node
        • HTTP Server Properties
        • HTTP Node Properties
      • InfluxDB
        • InfluxDB Connection Properties
        • InfluxDB Endpoint Properties
      • Kafka
        • Kafka Connection Properties
        • Kafka Endpoint Properties
      • Modbus/TCP
        • Modbus/TCP Connection Properties
        • Modbus/TCP Endpoint Properties
      • MQTT
        • MQTT Connection Properties
        • MQTT Endpoint Properties
      • MSSQL
        • Mssql Connection Properties
        • Mssql Endpoint Properties
      • OPC DA
        • OPC DA Connection Properties
        • OPC DA Endpoint Properties
      • OPC UA
        • OPC UA Client
          • OPC UA Client Connection Properties
          • OPC UA Client Endpoint Properties
        • OPC UA Server
          • OPC UA Server Properties
          • OPC UA Node Properties
        • OPC UA Object Types
        • OPC UA Server References
          • OPC UA Reference Node
          • OPC UA Object Node
      • Siemens SIMATIC S7
        • Siemens S7 Connection Properties
        • Siemens S7 Endpoint Properties
      • Shdr
        • Shdr Connection Properties
        • Shdr Endpoint Properties
      • SINUMERIK
        • SINUMERIK Connection Properties
        • SINUMERIK Endpoint Properties
      • SOPAS
        • SOPAS Connection Properties
        • SOPAS Endpoint Properties
      • SQL
        • SQL Connection Properties
        • SQL Endpoint Properties
      • Werma WIN Ethernet
        • Werma WIN Ethernet Connection Properties
        • Werma WIN Ethernet Endpoint Properties
      • Systemstate
        • Systemstate Endpoint Properties
    • API Reference
      • User Management (API)
      • Client Registry (API)
      • Services (API)
      • Resources (API)
      • System Status (API)
      • Resource Status Tracking (HTTP API)
      • Industry Protocol Details (API)
    • Changelog
Powered by GitBook
LogoLogo

Cybus

  • Terms and Condition
  • Imprint
  • Data Privacy

© Copyright 2025, Cybus GmbH

On this page
  • Configuring Single Sign-On with Entra ID
  • Prerequisites
  • Entra ID Information to Provide to Connectware
  • Connectware Entra ID Parameters
  • Redirect URIs in Microsoft Entra Authentication
  • Configuring Entra ID
  • Configuring Connectware to Support Entra ID
  • Configuring User Groups
  • Signing in with Entra ID
  • Configuring Entra ID in Connectware via API

Was this helpful?

  1. Documentation
  2. User Management
  3. Single Sign-On (SS0)

Single Sign-On with Microsoft Entra ID

PreviousSingle Sign-On (SS0)NextSingle Sign-On with LDAP

Last updated 14 days ago

Was this helpful?

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.

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

Prerequisites

  • License: Connectware Enterprise license required. For more information, see .

  • Microsoft Entra admin center: Access to the Microsoft Entra admin center ().

  • Configuration: Access to the Connectware configuration file.

    • Kubernetes: Modify the values.yaml file.

    • Docker: Modify the .env file.

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_DOMAINparameter (Docker).

Connectware Entra ID Parameters

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

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 URL that users will be redirected to after authenticating with their Entra ID credentials 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 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 URL that users will be redirected to after authenticating with their Entra ID credentials 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

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.

1

Registering Connectware in Entra ID

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

  2. Click New registration.

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

  4. Click Register.

    • Application (client) ID

    • Directory (tenant) ID

2

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.

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.

Entra ID Configuration for Kubernetes

  1. Open the values.yaml file.

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

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 Helm value:

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:

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.

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

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.

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

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.

  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

  • 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

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

Go to the Microsoft Entra admin center () and log in.

In the Overview section, note down the following values. You will need these values for configuring your Connectware setup. For more information, see .

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

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

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

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

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 :

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

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

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

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 for user management configurations.

Microsoft Entra documentation
cybus.io
https://entra.microsoft.com
Multi-factor authentication
https://entra.microsoft.com
API Definition
Entra ID Information to Provide to Connectware
Entra ID information
Entra ID configuration
Entra ID information
configuring Entra ID
Kubernetes Entra ID Parameters
Entra ID information
configuring Entra ID
Docker Entra ID Parameters
Configuring Roles in Connectware
Entra ID configuration
Docker Compose