System settings in the file appsettings.json

Warning

The file must be in valid JSON format.

The file path is BaseDirectory\Concrii\appsettings.json. Check out the definitions in the Installation thread to learn more about Concrii's filesystem properties.

Using the GUI, you can access, edit and save the appsettings.json under Configuration in the top navigation bar. Policy ConfigurationWrite is needed.

ConfigurationSecretProperties

Type	Description	Default
string	Commaseperated string with all property names that will be handled secure (encrypted) within all configuration files. Names are not trimmed but case insensitive, thus, whitespaces matters, case not.	"password,connectionstring,clientsecret,sharedsecret,instrumentationkey,eventcollectortoken"

Schedule

Type	Description	Default
string	.net crontab expression to configure `Scheduler` itself. Need to be configured when any scheduler must run.	null

Note

Find out more about .net crontab here.

ScheduleFrequencyMs

Type	Description	Default
string	Scheduler check is carried out every x miliseconds.	"5000"

Note

Every x milliseconds, the Schedule expression is checked if it is in the past and have to be started.

License

Type	Description	Default
string	A valid license string.	null

Note

If license is not or no more valid, a notice is shown within Ui footer. Concrii continues to work as expected.

AllowedHosts

Attribute	Type	Description	Default
AllowedHosts	string (semicolon seperated)	Specify allowed hostnames. Multiple hostnames can be configured by seperating them with `;`. Refer to docs.microsoft.com	*

AllowedClientCertificates

Attribute	Type	Description	Default
Filter	string array (Certificate Filter)	Filter criteria specifying which certificates are accepted. See Filter.	null

Note

At least one AllowedClientCertificates must be given to allow client certificates. * is not supported.

Certificate Filter

Attribute	Type	Description	Default
Subject	string	Gets the subject distinguished name from the certificate.	null
Issuer	string	Gets the name of the certificate authority that issued the X.509v3 certificate.	null
IssuerName	string	Gets the distinguished name of the certificate issuer.	null
FriendlyName	string	Gets the associated alias for a certificate.	null
Thumbprint	string	Gets the thumbprint of a certificate.	null

Note

Please refer to Filter string functions.

Access

Specify Roles and Contexts and assign Policies to Roles and SubRoles. Configure Authentication and Authorization: Basic, User/Password, Client certificate, OAuth, OpenIdConnect and Kerberos.

Note

After creating a new User, the Concrii service needs to be restarted to adapt the changes.

Warning

Even if a User is not assigned a certain Policy, the respective GUI element might still be displayed, but brings up error when clicking.

Attribute	Type	Description	Default
ApplyAllContexts	boolean	If `true` (default), all Contexts will be added. Means, users have access to all objects in Contexts. If false, you have to assign contexts via assignments, roles and/or context policies.	true
ShowPII	boolean	If `true`, PII (Personally Identifiable Information) information are included within logs/events. PII = Personally Identifiable Information	false

Warning

ShowPII must be activated only during debugging OIDC / JwtBearerToken authentication due to get detailled validation errors/informations. Never leave this setting on true when running in productive mode.

Roles

The Roles object consists of Policies and SubRoles that can be assigned to Users in order to control which types of read-write permissions are given and which API controllers each User has access to when using Concrii. Within (initial appsettings.json) you will find a good example of how to setup roles permissions structure. Within your instance, you can freely assign policy to further roles etc...

Attribute	Type	Description	Default
Name	string	name of the `Role`	null
Policies	string array	assigned `Policies`. These policies are strings taken directly from the source code. Check out the API thread to find out more about for which methods (e.g. `Search`) specific `Policies` are required in Authorization.	null
SubRoles	string array	assigned Roles (`SubRoles`). SubRoles can be added so that `Policies` are inherited from another `Role`.	null
Contexts	string array	Contexts to be applied.	null

Contexts

Contexts is an array that describes different scenarios or "environments" that allow for different usecases tailored to different Users. You can specifiy which tables, columns and configuration files are visible within each context.

