ELO Docs
 ELO Sync

# Service configuration

This section describes how to configure the ELO Sync service either using the appsettings.json and appsettings.Production.json files in the local installation or by changing the user settings stored in the ELO repository.

We recommend copying the supplied appsettings.json file into a new file appsettings.Production.json during installation and updating the settings accordingly.

As the appsettings.Production.json file is never added to the distributed package, it is never overwritten during updates.

For technical reasons, some settings must be configured in the appsettings.json file and cannot be changed in the web interface or the REST API.

Each section always contains an example that describes the individual section within the complete file. If you want to combine several sections, you must omit the outer brackets.

Example:

{
  "Key": {            // First line to be copied
    "MySetting": 42
  }                   // Last line to be copied
}

The sections are listed in alphabetical order for easier navigation.

# AllowedHosts

This configuration setting defines the host filtering (opens new window) that is used by the built-in Kestrel server.

{
  "AllowedHosts": "*"
}

# AzureAd

This section contains the settings for the (static) app registration in Microsoft Azure. The Azure settings can also be defined in the ELO repository, see Configuration stored in the ELO repository.

{
  "AzureAd": {
    // The Entra ID endpoint used for authentication must be changed for national cloud deployments.
    "Instance": "https://login.microsoftonline.com/",
    // The domain name under which this application is registered
    "Domain": "mydomain.onmicrosoft.com",
    // The application (client) ID of the registered application
    "ClientId": "00000000-0123-0123-0123-c0ffeec0ffee",
    // The tenant ID of the registered application
    "TenantId": "c0ffee00-0123-4567-4567-000000000000",
    // The client secret used for authentication
    "ClientSecret": "SecretGeneratedByAzure",
    // The callback path used for the OAuth Redirect results
    "CallbackPath": "/signin-oidc-custom",
    // Client certificate(s) used for authentication.
    "ClientCertificates": [
      {
        // The properties used to read the certificate must have one of the following values:
        // "Path" - The private key of the certificate is stored in a local file, optionally encrypted
        //          The properties "CertificateDiskPath" and "CertificatePassword" should be set
        // "StoreWithThumbprint" - The private key is stored in a Windows certificate store; the certificate is identified by its thumbprint.
        //          The properties "CertificateStorePath" and "CertificateThumbprint" should be set.
        // "StoreWithDistinguishedName" - The private key is stored in a Windows certificate store; the certificate is identified by distinguished name.
        //          The properties "CertificateStorePath" and "CertificateDistinguishedName" should be set.
        "CertificateSource": "Path",
        // Path to the certificate store
        "CertificateStorePath": "CurrentUser/My",
        // Certificate thumbprint
        "CertificateThumbprint": "0123456789abcdef",
        // Certificate distinguished name
        "CertificateDistinguishedName": "MyCertificateName",
        // Password for decrypting the certificate
        "CertificatePassword": "MySecretPassword",
        // Path to the certificate file
        "CertificateDiskPath": "C:\\path\\to\\certificate.pfx"
      }
    ]
  }
}

# ConnectionStrings

This section contains the connection strings used by the various database providers.

Only the connection string of the configured database provider must be set.

{
  "ConnectionStrings": {
    "Sqlite": "Data Source=mysyncdb.db",
    "Postgres": "User ID=myUsername;Password=myPassword;Server=mydbserver;Port=5432;Database=MySyncDb;Include Error Detail=true;",
    "Oracle": "Data Source=MySyncDb;User Id=myUsername;Password=myPassword;Integrated Security=no;",
    "MsSql": "Server=mydbserver,1433;Database=MySyncDb;User Id=myUsername;Password=myPassword;"
  }
}

# Database

This configuration key defines the database that ELO Sync will use.

After you have set this key, you also have to set the corresponding ConnectionString.

{
  // The type of the database provider to be used.
  // Must be one of the following values:
  // "Postgres" - PostgreSQL database (https://www.postgresql.org/)
  //              Version: 14.x or higher, 16.x recommended
  // "Sqlite"   - Sqlite database (https://sqlite.org/);
  //              NOTE: Should only be used for test purposes, as it is up to 10x slower than a real database system.
  // "MsSql"    - Microsoft SQL Server (https://www.microsoft.com/en-us/sql-server/sql-server-downloads)
  //              Version: 2012 or higher, 2019 recommended
  // "Oracle"   - Oracle database (https://www.oracle.com/database/)
  //              Version: 11g release 2 or higher, 19c recommended
  "Database": "Postgres"
}

# DownstreamApis

This key contains the configuration settings for all third-party APIs that are used by ELO Sync.

Each API must have the property Api, which is used to identify the API. All other properties are specifically for the configured API.

# DownstreamApis:Microsoft Graph

