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 toSQLDatabase
the local v1 endpoints on the main application will be disabled. All configuration is then done with the external v2 administration api. The default isEntityFramework
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 InMemory for 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 reservedu4ids-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 |
Database related settings
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. |
Development related settings only. Not supported in production
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 |