Attribute	Type	Description	Default
Id	string	Unique id of the context (will be assigned to user / role using this id).	null
Database	string array	Databases (ids) to be visible within this context.	null
Table	string array	Tables (ids) to be visible within this context.	null
Index	string array	Indexes (ids) to be available within this context.	null
Column	string array	Columns (ids) to be visible within this context.	null
Encryptor	string array	Encryptors (ids) to be available within this context.	null
EncryptorProvider	string array	Encryptors (ids) to be available within this context.	null
ConfigurationFile	string array	Configuration files (string) to be visible within this context, for instance "configuration.json".	null
CleartextDatabase	string array	Databases (ids) to be able to decrypt within this context.	null
CleartextTable	string array	Tables (ids) to be able to decrypt within this context.	null
CleartextColumns	string array	Columns (ids) to be able to decrypt within this context.	null

Warning

If ApplyAllContexts is set to true and no context is assigned to the user, this user has access to all aspects dependent to this roles. E.g. if IndexCreate policy is assigned through a role to a user without a context, this user can create all indexes (as he has access to all databases/tables).

User

This object array defines the local Concrii user.

Nested Object	Type	Description	Default
Name	string	Username of the local Concrii user.	null
Password	string	Password of the local Concrii user.	null

UserAssignments

In this object array, the actual assignment of formerly specified Roles and SubRoles takes place and are assigned to users. As context filter, User filter must be used. Please refer to Assignments for further information.

ClientCertificates

In this object array, the actual assignment of formerly specified Roles and SubRoles takes place.

Nested Object	Type	Description	Default
Active	boolean	To activate client certificate authentication: `true`.	false
EnableCrlCheck	boolean	To deactivate client certificate crl check: `false`.	true
ValidateCertificateUse	boolean	To deactivate client certificate usage validation: `false`.	true
ValidateValidityPeriod	boolean	To deactivate client certificate validityperiod validation: `false`.	true
Assignments	object array	Assignments to be applied using Certificate Filter.	null

Note

Please refer to Filter string functions.

Basic

This object defines basic authentication settings.

Attribute	Type	Description	Default
Active	boolean	To activate basic authentication: `true`	false
Realm	string	Currently only one realm is supported: `concrii`	"concrii"

Kerberos

This object defines kerberos/negotiate authentication settings.

Attribute	Type	Description	Default
Active	boolean	To activate kerberos authentication: `true`	false
NameTokenType	string	Every time the user's name is accessed through the `User.Identity.Name` property, the `NameTokenType` specifies the claim on the user who's value is retrieved.	"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name"
Assignments	object array	Assignments to be applied using Identity Filter.	null
ClaimTransformations	object array	ClaimTransformations to be applied to the external claims (claims from the IDP within the received token)	null

OAuth

This array serves as configuration for Open Authorization. OAuth provides clients a secure access to server resources on behalf of a resource owner, enabling resource owners to authorize third-party access to their server resources without providing credentials. Concrii supports OAuth 2.0.

Warning

ClientId and ClientSecret are essentially equivalent to a username and a password, so the ClientSecret should not be stored in plain text. You can cipher the ClientSecret as described here.

Attribute	Type	Description	Default
Name	string	Unique name of the provider.	null
Active	boolean	Is / Should the OAuth service (be) active?	false
ClientId	string	OAuth client id. The client id is a public identifier for OAuth applications (mostly 32-character hex strings), in this case for the respective Concrii instance.	null
ClientSecret	string	Client's secret. This is a secret only known to the application and the authorization server.	null
AuthorizationEndpoint	string	OAuth authorization endpoint. The authorization endpoint is one of two endpoints of the authorization server, used by the application to obtain authorization from the resource owner.	null
TokenEndpoint	string	OAuth token endpoint specified by the provider.	null
NameTokenType	string	Every time the user's name is accessed through the `User.Identity.Name` property, the `NameTokenType` specifies the claim on the user who's value is retrieved.	"name"
CallbackPath	string	OAuth callback path, unique for every application. If not configured, default value built up with `/signin-oauth/Name`	"/signin-oauth/Name"
Scopes	string array	OAuth scopes. An application can request one or more scopes, this information is then presented to the user in the consent screen, and the access token issued to the application will be limited to the scopes granted.	null
Assignments	object array	Assignments to be applied using Identity Filter, for instance using the `EndsWith()` method. Example: "Claims.First(c => c.Type.Equals("email")).Value.EndsWith("@yourdomain")"	null
ClaimTransformations	object array	ClaimTransformations to be applied to the external claims (claims from the IDP within the received token)	null