This section contains the specific settings for access to the Microsoft Graph API.

{
  "DownstreamApis": [
    {
      // Fixed name for the Microsoft Graph API
      "Api": "Microsoft Graph",
      // Base URL for access to Microsoft Graph, only has to be changed for national cloud deployments
      // NOTE: Currently, only the stable endpoint /v1.0 is supported. The endpoint /beta is untested.
      "BaseUrl": "https://graph.microsoft.com/v1.0",
      // The permissions to be requested when using this API
      "Scopes": "user.read Sites.Read.All Sites.ReadWrite.All",
      // The scope used when authenticating with this API
      "DefaultGraphScope": "https://graph.microsoft.com/.default"
    }
  ]
}

# InstanceName

The optional instance name can be used for horizontal scaling of the ELO Sync service. When you set this name, additional configuration files from the ELO repository can be loaded. See Configuration stored in the ELO repository for more information.

{
  "InstanceName": "EloSync1"
}

Important

There is no support for multiple instances of ELO Sync using the same database.

The instance name only affects the application configuration so that a separate database can be used for each instance.

# Kestrel

This configuration section contains the settings for the built-in Kestrel web server.

Information

The user endpoints must use the HTTPS protocol for ELO Sync to access Microsoft 365.

An HTTP endpoint can only be used if a reverse proxy is upstream of the ELO Sync server and the proxy is configured to use HTTPS.

See also:

{
  "Kestrel": {
    "Endpoints": {
      "HttpsInlineCertFile": {
        "Url": "https://my-elo-sync-server:7224",
        "Certificate": {
          "Path": "C:\\path\\to\\certificate.pfx",
          "Password": "MySecretPassword"
        }
      }
    }
  }
}

# Logging

The Microsoft.Extension.Logging component used by ELO Sync is configured in this section.

Normally, this component redirects all logging to Serilog, but is also used to change the logging level of individual components.

See Configure logging without code (opens new window) for more information.

{
  "Logging": {
    "LogLevel": {
      // Use Information and higher for all unconfigured components
      "Default": "Information",
      // Use Error and higher for all Microsoft components
      "Microsoft": "Error",
      // Use Debug and higher for all ELO components
      "Elo": "Debug"
    }
  }
}

# OAuth

This section contains the settings for using OAuth with ELO Sync.

{
  "OAuth": {
    // The ID of the OAuth configuration to be used with the ELOauth plug-in.
    "ConfigId": "elo_sync_oauth"
  }
}

The selected name for the OAuth configuration profile must also be entered in the configuration of the ELOauth plug-in for the ELO Indexserver.

The OAuth ConfigId can also be defined in the ELO repository, see Configuration stored in the ELO repository.

Please note the documentation (opens new window) for the ELOauth plug-in to configure an authentication profile.

# OpenTelemetry

ELO Sync uses the OpenTelemetry (opens new window) infrastructure for tracing and monitoring the status of the service.

Each area can be configured separately and is disabled by default.

# OpenTelemetry:Logging

The Log Exporter for OpenTelemetry is configured in this section using the OTLP protocol.

{
  "OpenTelemetry": {
    "Logging": {
      // Whether the OTLP Log Exporter should be enabled
      "Enabled": true,
      // The endpoint to be sent the logs
      "Endpoint": "http://localhost:4317/v1/logs",
      // The protocol used to send the logs to the endpoint, must be one of the following values:
      // "HttpProtobuf" - HTTP protocol that uses the Protobuf format
      // "Grpc" - gRPC protocol (default)
      "Protocol": "HttpProtobuf",
      // Additional headers to be sent with each request, typically used for authentication
      "Headers": "Authorization: Bearer MySecret",
      // Exporter options
      "BatchExportProcessorOptions": {
        // See below for more details
      }
    }
  }
}

# OpenTelemetry:Tracing

The Trace Exporter for OpenTelemetry is configured in this section using the OTLP protocol.

{
  "OpenTelemetry": {
    "Tracing": {
      // Whether the OTLP Trace Exporter should be enabled
      "Enabled": true,
      // The endpoint to be sent the traces
      "Endpoint": "http://localhost:4317/v1/traces",
      // The protocol used to send the traces to the endpoint, must be one of the following values:
      // "HttpProtobuf" - HTTP protocol that uses the Protobuf format
      // "Grpc" - gRPC protocol (default)
      "Protocol": "HttpProtobuf",
      // Additional headers to be sent with each request, typically used for authentication
      "Headers": "Authorization: Bearer MySecret",
      // Exporter options
      "BatchExportProcessorOptions": {
        // See below for more details
      }
    }
  }
}

# OpenTelemetry:Metrics

The Metrics Exporter for OpenTelemetry is configured in this section using the OTLP protocol.

