Skip to content

Application Settings explained in detail

This chapter explains the following configuration sections:

{
  "Serilog" : {},
  "ConnectionStrings" : {},
  "Service" : {},
  "AllowedHosts": "*"
}

Serilog

The serilog settings are documented well here: https://github.com/serilog/serilog-settings-configuration

The Authorization Server ships, by default, with the sinks file, eventlog, async and seq, as well as the log enrichers

  • FromLogContext
  • WithMachineName
  • WithThreadId
  • WithProcessId

ConnectionStrings

The connection string section consists of key-value pairs of database provider to connection string. The database provider that is used by the application is set in Service.DatabaseProvider.

The following data providers are supported: mssql, postgresql, oracle, db2, sqlite and inmemory. The last two providers are only recommended for demo or development purposes.

"ConnectionStrings": {
  "postgresql": "Server=127.0.0.1;Port=5432;Database=auth;Userid=postgres;Password=postgres;Pooling=false;MinPoolSize=1;MaxPoolSize=20;Timeout=15;SslMode=Disable;",
  "oracle": "Data Source=localhost:1521/orcl.docker.internal;User Id=\"C##test_auth_user\";Password=password",
  "mssql": "Data Source=localhost;Initial Catalog=auth;Integrated Security=True",
  "sqlite": "Data Source=c:\\data\\auth.db"
}

Service

This is the main configuration section of the Authorization Server.

  • DisableHttpsRequirement: whether or not the Authorization Server will answer non-https requests. Defaults to false. This should only be enabled if it can be secured that no http traffic is susceptible for interception
  • Ssl: whether or not to use HSTS and HTTPS redirects
  • Session: fine-tuning SSO session parameters, allowing to trade ease of use with tighter security
  • DatabaseProvider: defines the connection string that is used and the database provider that will connect to a DB backend
  • DataProtection: configures the .NET DataProtection subsystem. In simple scenarios with only 1 Authorization Server it is not necessary to adjust it at all
  • AuthCertificates: encryption and signing certificates used by the OIDC framework OpenIddict
  • PluginAssemblyPath: allows to replace the default user authentication mechanism that works against the local Windows machine and/or ActiveDirectory with a custom authentication mechanism
  • Cors: allows to set allowed request origins. If set, only provided origins are allowed to send requests
  • Proxy: see "Setting up a load balancer" in the installation guide for more information

A short sample of this section

{
  "Service": {
    "DisableHttpsRequirement": false,
    "Ssl": {
      "EnableHttpsRedirection": false,
      "UseHsts": true,
      "HstsMaxAgeHours": 720
    },
    "Session": {
      "ExpirationTimeSpanSeconds": 7200, // expires the cookie after 7200 seconds. By default, the cookie expires only after 14 days.
      "CookiePath": "/auth", // in case of co-hosting with other services on a single VM, you can limit when the cookie is sent with requests. In thise case, the AuthorizationServer is hosted on https://my.contoso.com/auth
      "RefreshTokenLifetimeSeconds": 7200, // issued refresh tokens expire after 7200 seconds. The default is 14 days.
      "AccessTokenLifetimeSeconds": 1200   // shortlived access token. Default is 1 hour
    },
    "DatabaseProvider": "mssql",
    "DataProtection": {
      "ApplicationName": "myapp",
    },
    "AuthCertificates": {
      "Style": "automatic"
    },
    "PluginAssemblyPath": null, //"C:\\path_to\\AuthorizationService.SamplePlugin.dll",
    "Cors": {
      "Origins": []
    },
    "Proxy": {}
  }
}

DataProtection

The .NET DataProtection subsystem is used to ensure encryption at rest of sensitive data such as client secrets or user tokens.

If the keys are not stored in their default location, either by using PersistKeysInDatabase or PersistKeysPath, they are not encrypted at rest unless they are explicitly protected by configured certificates. Therefore, we recommend to set ProtectKeysThumbprint to the thumbprint of a certificate that can be found in the Windows certificate store that is accessible by the Authorization Server user. If that is not possible, provide the file and password.

  • ApplicationName: if set, allows shared access to protected payloads (data protection) if application base paths differ but multiple installed apps are working together
  • PersistKeysInDatabase: if set to true, the keys of the .NET DataProtection subsystem are stored in the Authorization Server DB. Defaults to false.
  • PersistKeysPath: in production scenarios with multiple machines, it is recommended to persist keys to a path and protect them. Defaults to "".
{
  "DataProtection": {
    "ApplicationName": null,
    "PersistKeysInDatabase": false,
    "PersistKeysPath": "",
    "ProtectKeysThumbprint": "",
    "ProtectKeysFile": "",
    "ProtectKeysPassword": "",
    "UnprotectWithMultipleKeys": false,
    "UnprotectMultipleThumbprint1": "",
    "UnprotectMultipleThumbprint2": "",
    "UnprotectMultipleFile1": "",
    "UnprotectMultiplePassword1": "",
    "UnprotectMultipleFile2": "",
    "UnprotectMultiplePassword2": ""
  }
}

AuthCertificates

These are certificates used by the OIDC framework OpenIddict. They may be used for encryption and signing of tokens. By default, OpenIddict automatically creates "development" certificates that are perfectly functional for a simple installation.

  • Style: defaults to automatic that automatically sets up certificates for the service user. For distributed installations, persisted is recommended
  • EncryptionCertificates/SigningCertificates: lists of certificates that are used for encryption and or signing. Multiple certificates can be specified to support certificate rotation
  • Thumbprint: A certificate thumbprint either in the LocalMachine or CurrentUser personal store (my). The Authorization Server requires of course access

  • Path/Password: in case it is not possible to use certificates from the certificate stores. Since the password cannot be protected, this requires that that machine on that the Authorization Server runs is secured.

    //"StyleOptions": "ephemeral (default), automatic, persisted",

{
  "AuthCertificates": {
    "Style": "persisted",
    "EncryptionCertificates": [
     {
       "Thumbprint": "a5511be2236f5d7f6ec8d95dc7e37fc54bf1e14b"
     },
     {
       "Path": "c:\\auth_svc\\openIddict_enc_cert2.pfx",
       "Password": "my secret pwd"
     },
    ],
    "SigningCertificates": [
     {
       "Thumbprint": "a5511be2236f5d7f6ec8d95dc7e37fc54bf1e14c"
     }
    ]
  }
}