OpenIdConnect

This array serves as configuration for OpenIdConnect. OpenIdConnect provides clients a secure access to server resources on behalf of a resource owner, enabling resource owners to authorize and third-party access to their server resources without providing credentials.

Warning

ClientId and ClientSecret are essentially equivalent to a username and a password, so the ClientSecret should not be stored in plain text. You can cipher the ClientSecret as described here.

Attribute	Type	Description	Default
Name	string	Unique name of the provider.	null
Active	boolean	Is / Should the OIDC service (be) active?	false
ClientId	string	Identity provider client id. The client id is a public identifier for applications (mostly 32-character hex strings), in this case for the respective Concrii instance.	null
ClientSecret	string	Identity provider Client's secret. This is a secret only known to the application and the authorization server.	null
Authority	string	The authority endpoint of the identity provider concrii will use for authentication / authorization.	null
Resource	string	The resource (id) to be requested within access token. Usually the `ClientId` is should be used.	null
NameTokenType	string	Every time the user's name is accessed through the `User.Identity.Name` property, the `NameTokenType` specifies the claim on the user who's value is retrieved.	"name"
ResponseType	string	Defines oidc flow type (Expert setting). Default value might be changed in very rare circumstances, only. Supported values: `code`,`code id_token`,`code id_token token`,`code token`,`id_token`,`id_token token`,`none`,`token`. Refer to docs.microsoft.com	"code"
UsePkce	boolean	Enables or disables the use of the Proof Key for Code Exchange (PKCE) standard.	true
RequireHttpsMetadata	boolean	Sets if HTTPS is required for the metadata address or authority.	true
GetClaimsFromUserInfoEndpoint	boolean	Set whether the handler should go to user info endpoint to retrieve additional claims or not after creating an identity from id_token received from token endpoint.	true
SaveTokens	boolean	Defines whether access and refresh tokens should be stored in the Microsoft.AspNetCore.Authentication.AuthenticationProperties after a successful authorization.	true
CallbackPath	string	OIDC callback path, unique for every application. If not configured, default value built up with `/signin-oidc/Name`	"/signin-oidc/Name"
SignedOutCallbackPath	string	OIDC signout callback path, unique for every application. If not configured, default value built up with `/signout-oidc/Name`	"/signout-oidc/Name"
SignedOutRedirectUri	string	OIDC signout redirect uri. Might be need from some identity provider (likely ADFS)	null
Scopes	string array	OIDC scopes. An application can request one or more scopes, this information is then presented to the user in the consent screen, and the access token issued to the application will be limited to the scopes granted.	null
Assignments	object array	Assignments to be applied using Identity Filter, for instance using the `EndsWith()` method. Example: "Claims.First(c => c.Type.Equals("email")).Value.EndsWith("@yourdomain")"	null
ClaimTransformations	object array	ClaimTransformations to be applied to the external claims (claims from the IDP within the received token)	null

JwtBearerToken

This array serves as configuration for JwtBearerToken authentication. JwtBearerToken provides clients a secure access to server with a Bearer Token (Authentication heade: "Bearer ...").