{
  "OpenTelemetry": {
    "Metrics": {
      // Whether the OTLP Metrics Exporter should be enabled
      "Enabled": true,
      // The endpoint to be sent the metrics
      "Endpoint": "http://localhost:4317/v1/metrics",
      // The protocol used to send the metrics to the endpoint, must be one of the following values:
      // "HttpProtobuf" - HTTP protocol that uses the Protobuf format
      // "Grpc" - gRPC protocol (default)
      "Protocol": "HttpProtobuf",
      // Additional headers to be sent with each request, typically used for authentication
      "Headers": "Authorization: Bearer MySecret",
      // Exporter options
      "BatchExportProcessorOptions": {
        // See below for more details
      }
    }
  }
}

# OpenTelemetry:*:BatchExportProcessorOptions

This section is used by all OpenTelemetry exporters and configures the Batch Export Processor.

{
  "OpenTelemetry": {
    "*": {
      "BatchExportProcessorOptions": {
        // Delay between two planned exports in milliseconds
        "ScheduledDelayMilliseconds": 5000,
        // The number of items per export batch
        "MaxExportBatchSize": 512,
        // The maximum number of items in the queue before further items are discarded
        "MaxQueueSize": 2048,
        // The timeout in milliseconds after which an export is canceled
        "ExporterTimeoutMilliseconds": 30000
      }
    }
  }
}

# OpenTelemetry:Zipkin

The Zipkin (opens new window) Exporter is configured in this section.

{
  "OpenTelemetry": {
    "Zipkin": {
      // To use the Zipkin Exporter
      "Enabled": true,
      // The endpoint the traces are to be sent to
      "Endpoint": "http://localhost:9411/api/v2/spans"
    }
  }
}

# PrometheusServer

The server for the Prometheus (opens new window) metric provider is configured in this section.

{
  "PrometheusServer": {
    // The endpoint URL where the metrics will be published
    // https is not currently supported
    "Endpoint": "http://localhost:9090/metrics",
    // Defines whether access is allowed via any host name
    "AllowAllHosts": true
  }
}

# PublicUrl

This entry contains the public URL that can be used to access ELO Sync if the access URL is different from the internal URL set in the Kestrel section, e.g. due to the use of a proxy.

{
  "PublicUrl": "https://my-elo-server:9093/ix-Repository1/plugin/de.elo.ix.plugin.proxy/sync"
}

# Repositories

All ELO repositories that can be accessed when using ELO Sync are listed in this configuration section.

A user can select one of these repositories when signing into the web interface.

{
  "Repositories": [
    {
      // Required; the display name for the server in the user interface
      "name": "My ELO Server",
      // Required; a unique key for this server. This key
      // is also used when calling the REST API to identify the repository.
      "key": "MyELOServer",
      // Required; the ELOix endpoint to be used to access the repository
      "url": "https://my-elo-server:9093/ix-Repository1/ix",
      // Optional; the ELO Web Client URL used for the preview or linking with existing documents
      // If not defined, the ELO Web Client URL from the property "url" is used
      "webclienturl": "https://my-elo-server:9093/ix-Repository1/plugin/de.elo.ix.plugin.proxy/web/",
      // Optional; the OAuth callback URL used by this repository
      "oauthcallbackurl": "https://my-elo-server:9093/ix-Repository1",
      // The logon mode used by this repository; must be one of the following values:
      // "ELOauth" - The ELOauth plug-in is used for authentication, which is provided for reasons of backward compatibility.
      // "auth2"   - The Auth2 plug-in is used for authentication
      "loginmode": "auth2",
      // Cookie token exchange URL used to authenticate an ELO session with an access token (see below)
      // This property is ignored if "loginmode" is set
      "cookietokenexchangeurl": "https://my-elo-server:9093/ix-Repository1/plugin/de.elo.ix.plugin.auth/access_token?configId=elo_sync_oauth&clientId=json&jwt_token=",
      // The login URL used if a user is redirected to an ELO web user interface
      // ¶ClientUrl¶ is replaced with the target URL
      // This property is ignored if "loginmode" is set
      "loginurl": "https://my-elo-server:9093/ix-Repository1/plugin/de.elo.ix.plugin.auth/login/?clientUrl=¶ClientUrl¶&configId=elo_sync_oauth",
      // Optional; the timeout in seconds for access to the repository
      // The default value is 10 seconds, as ELO Sync often runs on the same devices as the ELOix.
      "timeout": 10
    }
  ]
}

For simplicity, several template configurations for repositories are listed in the following.

