UNIFYConnect Data Configuration

The UNIFYConnect data extensibility configuration is located in %InstallDir%\Services\Extensibility\DataEngine.config.json, and contains all configuration related to how the service connects to the database.

Data Engine configuration

A dataConnection describes a database that UNIFYConnect can connect to. In the default UNIFYConnect configuration, the data connection with the repositoryUnify.IdentityBroker is the active connection, and is required.

SQL Server

{
  "$version": "1.0",
  "dataConnections": [
    {
      "$version": "1.0",
      "name": "sql",
      "repository": "Unify.IdentityBroker",
      "type": "SqlServer",
      "connectionString": "Data Source=LOCALHOST;Initial Catalog=Unify.IdentityBroker;Integrated Security=True",
      "secureConnectionString": null,
      "securePassword": null,
      "enableTransactions": false
    }
  ]
}

For more information on configuring a SQL Server connection string see: http://msdn.microsoft.com/en-us/library/system.data.sqlclient.sqlconnection.connectionstring.aspx

PostgreSQL

{
  "$version": "1.0",
  "dataConnections": [
    {
      "$version": "1.0",
      "name": "postgres",
      "repository": "Unify.IdentityBroker",
      "type": "PostgreSql",
      "connectionString": "Host=;Port=;Database=;Username=;Password=",
      "secureConnectionString": null,
      "securePassword": null,
      "enableTransactions": false
    }
  ]
}

The connectionString attribute can be customised to meet environment-specific requirements. Non-standard connection-string values may cause unintended behaviour. For PostgreSQL connection-string options, see the Npgsql connection-string parameters.

Microsoft Entra authentication

Database authentication defaults to ConnectionString. Existing configurations therefore continue to use the credentials in their connection string without requiring an authentication object.

The optional authentication property was added in schema version 1.1 of each object in dataConnections. Use "$version": "1.1" on connections containing this property. The root object remains at version 1.0, and the new nested authentication object has its own version 1.0. Existing version 1.0 connections without authentication settings remain supported.

For SQL Server, an AKS workload identity data connection can be configured as follows:

{
  "$version": "1.0",
  "dataConnections": [
    {
      "$version": "1.1",
      "name": "sql",
      "repository": "Unify.IdentityBroker",
      "type": "SqlServer",
      "connectionString": "Data Source=<server>.database.windows.net;Initial Catalog=<database>;Encrypt=True;Trust Server Certificate=False",
      "secureConnectionString": null,
      "securePassword": null,
      "authentication": {
        "$version": "1.0",
        "mode": "WorkloadIdentity",
        "tenantId": null,
        "clientId": null,
        "clientSecret": null,
        "tokenFilePath": null
      },
      "enableTransactions": false
    }
  ]
}

For PostgreSQL, specify the database principal in Username. This avoids requiring a token while the shared data source is being initialised and also supports database role names which differ from the identity name.

{
  "$version": "1.0",
  "dataConnections": [
    {
      "$version": "1.1",
      "name": "postgres",
      "repository": "Unify.IdentityBroker",
      "type": "PostgreSql",
      "connectionString": "Host=<server>.postgres.database.azure.com;Port=5432;Database=<database>;Username=<database-principal>;SSL Mode=Require",
      "secureConnectionString": null,
      "securePassword": null,
      "authentication": {
        "$version": "1.0",
        "mode": "WorkloadIdentity",
        "tenantId": null,
        "clientId": null,
        "clientSecret": null,
        "tokenFilePath": null
      },
      "enableTransactions": false
    }
  ]
}

When these authentication values are null, workload identity uses the standard AZURE_TENANT_ID, AZURE_CLIENT_ID, and AZURE_FEDERATED_TOKEN_FILE environment variables injected by Azure Workload Identity. Set tenantId, clientId, or tokenFilePath only when a data connection must override those values. Merge the applicable connection and authentication properties into the existing Extensibility/DataEngine.config.json; do not replace other configured data connections.

The authentication value properties, as well as connectionString, support external configuration value references. The mode property is configured directly. For example:

"connectionString": { "$xref": "database-connection-string" },
"authentication": {
  "$version": "1.0",
  "mode": "WorkloadIdentity",
  "tenantId": { "$xref": "database-tenant-id" },
  "clientId": { "$xref": "database-client-id" },
  "clientSecret": { "$xref": "database-client-secret" },
  "tokenFilePath": { "$xref": "database-token-file-path" }
}

Authentication value references are resolved by the configuration engine when the current JSON configuration is loaded; they are not exposed through a data-configuration editing API.

The available authentication modes are:

Mode	Description
ConnectionString	Uses the connection string unchanged. This is the default and is backwards compatible.
DefaultCredential	Uses DefaultAzureCredential. tenantId and clientId can override the corresponding workload-identity and managed-identity selections.
WorkloadIdentity	Uses WorkloadIdentityCredential. tenantId, clientId, and tokenFilePath are optional overrides. This is the recommended explicit mode for AKS workload identity.
ManagedIdentity	Uses the system-assigned managed identity when clientId is empty, or the user-assigned managed identity identified by clientId.
ClientSecret	Uses an application registration. tenantId, clientId, and clientSecret are required. Store clientSecret using an external configuration value reference, rather than as plain text.

Entra authentication still requires a connection string containing the server and database details. Do not include a password when an Entra mode is selected. For SQL Server, also omit Authentication and Integrated Security from the connection string. For PostgreSQL, specify the database principal with the connection string's Username property when using ClientSecret; it is also recommended for all other Entra modes. The identity must exist as a database principal with the required permissions.

UNIFYConnect creates one reusable credential and database provider per configured repository. PostgreSQL requests a valid token through its password provider when a new physical connection is authenticated, while SQL Server uses a stable access-token callback that is also reused as part of the connection-pool key. Azure Identity caches valid tokens and refreshes them as required, so the data source and connection pools do not retain a single token until it expires and do not make an identity-service request for every database operation.

If PostgreSQL data-source initialisation fails, for example because the projected workload-identity token is not ready during AKS startup, a later database operation retries initialisation instead of retaining the first failure for the lifetime of the process.

Configuration Details

Attributes	Description
name	The connection name. Must be unique, but otherwise does not have any special meaning.
type	The type of database connection. The allowable values are SqlServer, PostgreSql
repository	This is the name of the repository as referred to in other extensibility files. This generally shouldn't be changed, and doesn't need to match your database name.
connectionString	An ADO.NET connection string for the database. For more information on database specific connection strings refer to Connection Strings below.
authentication	Optional Microsoft Entra authentication settings. If omitted, mode defaults to ConnectionString.
enableTransactions	Set to true to allow UNIFYConnect to perform operations for this connection inside transactions. Microsoft Distributed Transaction Coordinator may be used.
securePassword	Reads a password from a secure string, appending it to an existing connection string. Should not be set manually.
secureConnectionString	Reads a connection string from a secure format. Should not be set manually.