# 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.
# Cookie token exchange URL
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.publicIf 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
InstanceNameis defined in the local configuration, the following configuration document is loaded in addition to the previous configuration elements.Administration/ELO Sync/config/<InstanceName>/appsettings.publicThe placeholder above
<InstanceName>is replaced with the value from theInstanceNamesetting.