2.3Stage 2: Configure with the setup wizard
Last updated
The setup wizard is a desktop application with nine pages, listed on the left of its window under short names: Prerequisites, Hosting, Database, Secrets, Sessions, CORS & proxy, Limits, Audit and Logging. The top of each page shows its full title and Step N of 9, for example Step 2 of 9. It starts automatically after the installer finishes; you can also start it at any time from Start > SYNERGY Management Gateway Setup. It needs administrator rights.
The top of the left panel shows whether this is a First installation or whether you are Reconfiguring an existing installation. The wizard decides this itself: if it finds an existing configuration file and an existing token signing secret, it treats the run as a reconfiguration.
Moving through the wizard
- Next checks the current page and moves to the next one. If something is missing or invalid, the problems are listed in red under the page and you stay on the page until they are fixed.
- Back returns to the previous page. Nothing is written until the last step.
- On the last page the Next button becomes Apply. Applying is the only step that changes anything on the server.
- Close closes the wizard. If you close it while it is applying, it warns you that the configuration may be left half applied.
Most fields show a short explanation under them. The sections below describe each page in order, with the default values a first installation starts from.
Page 1: Prerequisites
This page checks the server and writes nothing. The check runs automatically when the page opens; select Re-check to run it again after fixing something.
| Check | Required | What to do if it is missing |
|---|---|---|
| Windows Server 2016 or later | Yes | Use a supported Windows version. |
| Running as administrator | Yes | Close the wizard and start it again as administrator. |
| .NET 10 ASP.NET Core runtime | Yes | Install the ASP.NET Core 10 Hosting Bundle. |
| IIS installed | Yes | Add the Web Server (IIS) role. |
| ASP.NET Core Module V2 | Yes | Install (or repair) the ASP.NET Core 10 Hosting Bundle after IIS. |
| IIS Windows Authentication (for Windows sign-in) | No | Needed only for Windows sign-in: Install-WindowsFeature Web-Windows-Auth. |
Each line reads OK or MISSING followed by the check's name and a detail. The page also reminds you that the product runs only on Windows.
Page 2: Hosting and paths
This page says where the files are and how IIS exposes them.
| Field | Default | Description |
|---|---|---|
| API content directory | C:\inetpub\apps\api | Where the API is installed. The configuration file appsettings.Production.json is written here. Required. |
| Client content directory | C:\inetpub\wwwroot | Where the web console is installed. It is served at the site root. Required. |
| IIS site | Default Web Site | An existing IIS site. The wizard does not create sites or bindings. Required. |
| Application alias | backend | The path the API answers on, below the site. Keep backend: the web console, health checks and the update agent expect it. Required. |
| Application pool | api | Created if it does not exist. Required. |
| Public base URL | empty | The address users reach the product at, for example https://gateway.example.com. Required, and must be https. |
| Allowed hosts | * | Host names the server answers to. * accepts any; enter your real host name to reject the rest. |
| Windows sign-in | Unchanged | Whether IIS is configured for Windows sign-in. See below. |
The application pool is created with no managed runtime, no idle time-out and no periodic recycle. An idle shutdown would stop the licence heartbeat and the product's other background work, so do not add an idle time-out later.
The release stage (for example Release) and the release notes address are not asked for: they are part of the product build and are shown in the console's About dialog and Help menu. Earlier versions of the wizard asked for them on this page; a value an earlier version wrote into the configuration file is now ignored.
The Windows sign-in option
Windows sign-in lets people sign in to the console with their Windows session (Kerberos) instead of typing a password. It needs IIS to be set up in a particular way, which this option does for you.
| Choice | Effect |
|---|---|
| Unchanged | Leaves the IIS Windows authentication settings as they are. Choose this on every run unless you want to change them. |
| On | Configures IIS Windows authentication for the API: on at the application's root, off again for every path the application serves, and on only for the Windows sign-in address. This keeps ordinary console requests and integrations from receiving Windows authentication prompts. |
| Off | Removes that configuration. |
The settings are written to the server's IIS configuration (applicationHost.config), not to the application's web.config, because IIS locks that section at server level by default.
Before choosing On, make sure that:
- the IIS Windows Authentication role service is installed (the Prerequisites page shows it);
- the site has an HTTPS binding — Windows sign-in refuses plain HTTP;
- a service principal name (SPN) for the site's host name is registered on the application pool's account, so Kerberos works.
Configuring IIS only makes Windows sign-in possible. Who may sign in this way, and which roles their Active Directory groups give them, is configured afterwards in the console and requires the sso licence module. See Chapter 17, Single sign-on.
Page 3: Database
This page sets up the product's own database, which holds platform users, roles, connections, policies, the operations log and settings.
| Field | Shown when | Description |
|---|---|---|
| Provider | Always | SqlServer, Postgres or Sqlite. |
| Server | SQL Server, PostgreSQL | SQL Server: HOST or HOST\INSTANCE. PostgreSQL: host, optionally host:port (port 5432 if omitted). |
| Database | SQL Server, PostgreSQL | The name of the database your database administrator created. Replace the pre-filled name with it. It must already exist and be empty or already used by this product. |
| Authentication | SQL Server, PostgreSQL | WindowsIntegrated (the default) connects as the application pool identity. SqlLogin connects with a user name and password. |
| SQL login | SqlLogin | The database account to connect as. |
| SQL password | SqlLogin | Its password. It is written into the connection string in the configuration file, which is why integrated authentication is preferred. |
| Encrypt the connection | SQL Server | On by default. Keep it on. |
| Trust the server certificate | SQL Server, with encryption on | On by default, because most on-premises SQL Server instances use a self-signed certificate. Turn it off once the database server has a properly issued certificate. |
| SQLite file | SQLite | Full path of the database file. Default C:\ProgramData\Synergy\ManagementGateway\gateway.db. |
| Apply migrations at startup | Always | On by default: the application creates and upgrades its tables and default data when it starts. Leave this on unless your organisation applies database changes as a separate step. |
| Use a connection string I supply | Always | Replaces all the fields above with a connection string you type, for options the fields do not cover (failover partner, application intent, custom time-outs). |
| Connection string | Override selected | The connection string, written exactly as typed. |
Select Test next to Test connection to open a real connection with the details you entered. For SQL Server and PostgreSQL the result shows the database server version and database name; for SQLite it confirms that the database file can be created at the path given. On failure it shows the database provider's own error message. The test does not look for tables: on a first installation there are none yet.
Important: If you turn off Apply migrations at startup, the wizard does not create the schema, and the final readiness check fails until the database has been brought up to date by your own process. The wizard tells you this in its transcript.
Page 4: Secrets
Secrets are written as environment variables of the API's IIS application pool, never into the configuration file. Only the API's worker process sees them; other programs on the server do not.
On a first installation every secret is generated for you with a strong random value, and each field has a Generate button to make a new one. You do not need to see or record the values: the product reads them from the application pool.
| Field | Variable | Description |
|---|---|---|
| JWT signing secret | JWT_SECRET | Signs sign-in tokens. At least 32 characters. The application refuses to start without it. Required. |
| Credential encryption key | CREDENTIAL_ENCRYPTION_KEY | Encrypts every stored directory connection password and other stored credentials. At least 16 characters. |
| Audit chain key | AUDIT_CHAIN_KEY | Signs the audit chain. At least 32 characters. Required while the audit chain is enabled (page 8). Must differ from the credential encryption key. |
| Retention pseudonym salt | RETENTION_PSEUDONYM_SALT | Used only when operation log retention is enabled (page 8), to replace people's identities with pseudonyms in retained records. |
Important: Never change the credential encryption key casually. If it changes, no saved directory connection password can be decrypted and every connection must be re-entered. Changing the audit chain key without following the key rotation procedure makes existing audit entries report as unverifiable.
When you reconfigure an existing installation, the secret fields start empty and empty fields are left unchanged. Type or generate a value only if you intend to replace that secret.
Page 5: Tokens, cookies and CSRF
This page controls how a browser session is issued, refreshed and protected. The defaults are suitable for most installations; change them only if you have a specific reason.
| Field | Default | Description |
|---|---|---|
| Token issuer | ActiveDirectoryService | The issuer recorded in sign-in tokens. Changing it signs everybody out. |
| Token audience | ActiveDirectoryServiceUsers | The audience recorded in sign-in tokens. Unrelated to licensing. |
| Access token lifetime (minutes) | 15 | How long a sign-in token is valid before the browser silently refreshes it. 1 to 1440. |
| Refresh token lifetime (days) | 14 | How long a session can stay idle and still be refreshed. Renewed each time it is used. |
| Absolute session ceiling (days) | 90 | The longest any session can last, however active, before the person must sign in again. Cannot be shorter than the refresh token lifetime. |
| Refresh cookie name | refresh_token | Name of the refresh cookie. |
| Refresh cookie path | /auth | Limits which requests carry the refresh cookie. Must start with /. Leave at the default. |
| Bind refresh tokens to the origin IP | On | A refresh token works only from the address that obtained it. Turn off if users roam between addresses during a session (VPN, mobile networks). |
| Auth cookie SameSite | None | None, Lax or Strict. None is needed when the console is served from a different origin than the API, and only works together with Secure. |
| Auth cookie Secure | On | Required for HTTPS and for SameSite None. |
| CSRF protection | On | Protects cookie-authenticated console requests against cross-site request forgery. Integrations using API keys or bearer tokens are not affected, so leave it on. |
| CSRF cookie name | XSRF-TOKEN | Must match what the web console expects. |
| CSRF header name | X-XSRF-TOKEN | Must match what the web console expects. |
Page 6: Browser origins and reverse proxy
| Field | Description |
|---|---|
| Allowed origins | The web addresses browsers may call the API from, one per line, with scheme and port, for example https://gateway.example.com. Normally this is your public base URL. Wildcards are not accepted. At least one is required — with none, the web console cannot call the API. An origin has no path. |
| Known proxies | The IP addresses of reverse proxies or load balancers in front of IIS, one per line. |
| Known networks | Network ranges of such proxies in CIDR form, one per line, for example 10.0.0.0/8. |
Leave both proxy lists empty when users reach IIS directly. Fill them in when anything sits in front of IIS; otherwise every user appears to come from the proxy's address, and the per-address rate limits on page 7 become one shared limit for everybody.
If the product is reached by more than one name — for example an internal name and an external name published through a reverse proxy — list every origin users will use.
Page 7: Rate and request size limits
Rate limits restrict how many requests one client address can make in a time window. Health checks and live update connections are always exempt.
| Field | Default | Description |
|---|---|---|
| Global limiter | On | A baseline limit applied to every request. |
| Global requests | 300 | Requests allowed per window. |
| Global window (seconds) | 60 | Length of the window. |
| Directory search requests | 60 | A separate, tighter limit for directory searches, the most expensive requests. |
| Directory search window (seconds) | 60 | Length of the search window. |
| Per-path overrides | three rows | Limits for particular paths. The longest matching path prefix wins. |
| Request body limit (MB) | 1 | The largest request body accepted; larger requests are refused with 413. 1 to 28. |
| Batch request body limit (MB) | 10 | The largest body accepted by the directory batch endpoints (up to 100 objects per request). At least the request body limit, and at most 28. |
The per-path overrides are pre-filled to protect sign-in against password guessing:
| Path | Requests | Window (seconds) |
|---|---|---|
/rest/auth/login | 10 | 60 |
/api/auth/login | 10 | 60 |
/rest/auth/refresh | 60 | 60 |
Each row has an Enabled tick box. Clearing it switches rate limiting off for that path rather than tightening it.
The request body limits are written to the configuration only when they differ from the defaults, so upgrades keep the product's defaults otherwise. Limits above 28 MB would be refused by IIS request filtering before reaching the product.
Page 8: Audit chain, retention and the kill switch
This page decides what is recorded, how long it is kept, and which operations this installation refuses entirely.
| Field | Default | Description |
|---|---|---|
| Hash-chained audit | On | Every change to an operation record appends a signed, chained entry that can be verified later. Requires the audit chain key from page 4. |
| Key epoch | 1 | Increase by one when you rotate the audit chain key. |
| Checkpoint interval | 01:00:00 | How often the latest audit chain value is written to the application log, which can be forwarded off the server. 00:00:00 turns it off. |
| Refuse operations that cannot be audited | Off | On: if the audit record cannot be written, the operation is refused. Off: work continues, an error is logged and the readiness check reports unhealthy. Turn on where the audit trail is a regulatory obligation. |
| Operation log retention | Off | Turns on automatic clean-up of old operation records. |
| Clear personal data after (days) | 400 | Stage one: removes personal data from old records but keeps what ran, where, when and the outcome. |
| Delete rows after (days) | 1095 | Stage two: deletes old records. This cannot be undone. |
| Refuse a retention shorter than (days) | 90 | A safety floor checked at start-up, so a typing mistake cannot empty the log. |
| Rows per batch | 500 | How many records are processed at a time. |
| Batches per run | 20 | How many batches each clean-up run processes. |
| Retention check interval | 1.00:00:00 | How often clean-up runs, as d.HH:MM:SS. |
| Disabled commands | empty | Operations to block for the whole installation, one per line, by name (for example DeleteActiveDirectoryUserCommand). |
| Disabled categories | empty | Operation categories to block, one per line (for example Active Directory Security). |
| Disabled sensitivities | empty | Any of Normal, Sensitive, Destructive, one per line. |
When retention is on, the page checks that Delete rows after is not below Refuse a retention shorter than, and that personal data is cleared before rows are deleted. It also warns you if no retention pseudonym salt was set on page 4: without one, retained records lose the link between operations by the same person.
Important: The retention day counts are placeholders, not recommendations. How long you keep audit records is a compliance decision for your organisation. Export anything you must keep before you enable stage two.
The last three lists are the installation's kill switch. An operation matched by any of them is blocked whatever its policy says, and cannot be switched back on from the console or the API. Leave all three empty unless you mean to block something permanently. Each entry is checked when the application starts, and the application refuses to start if an entry matches nothing — so a typing mistake shows up as a failed start rather than as an operation you believe is blocked but is not. Per-operation switches that you can change at any time are on the Directory Policies screen; see Chapter 10, Operation policies, attribute policies and agent supervision.
Page 9: Logging, alerting and workers
| Field | Default | Description |
|---|---|---|
| Default level | Information | The detail level of the application log. |
| Framework level | Warning | Detail level for the web server and framework. |
| Entity Framework level | Warning | Detail level for database access. Information logs every database statement; use it only briefly when troubleshooting. |
| Log file path | C:\Logs\log-.logs | Log files roll daily from this name. The application pool is given write access to the folder. |
| Files retained | 31 | How many daily log files are kept. |
| File size limit (bytes) | 104857600 | The largest size of one log file (100 MB). |
| Syslog collector host | empty | A syslog server to forward the log to. Leave empty for none. |
| Syslog port | 6514 | 6514 for syslog over TLS, 601 for plain TCP. |
| Syslog over TLS | On | The collector's certificate must be trusted by this server. |
| Sentry DSN | empty | Optional error alerting through Sentry. Only errors are sent, without personal data. |
| Email retry attempts | 3 | How often sending an email is retried. |
| Email base delay (seconds) | 2 | Delay before the first retry. |
| Email exponential backoff | On | Whether each retry waits longer than the previous one. |
| Email max delay (seconds) | 30 | The longest delay between retries. |
| API-key expiry check | 01:00:00 | How often the product looks for API keys about to expire, to send notices. |
Settings that are not in the wizard
Earlier versions of the wizard had two more pages, Directory client and Licensing, feedback and usage statistics, and a Licence expiry check field on the Logging page. None of these is asked for any more:
| Setting | Where it is now |
|---|---|
| Licensing service address and product key | Built into the product. The server must still reach https://public-hub.synergy.lt/ (see Allow outbound access to the licensing service). Licensing is always enforced: until a licence is activated, directory operations are refused with 403 License.NotActivated. |
| Licence heartbeat (every 4 minutes), licensing service key cache (1 hour), request time-out (10 seconds) and licence expiry check (every 12 hours) | Built into the product. There is nothing to set. |
| Feedback and bug reports | On by default. Users send them from the console's Help menu (see Chapter 4, Working in the console). |
| Usage statistics | Agreed or refused by an administrator on the Licence screen in the console (see Chapter 19, Licence, updates and backups). |
| Retry attempts, initial retry delay, connection health checks and schema classes read at start-up | The Directory › Directory client screen in the console (see Chapter 5, Directory connections, Directory client settings). The old Connection timeout field is gone completely: the product never used it. |
Applying the configuration
When you select Apply on the last page, the wizard lists what it will do and asks you to confirm:
- write
appsettings.Production.jsoninto the API content directory; - set the secrets as environment variables of the application pool;
- restrict
appsettings.Production.jsonso that only SYSTEM, Administrators and the application pool can read it; - create or update the IIS application pool and the application under the site;
- grant the application pool identity rights on the content, key and log folders;
- restart the application pool and wait for the readiness check.
Select OK to continue. The wizard shows a transcript as it works. Do not close the window while it reads Applying. Do not close this window.
The wizard works through these steps in order:
- Configuration. Writes
appsettings.Production.json. If a previous file existed, a timestamped backup is kept beside it. - IIS and permissions. Creates or updates the application pool and the application, applies the Windows sign-in choice, and grants folder permissions. Existing pools and applications are updated, never deleted and recreated, so settings you made by hand are kept.
- Secrets. Writes the secrets to the application pool. Secrets left machine-wide by an older version are moved into the pool.
- Database schema. Reports whether the application will apply database changes itself.
- Application pool. Restarts the IIS services (so every site on the server is interrupted briefly) and the application pool, so that the new settings take effect. It also restarts the update agent service so that it reads the new configuration.
- Readiness. Waits for the application to start, create its database tables and report ready at the public base URL followed by
/backend/health/ready, for examplehttps://gateway.example.com/backend/health/ready. On an empty database this takes tens of seconds. The wizard tries up to twelve times, five seconds apart, and accepts a certificate that is not yet trusted. Because it calls the public base URL, the server itself must be able to resolve and reach that address.
When everything succeeds, the wizard shows a Setup completed message telling you to open the public base URL in a browser on the server to create the first administrator, and reminding you that the first directory connection and the licence activation are still to do. The button changes to Finish.
If a step fails, the wizard shows Setup did not complete and the transcript shows how far it got. Every step can safely be repeated: fix the cause and run the wizard again. See "Troubleshooting installation" later in this chapter.
The setup record
At the end of every run the wizard writes SETUP-NOTES.md in the API content directory. It records:
- when setup ran, by whom, and whether it completed;
- where everything is: folders, configuration file, IIS site and application, application pool, public address, readiness address, log folder and database;
- which secrets are present (names only, never values);
- important decisions: audit chain, fail-closed auditing, retention, licensing (built in, nothing to configure), off-server logging and kill switch entries;
- the remaining manual steps;
- a description of the update agent;
- advice before upgrading;
- the complete transcript.
Keep this file. It is the easiest way to find out later how the installation was configured.
Last updated
Thank you for your feedback.