Application settings

The following is an overview of all the application settings that the Unit4 Identity Services web applications use. The settings are read from web.config and overridden by Azure App Service application settings.

Application settings for main application

The main application is the U4IDS authority itself.

Connection strings

U4IDS reads database connections from the connection strings section of the application configuration. It is recommended to have the same database for operational and configuration data. The default name for the main database connection string is IDSConfig and defined like this:

    <connectionStrings>
      <add name="U4IDSConfig" connectionString=" / actual connection string / " providerName="System.Data.SqlClient" />
    </connectionStrings>

In production U4IDS has to use a central cache to avoid stale data when it scales horizontally. Connection to Redis cache service is also set as a connection string. In this example with the name RedisConfig.

    <connectionStrings>
      <add name="RedisConfig" connectionString=" / actual connection string / " />
    </connectionStrings>

In Azure all connection strings are overridden in the connection strings section of the app service configuration.

Store setup

Store setup settings governs how and from where operational and configuration data is read. In production we use database as the store for both types of data. Note the two different options for configuration-store:type. EntityFramework will read from the database schema that the local v1 administration API writes to. SQLDatabase will use SQL functions to read from the database schema that the external v2 and later administration API writes to.

Important: When configuration-store:type is set to SQLDatabase the local v1 endpoints on the main application will be disabled. All configuration is then done with the external v2 administration api. The default is EntityFramework to allow migration in a timely fashion after an upgrade to IDS 2.x.

Setting Description Default value
operational-store:type Type of store for operational data. EntityFramework for using the database. InMemory for development only EntityFramework
operational-store:connection-string Reference to database connection string for operational data database U4IDSConfig
operational-store:cleanup-interval Time interval in seconds for purging expired operational data like tokens 3600
configuration-store:type Type of store for configuration data (tenants, clients, scopes). EntityFramework for v1 database schema and administration api. SQLDatabase for v2 database schema and external administration API. JsonFile for development. EntityFramework
configuration-store:connection-string Reference to database connection string for configuration data database U4IDSConfig

Security setup

These settings are related to security and signing certificates

Setting Description Default value
SigningCertificateThumbprint Thumbprint of certificate used to sign tokens. Site will not start without it. empty
SigningCertificateStoreLocation Certificate store of the signing cert. Not relevant for Azure App Services. CurrentUser
SigningCertificateStoreName Certificate store name. Not relevant for Azure App Services. PERSONAL
WEBSITE_LOAD_CERTIFICATES Thumbprint of signing certificate to load into Azure App Service (in PERSONAL for CurrentUser). Set to same as SigningCertificateThumbprint. empty
security:override-redirect-uri-validator Allow arbitraty query string parameters for redirect uris so long as the path matches legal uris true

SAML setup

Settings related to how U4IDS acts as SAML-SP

Setting Description Default value
identityserver:providers: saml2:entity-id IDS SAML-SP Entity Id. Should be set to the public fully qualified domain name of the IDS authority https://myids-api.domain.com/identity. https://localhost:44300/identity
identityserver:providers: saml2:serviceProviderInstances Number of additional SAML-SP Entity Ids the IDS can act as. 5
identityserver:providers: saml2:minIncomingSigningAlgorithm Minimum signing algorithm IDS allow external SAML tokens to be signed with. http://www.w3.org/2000/09/xmldsig#rsa-sha1

API setup

The following settings govern what API the IDS is using, and how the local v1 admin api is configured if active.

Note: admin:api:base-url must be set to the external API root when using v2 administration interfaces. The other api related settings are not used when using v2 API as the v1 api endpoints are then disabled.

Setting Description Default value
admin:api:base-url v2 only. Base URL for the api site. The external site https://myids-api.domain.com/api when using v2 API. Use public fully qualified domain name. empty
admin:am-api:base-url v2 only. Base URL for the Access Management service. For example https://myam.domain.com/api. The setting is optional, but helps discovery by IDS portals. empty
admin:api:entity-framework-connectionstring v1 only. Reference to database connection string that local v1 uses to read and write configuration. U4IDSConfig
admin:api:authentication:enabled v1 only. If local v1 API require authentication. Only disable in development. true
admin:api:authentication:type Authentication mode of the API. basic for basic authentication and bearer for bearer authentication. Must be set for both v1 and v2. basic
admin:api:authentication:basic:username v1 only. Username when using basic authentication admin
admin:api:authentication:basic:password v1 only. Password when using basic authentication empty
admin:api:authentication:ids-bearer-token:authority v1 only. Public fully qualified domain name of the IDS authority itself for bearer token validation. https://localhost:44300/identity
admin:api:authentication:ids-bearer-token:clientId v1 only. Scope name for the IDS api resource. Set to u4ids-admin when using bearer token authentication. empty
admin:api:authentication:ids-bearer-token:clientSecret v1 only. Scope (api) secret for bearer reference token validation. Jwt tokens supported without this setting. empty
EnableSwagger v1 only. Enable or disable OpenAPI / Swagger metadata for the v1 api true
EnableSwaggerUI v1 only. Enable or disable Swagger development UI for the v1 api false