Attribute	Type	Description	Default
Name	string	Unique name of the provider.	null
Active	boolean	Is / Should this BearerToken authentication service (be) active?	false
Authority	string	The authority endpoint of the identity provider concrii will use for authentication / authorization.	null
Audience	string	The audience / clientid of concrii which has to be aquired from any client.	null
NameTokenType	string	Every time the user's name is accessed through the `User.Identity.Name` property, the `NameTokenType` specifies the claim on the user who's value is retrieved.	"name"
ClaimsIssuer	string	Override the issuer of claims (Expert setting).	null
RequireHttpsMetadata	boolean	If `true`, https is required for any request to metadata adress or authority.	true
RequireExpirationTime	boolean	If `true`, Expiration time of received token is valided.	true
RequireSignedTokens	boolean	If `true`, tokens must be signed	true
RequireAudience	boolean	If `true`, token must contain an audience.	true
SaveSigninToken	boolean	If `true`, tokens can be saved internally (Internal settings / Experts only)	false
TryAllIssuerSigningKeys	boolean	If `true`, all signing keys will be used/tried during validation. As signing keys cannot be specified, leave this setting on `true`, always. (Expert setting)	true
ValidateActor	boolean	If `true`, Actor of received token is validated.	false
ValidateAudience	boolean	If `true`, Audience of received token is validated.	true
ValidateIssuer	boolean	If `true`, Issuer of received token is validated.	true
ValidateIssuerSigningKey	boolean	If `true`, Issue signing keys of received token will be validated.	false
ValidateLifetime	boolean	If `true`, lifetime of received token is validated.	true
ValidateTokenReplay	boolean	If `true`, token replay is validated during validation. As TokenReplayValidator is not available in concrii, leave this setting on `true`, always. (Expert setting)	false
ValidIssuer	string	If set, this overrides the Issuer which the token's Issuer is validated against. If not set, `Authority` is used.	Authority
ValidAudience	string	If set, this overrides the Audience which the token's Audience is validated against. If not set, `Audience` is used.	Audience
ClockSkewSeconds	int	Configure clock skew for time comparison between relying parties (concrii, IDP). Default is 5 minutes (300 seconds).	300
Assignments	object array	Assignments to be applied using Identity Filter, for instance using the `EndsWith()` method. Example: "Claims.First(c => c.Type.Equals("email")).Value.EndsWith("@yourdomain")"	null
ClaimTransformations	object array	ClaimTransformations to be applied to the external claims (claims from the IDP within the received token)	null

Server

This object array contains the configuration for the .net core webserver that is part of Concrii.

Endpoints (object array):