{
  "Repositories": [
    // >= ELO 23.4
    {
      "name": "My Repository",
      "key": "MyRepository",
      "url": "https://my-elo-server:9093/ix-Repository1/ix",
      "loginmode": "auth2"
    },
    // < ELO 23.4
    {
      "name": "My Repository",
      "key": "MyRepository",
      "url": "https://my-elo-server:9093/ix-Repository1/ix",
      "loginmode": "ELOauth"
    },
    // >= ELO 23.4; with public access to the ELO Web Client
    {
      "name": "My Repository",
      "key": "MyRepository",
      "url": "https://my-elo-server:9093/ix-Repository1/ix",
      "loginmode": "auth2",
      // Public URLs for web & login; same domain must be used
      "webclienturl": "https://elo.company.com/web/",
      "loginurl": "https://elo.company.com/authorize?redirect_uri=¶ClientUrl¶&response_type=none&client_id=elosync"
    },
    // < ELO 23.4; with public access to the ELO Web Client
    {
      "name": "My Repository",
      "key": "MyRepository",
      "url": "https://my-elo-server:9093/ix-Repository1/ix",
      "loginmode": "ELOauth",
      // Public URLs for web & login; same domain must be used
      "webclienturl": "https://elo.company.com/web/",
      "loginurl": "https://elo.company.com/login?clientUrl=¶ClientUrl¶&configId=¶ConfigId¶"
    }
  ]
}

# Login mode

The property loginmode controls the additional properties required for authentication with an ELO repository.

Depending on the ELOix version and configuration, it can be set to either ELOauth or auth2.

ELOauth designates the use of the ELOauth plug-in for authentication, which is supported by ELO versions before 23.4.

auth2 designates the use of the Auth2 plug-in for authentication, which is supported by ELOix versions 23.4 and higher.

This URL is used to authenticate an ELO session with the help of an access token from Azure/Entra ID.

The entered URL can contain a placeholder ¶ConfigId¶, which is replaced by the setting OAuth:ConfigId.

Alternatively, the parameter configId has to be set in the URL manually. ELO Sync does not check whether the URL is correct.

If the property is entered manually, the setting OAuth:ConfigId is ignored and the parameter configId must correspond to the configuration required for ELO Sync.

The URL entered must end with the jwt_token query parameter, as the access token is simply added at the end.

Information

This may change in a future version, depending on other requirements.

If the property is not entered, a default URL is created using the basic URL of the original authentication plug-in (de.elo.ix.plugin.auth).

If the Auth2 plug-in is used for authentication (enabled for ELOix 23.4+ by default), this property must be entered explicitly.

Example:

{
  "cookietokenexchangeurl": "https://my-elo-server:9093/ix-Repository1/plugin/de.elo.ix.plugin.rest/auth2/access_token?configId=¶ConfigId¶&clientId=json&jwt_token="
}

The configId parameter must match the configuration that was used for the login configuration in the plug-in.

# Serilog

The logging solution currently used by ELO Sync is Serilog (opens new window).

The sinks and filters for logging are configured in this section. For more details, see Serilog.Settings.Configuration (opens new window)

Below you will find an example that writes a basic log in a rolling log file.

{
  "Serilog": {
    "Using": [
      "Serilog.Sinks.File"
    ],
    "MinimumLevel": "Debug",
    "WriteTo": [
      {
        "Name": "File",
        "Args": {
          "fileSizeLimitBytes": 79857600,
          "retainedFileCountLimit": 20,
          "path": "Logs/ELOSync.log",
          "rollingInterval": "Day"
        }
      }
    ],
    "Enrich": [
      "FromLogContext",
      "WithMachineName",
      "WithThreadId"
    ],
    "Properties": {
      "Application": "ELO Sync"
    }
  }
}

You will find alternative examples for configuring logging here.

# ServiceUser

The settings for the ELO Service user to be used by ELO Sync.

This user must already exist in the ELOam instance and have administrator rights.

{
  "ServiceUser": {
    // User in the ELOam instance with administrator rights
    "UserName": "ELO Service",
    // Password for the user
    "Password": "MySecretPassword"
  }
}

# Save the configuration in the ELO repository

Parts of the application configuration can be stored in an ELO repository.

For this reason, the local appsettings.json (or appsettings.Production.json) must have a repository and the setting Service User.

ELO Sync then uses this local configuration, connects to the repository, and inserts the working version of the following json document as a configuration file:

  • Administration/ELO Sync/config/appsettings.public

    If this document is missing or does not contain a valid configuration, its content is ignored and a warning is logged.

    If multiple documents with this name exist, only the first one (identified by ELOix) is loaded.

    If the InstanceName is defined in the local configuration, the following configuration document is loaded in addition to the previous configuration elements.

  • Administration/ELO Sync/config/<InstanceName>/appsettings.public

    The placeholder above <InstanceName> is replaced with the value from the InstanceName setting.

Edit this page (opens new window)
Last updated: February 21, 2025 at 9:59 AM

Templates for logging configurations →