Caching setup

The following settings are related to configuring caching of configuration data.

Setting Description Default value
cache:enabled If caching is enabled or all config read from database. true
cache:type Type of cache. Either InMemoryfor development or Redis for production. Note that InMemory is disregarded when reading from v2 configuration schema / SQLDatabase, if not Redis then all reads are directly from database to avoid stale caches. InMemory
cache:default-duration The default lifetime for cache items in minutes. 60
cache:redis-configuration Only for type Redis. Reference to Redis connection string. empty
cache:redis-database Only for type Redis. If using a Redis service with other databases in it, a reference to the database U4IDS uses. empty

Cleanup Routines

External tokens and login information can get stale. We want to remove this data at regular intervals to prevent operational tables to get too large. You should probably leave these values at their default settings, but there could be scenarios where you want to change them.

Setting Description Default value
TokenCleanup:interval The number of seconds between each run 3600
TokenCleanup:batchSize The number of stale tokens that will be deleted at a time. This should not be too large, otherwise you might get database performance problems (Entity Framework does "range-deletions" very inefficiently) 100
LoginCleanup:interval The number of seconds between each run 3600
LoginCleanup:batchSize The number of stale "logins" that will be deleted at a time. This should not be too large, otherwise you might get database performance problems (Entity Framework does "range-deletions" very inefficiently) 100
LoginCleanup:olderThan Delete stale "logins" that are older than this (in days) 7

Logging setup

The following settings are related to configuration of logging. U4IDS uses the Serilog logging framework and fine tuned logging settings can be overridden beyond the listings here.

Setting Description Default value
Serilog:UseLogStreamFileSink Duende IdentityServer only. If you want to use the Azure Log Streaming feature, you need to set this to true false
serilog:minimum-level Minimum log level of log entries. Information
ApplicationInsights:InstrumentationKey Application insights instrumentation key for enabling trace to AppInsights empty