Nested Object	Type	Description	Default
Host	string	Specifies the ip to listen to.	null
Port	string	Specifies the port to listen to.	null
Scheme	string	"http” or "https".	null
CertificateMode	enumeration CertificateMode	Configure how to handle client certificates.	null
SslProtocol	string (comma seperated enumeration SslProtocol)	Supported SslProtocol versions.	"Tls12"
SslCertificate	object SslCertificate	Certificate object to configure server certificate.	null
DisableUi	boolean	Disable Ui within this endpoint.	false
DisableApi	boolean	Disable Api within this endpoint.	false
IpWhitelist	string array	Whitelist ip addresses within this endpoint. If none specified, all ips are permitted.	null
HeaderWhitelist	HeaderWhitelistOptions array	Whitelist certain header values within this endpoint. If none specified, no checks are done regarding headers.	null
ContextWhitelistFilter	string array	Expert usage only! Configure whitelist filter on the context object ([Microsoft.AspNetCore.Http.HttpContext](https://docs.microsoft.com/de-de/dotnet/api/microsoft.aspnetcore.http.httpcontext.	null

Nested Object	Type	Description	Default
Hsts	object Hsts	Specify `Strict-Transport-Security` Header.	see Hsts defaults
XFrame	string	Specify `X-Frame-Options` Header.	"deny"
Csp	object Csp	Specify `Content-Security-Policy` Header.	see Csp defaults
XContentType	string	Specify `X-Content-Type-Options` Header.	"nosniff"
XXssProtection	string	Specify `X-Xss-Protection` Header.	"1; mode=block"
ReferrerPolicy	string	Specify `Referrer-Policy` Header.	"no-referrer"
PermissionPolicy	string	Specify `Permissions-Policy` Header.	"accelerometer=(), ambient-light-sensor=(), autoplay=(), battery=(), camera=(), display-capture=(), document-domain=(), encrypted-media=(), execution-while-not-rendered=(), execution-while-out-of-viewport=(), fullscreen=(), gamepad=(), geolocation=(), gyroscope=(), layout-animations=(), legacy-image-formats=(), magnetometer=(), microphone=(), midi=(), navigation-override=(), oversized-images=(), payment=(), picture-in-picture=(), publickey-credentials-get=(), speaker-selection=(), usb=(), screen-wake-lock=(), web-share=(), xr-spatial-tracking=()"
CacheControl	string	Specify `Cache-Control` Header.	"no-cache, no-store, must-revalidate"

Hsts

Nested Object	Type	Description	Default
Active	boolean	Activate Hsts (`Strict-Transport-Security`).	true
MaxAgeHours	integer	Hsts max age (in hours).	720
Preload	boolean	Activate Hsts preload.	true
IncludeSubDomains	boolean	Hsts include subdomains.	true
ExcludedHosts	List array	Exclude hosts from hsts header.	null

Csp

Nested Object	Type	Description	Default
Active	boolean	Activate Csp (`Content-Security-Policy`).	true
DefaultSrc	string array	specify csp `default-src`.	['default-srs']
ScriptSrc	string array	specify csp `script_src`.	['scriptssrc']
ScriptSrcElem	string array	specify csp `script-src-elem`.	['script-src-elem']
ScriptSrcAttr	string array	specify csp `script-src-attr`.	['script-src-attr']
StyleSrc	string array	specify csp `style-src`.	['style-src']
StyleSrcElem	string array	specify csp `style-src-elem`.	['style-src-elem']
StyleSrcAttr	string array	specify csp `style-src-attr`.	['style-src-attr']
ImageSrc	string array	specify csp `img-src`.	['img-src']
FontSrc	string array	specify csp `font-src`.	['font-src']
MediaSrc	string array	specify csp `media-src`.	['media-src']
ConnectSrc	string array	specify csp `connect-src`.	['connect-src']
ObjectSrc	string array	specify csp `object-src`.	['object-src']
FormAction	string array	specify csp `form-action`.	['form-action']
FrameSrc	string array	specify csp `frame-src`.	['frame-src']
PrefetchSrc	string array	specify csp `prefetch-src`.	['prefetch-src']
ManifestSrc	string array	specify csp `manifest-src`.	['manifest-src']
WorkerSrc	string array	specify csp `worker-src`.	['worker-src']

CertificateMode

none: client certificate is not accepted
require: client certificate is required
accept: client certificate is accepted

SslProtocol

Type System.Security.Authentication.SslProtocols, refer to docs.microsoft.com.

None
Ssl2
Ssl3
Tls
Tls11
Tls12
Tls13

SslCertificate

Server SSL certificate is used to setup SSL/https. See Certificate settings for further details how to configure certificates.

HeaderWhitelistOptions

Configure header name and values. At least one value from the request must match the configured ones. This option can be used, if an ip whitelist is not suitable because of a loadbalancer scenario. If so, LB very likely forwards a header X-Forwarded-For which contains the clients ip address.

Nested Object	Type	Description	Default
Name	string	Specifies the header name to be checked.	null
Values	string array	Specifies the values which at least one must match with the request.	null

Client

This object contains settings about the client behaviour of concrii.

Certificate

Client certificate is used to authenticate this concrii instance against further concrii instances (friends). See Certificate settings for further details how to configure certificates.

MaxSearchResults

String that specifies the maximum number of search results.

Serilog

Complex logging settings. Detailed explanations and docs can be found here. For detailed information about log filter with expressions, go [here] (https://githubhelp.com/serilog/serilog-filters-expressions).

Example:

"Serilog": {
  "Using": [
    "Serilog.Sinks.File",
    "Serilog.Expressions"
  ],
  "MinimumLevel": {
    "Default": "Error",
    "Override": {
      "bizconAG":  "Debug"
    }
  },
  "WriteTo": [
    {
      "Name": "File",
      "Args": {
        "path": "logs\\log.txt",
        "rollingInterval": "Day",
        "outputTemplate": "{Timestamp:yyyy-MM-dd HH:mm:ss.fff} [{ThreadId}][{Level:u3}]{RequestId} {Message:lj} <s:{SourceContext}>{NewLine}{Exception}"
      }
    }
  ],
  "Enrich": [
    "FromLogContext",
    "WithMachineName",
    "WithThreadId"
  ],
  "Properties": {
    "Application": "concrii"
  }
}

This example creates a new logfile every 24 hours named logYYYYMMdd.txt. All error logs will be captured, plus all concrii specific logs minimum level debug. The outputTemplate (one line within log file) is slightly modified to the known default one: Additional ThreadId, RequestId and SourceContext.

Note

RequestId information in log can be matched with the TraceId property in ErrorModel, see api.

Warning

Logging Exceptions ([Exception] at the end of outputTemplate) maybe is inappropriate running concrii in productive environment.

SerilogAudit

Complex audit logging settings. Detailed explanations and docs can be found here. When logging (auditing) to file, audit entries with it's specific properties can hardly be display with a line of text, as you might be used to from log entries. Therefore, we recommend using a json format for the audit log. See following example:

Example:

"SerilogAudit": {
  "Using": [
    "Serilog.Sinks.File",
    "Serilog.Expressions"
  ],
  "MinimumLevel": {
    "Default": "Information"
  },
  "Filter": [
    {
      "Name": "ByExcluding",
      "Args": {
        "expression": "EventId.Id in [1100,1101,2000]"
      }
    }
  ],
  "WriteTo": [
    {
      "Name": "File",
      "Args": {
        "path": "logs\\audit.log",
        "rollingInterval": "Day",
        "shared": true,
        "formatter": "Serilog.Formatting.Json.JsonFormatter, Serilog"
      }
    }
  ],
  "Enrich": [
    "FromLogContext"
  ],
  "Properties": {
    "Application": "concrii"
  }
}

This example creates a new logfile every 24 hours named auditYYYYMMdd.log. Audit always uses loglevel Information, thus do not configure any higher level like Warning or Error, otherwise, no audit records will be created. When using json format (recommended when writing audit records to file), no output template is necessary, because all properties will be part of the json object additionally to the created plain text message. Here, all events with id 1100 or 1101 or 2000 are excluded (see Filter EventId.Id in [2000]). Further filter exressions or adopting the existing one is allowed and appreciated to fullfill your audit requirements. For detailed information about log filter with expressions, go here.

Note

For a complete list of audit events go here.

Warning

Within serilog file audit configuration (WriteTo, property shared must be set to true ("shared": true), because several processes use this unique audit logger in parallel. Not specified (or set to false), concrii might create multiple audit files with additional filename endings _001, _002, ..., _00x.

Shared objects

Shared objects are used within multiple object configurations and are not part of appsettings.json root structure.

Assignments

In this object array, the actual assignment of formerly specified Roles and SubRoles takes place and are assigned to certain identities (individual, dependent on the used authentication method).

Attribute	Type	Description	Default
Filter	string array (context filter)	Specifies to which identity this assignment will be applied. See Filter.	null
Roles	string array	Roles to be assigned.	null
Policies	string array	Policies to be assigned.	null
Contexts	string array	Contexts to be applied.	null

ClaimTransformations

In this object array, the a certain claim (from received token, Type and Value must match exactly) can be mapped to additional claims to be added. If the original claim should be removed, set Replace = true.

Attribute	Type	Description	Default
Type	string	This must match exactly a claim type within initially received claims from token.	null
Value	string	This must match exactly a claim value within initially received claims from token.	null
Replace	boolean	If `true`, the original claim will be removed.	false
AssignClaims	object array	AssignClaim to be additionally assigned to the authenticated identity.	null

ClaimTransformationsAssignClaim

Specify a claim to be assigned additionaly to the authenticated identity.

Attribute	Type	Description	Default
Type	string	Type of the additionally assigned claim.	null
Value	string	Value of the additionally assigned claim.	null

User Filter

Filter authenticated user.

Attribute	Type	Description	Default
Identity.Name	string	Get the username.	null

Note

Please refer to Filter string functions.

Certificate Filter

Filter incoming client certificates.

Attribute	Type	Description	Default
Subject	string	Gets the subject distinguished name from the certificate.	null
Issuer	string	Gets the name of the certificate authority that issued the X.509v3 certificate.	null
IssuerName	string	Gets the distinguished name of the certificate issuer.	null
FriendlyName	string	Gets the associated alias for a certificate.	null
Thumbprint	string	Gets the thumbprint of a certificate.	null

Identity Filter

Filter logged in identities.

Attribute	Type	Description	Default
Name	string	Get name of identity (usually names claim).	null
Claims	array System.Security.Claims.Claim	Get identity claims.	null

Note

Please refer to Filter string functions and Claims functions.