You can use normal Serilog configuration settings to change things like message template, add more sinks, etc. See the Serilog documentation for this (https://serilog.net/)

Partial login

Setting Description Default value
partial-login:enabled Set to true to enable partial logging False

IdentityServerOptions

U4IDS is based on Duende IdentityServer, and we have exposed some of the Duende IdentityServer options. Currently only a length restriction.

Setting Description Default value
IdentityServerOptions:InputLengthRestrictions:RedirectUri This setting was introduced in version 4.1.11. Prior to this, it was hard coded to 400 characters 1000

Bootstrapping of initial configuration client

When using Administration API v2 and later, basic authentication is not possible. The first configuration will be done with a client called u4ids-admin-client. The initial / default secret for this client is set in application settings:

Setting Description Default value
admin:client-secret Secret for u4ids-admin-client empty

Important: Without initial secret it is not possible to configure the first settings on U4IDS instances set up with v2 API. We reccomend that the first action is to add u4ids-admin-client using the API, as this will disable the built in secret and replace it with a generated one for further use. The support for the reserved u4ids-admin-client and initial secret is important for bootstrapping new IDS instances without first using the weaker basic authentication which was the case for earlier versions of U4IDS.

Application settings for Administration API site

From IDS version 2 the following settings are used on the external administration api site.

Connection strings

The Admin API site reads and writes configuration data to the database. It must be the same as configured for the main application. The name for the main database connection string is IdsConfig and defined like this:

    <connectionStrings>
      <add name="IdsConfig" connectionString=" / actual connection string / " providerName="System.Data.SqlClient" />
    </connectionStrings>

The Admin API will update central cache when changing configuration data. To do this it needs the connection string to the Redis service the main application is using. The name for the Redis connection string is RedisConfig:

    <connectionStrings>
      <add name="RedisConfig" connectionString=" / actual connection string / " />
    </connectionStrings>

Important: If the main application uses InMemory caching, or the Admin API is not configured with the Redis connection string, configuration data will not be immediately up to date.

Every change in the configuration data creates an audit entry in the database. The entity that is changed (scope, client or tenant) is serialized and compressed as part of this audit entry. If the database grows too large, it's possible to store the compressed entity in azure blob storage instead of the database. The connection string for this blob storage is called 'AuditStore'. If it exists exists, blob storage is used. 

    <connectionStrings>
      <add name="AuditStore" connectionString=" / actual connection string / " />
    </connectionStrings>

Important: Using AuditStore will slow down the response from the AdminAPI considerably, so it's only recommended as a troubleshooting feature. A better option is to purge the Audit Store. Audits that existed before you "turned on" AuditStore are not moved. Only new audits will be stored in the AuditStore.

In Azure all connection strings are overridden in the connection strings section of the app service configuration.

Authentication setup

The following settings are needed to set up authentication for the Administration API. Administration API only supports bearer authentication in production.

Note: The resource scope for managing U4IDS is always u4ids-admin and will be auto-provisioned if it does not exist.

Setting Description Default value
AuthenticationSettings:AuthenticationScheme Authentication scheme. Always set to bearer in production. Possible to set to basic for development. bearer
AuthenticationSettings:Bearer:IssuerUrl The public fully qualified domain name for the U4IDS issuer this API manages and verifies tokens against. empty
AuthenticationSettings:Bearer:ApiSecret The scope secret for the u4ids-admin scope. Used to verify reference tokens. If the secret is not in the database, it is auto provisioned. If empty only Jwt tokens are accepted. empty
(AdminApiSettings:ApiSecret) Version 3.1 only. Same as 'AuthenticationSettings:Bearer:ApiSecret' above, but because of a known bug, you need to set them both to use this feature. This was not an issue in 3.0 and V2, and is fixed in 3.2 empty
AuthenticationSettings:Bearer:AdminRole The optional value of external role claims that allow users to manage U4IDS. For external authorization of administration users. IDSADMIN
AuthenticationSettings:AdminTenant The tenant id for the administration tenant. The administration tenant user's can manage all aspects of the IDS configuration. Important to set when using Access Management and allowing tenant-administrators in the Portal empty
AccessManagementApiSettings:ApiUri The optional location of Unit4 Access Management api for internal authorization of administration users. For example https://myam.domain.com/api/v1/. empty
AuthenticationSettings:Bearer: AccessManagementClient Client id for validating internal roles for administration users against the Access Management service empty
AuthenticationSettings:Bearer: AccessManagementClientSecret Client secret for validating internal roles for administration users against the Access Management service empty

These settings are only important when you want to troubleshoot startup problems for the Admin API service, or if you are doing development and want to change the state of the database.

If the startup of the AdminAPI service takes more than 2 minutes in total, the service will restart, and the database migration (which is part of the startup) will stay in an undefined state. In this case, restarting the service will not help. You will have to set MigrationAction to force and maybe also increase the CommandTimeout. In addition, you will have to update the web.config file in Azure manually, to increase startupTimeLimit (part of the <aspNetCore> tag). The default value is 120 (2 minutes). In general, startup should take seconds and not minutes.

Setting Description Default value
EntityFramework:CommandTimeout The time it takes before an SQL command times out (in seconds). We set it pretty high because some of the migration commands could take a long time. 300
EntityFramework:MigrationAction (new in version 3.2) This setting should always be "normal" unless you are troubleshooting something. "Normal" means that before the API service starts, it will update the database with any changes and populate the database with default scopes. If several services starts up at the same time, only one service will be able to do this at a time. See legal values below. normal
EntityFramework:MigrationWait (new in version 3.2) If updating the database fails (i.e. another service is already updating the database), how long (in seconds) should we wait before we try again. 5
EntityFramework:MigrationRetries (new in version 3.2) How many times the API service will try to update the database before giving up. When giving up, it will start the API service without updating the database. 10

Legal values for EntityFramework:MigrationAction

Value Description
normal Run "database update" (migrations) when the API service starts. This includes populating the database with the default scopes
none Start the API service without updating the database (i.e. we are not running migrations). This should only be used for troubleshooting.
force Run migrations without checking if someone else is already running it. This should only be used for troubleshooting. Make sure only one process is running if doing this. If several API services are running, this can cause the database to become unstable.
specific:<name> Should only be used for troubleshooting. You can roll back the database to a specific Migration. The names of the migrations can be found in the __EFMigrationHistory table.
Setting Description Default value
AuthenticationSettings:AuthenticationScheme:Basic:ClientId When in development setting up basic authentication, the fixed user name empty
AuthenticationSettings:AuthenticationScheme:Basic:Secret When in development setting up basic authentication, the fixed user password empty
AccessManagementApiSettings:ApiScope Overridden scope name of the standard u4am-public-api scope for access management. u4am-public-api

Logging setup

The administration site for U4IDS uses the Serilog logging framework and fine tuned logging settings can be overridden beyond the listings here uses. ApplicationInsights events are logged when the instrumentation key is present.

Setting Description Default value
ApplicationInsights:InstrumentationKey ApplicationInsights instrumentation key. Set to same key as used in main application site. empty
Serilog:MinimumLevel:Default Log detail level. Set to Information in production. Information
Serilog:MinimumLevel:Override:System Log detail level override for system logs. Set to Warning in production. Warning
Serilog:MinimumLevel:Override:Microsoft Log detail level override for system logs Set to Warning in production. Warning
Logging:LogStreamPath The location for the log file. To make Azure LogStream work, this path must start with "D:\home\LogFiles\" D:\home\LogFiles\Application\
Logging:LogStreamFile The name of the log file AdminApi.txt

Admin Scope setup

Setting Description Default value
AdminScope:AllowedForTenantSpecificClients Tenant specific clients doesn't normally have access to create or configure clients and scopes. I.e. you can't add the u4ids-admin scope to AllowedScopes for a Client that has a value for OwnerTenant. You can override this limitation by adding this application setting with the value True. Not existing