SilhouetteTokenService Web Application Configuration
The configuration of the SilhouetteTokenService web application is completed through configuration files on the server. You must have privileged user access to the server to edit this configuration.
In the SilhouetteTokenService Web Application folder there is a file named 'appsettings.json' containing default settings and should not be modified. Settings are overridden by including a new production appsettings file named 'appsettings.Production.json'. The json files are text format files following the JSON format specified in RFC8259 and can be edited by any standard text editor, e.g. Notepad.
The only mandatory setting to include in the production appsettings file is the database connection string. Other settings will be included based on your needs. Not all settings are listed in this chapter, only those you are likely to need.
A very basic appsettings.Production.json file looks like:
{
"ConnectionStrings": {
"sts": "Data Source=.;Initial Catalog=silhouette;Integrated Security=true"
}
}
The convention used in this chapter when referring to members within the JSON file is to use a dotted notation (the chain of JSON member names separated by periods (.). For example, the connection string above can be referred to as ConnectionStrings.sts.
Where the property is part of an array or members, square brackets are used to indicate that
Changes to the appsettings are only applied when the associated application pool is recycled.
Database Connection String
The database connection string is a required setting and should be configured to connect to the SilhouetteCentral database.
{
"ConnectionStrings": {
"sts": "Data Source=.;Initial Catalog=silhouette;Integrated Security=true"
}
}
| Member Name | Value |
|---|---|
| ConnectionStrings.sts |
A MS SQL Server connection string. |
|
Once the SilhouetteCentral Initial Configuration Wizard is completed then the database connection string can be copied from the SilhouetteCentral web application MachineSettings.xml file. |
Logo
If a logo is uploaded in the SilhouetteCentral initial configuration wizard, you can set the SilhouetteTokenService to display the same logo on the login pages.
{
"Configuration": {
"CustomerLogoUrl": "/silhouette/api/v3/customfile/customerlogo"
}
}
| Member Name | Value |
|---|---|
| Configuration.CustomerLogoUrl |
The website path to the customer logo. This URL must be a reference to an image file on the same website as the SilhouetteTokenService. This is typically a path to the SilhouetteCentral API that contains the logo set in the SilhouetteCentral initial configuration wizard. For example: /silhouette/api/v3/customfile/customerlogo
|
Local Silhouette Users
The AccountSecurity section of the configuration sets the parameters for Local Silhouette User accounts and the associated password and account lockout rules.
"AccountSecurity": {
"AllowLocalLogin": true,
"Passwords": {
"ExpirationEnabled": false,
"ExpirationDays": 14,
"MinLength": 3,
"MaxLength": 20,
"MustContainAlphaAndNumeric": false,
"MustNotMatchUser": false,
"HistoryCount": 0
},
"Lockout": {
"Enabled": false,
"AfterFailedLogonCount": 6,
"CheckIntervalMinutes": 10
}
}
| Member Name | Value |
|---|---|
| AccountSecurity.AllowLocalLogin |
Set to true by default. Setting to false disables the ability to login for all Silhouette Local User accounts, including default ARANZ Support and Admin users. Only set to false if there is an external identity provider configured. |
| AccountSecurity.Passwords.MinLength |
The default value is 3 and the value can be set between 3 and the MaxLength setting. Sets the minimum length for Silhouette Local User account passwords. |
| AccountSecurity.Passwords.MaxLength |
The default value is 20 and the value can be set between the MinLength and 50. Sets the maximum length for Silhouette Local User account passwords. |
| AccountSecurity.Passwords.MustContainAlphaAndNumeric |
The default value is false. Set to true to require Silhouette Local User account passwords to have both at least one alphabetical character and one numeric character. |
| AccountSecurity.Passwords.MustNotMatchUser |
The default value is false. Set to true if Silhouette Local User account passwords must be different to the accounts User Name. |
| AccountSecurity.Passwords.HistoryCount |
The default value is 0 and the maximum value is 9. Sets the number of old Silhouette Local User account passwords that are remembered. When setting a new password, the user cannot select a password in the remembered history. |
| AccountSecurity.Lockout.Enabled |
The default value is false. Set to true to enable Silhouette Local User account lockout if there are too many failed login attempts. |
| AccountSecurity.Lockout.AfterFailedLogonCount |
The default value is 6. Sets the number of failed login attempts the user gets before their Silhouette Local User account is locked. |
| AccountSecurity.Lockout.CheckIntervalMinutes |
The default value is 10. Sets the period (in minutes) which failed login attempts must occur within for the Silhouette Local User account to be locked out. |
|
|
The AccountSecurity.Password settings also have paired settings in the SilhouetteCentral Organizational Settings which need to configured the same as these SilhouetteTokenService settings for robust operation. |
Logging
The SilhouetteTokenService uses the Serilog logging library. Some of the logging configuration is exposed and is able to be set. Not all configuration is included in the table below.
"Serilog": {
"MinimumLevel": {
"Default": "Information",
},
"WriteTo": [
{
"Name": "File",
"Args": {
"path": "Files/Logs/TokenServiceLog.txt",
"retainedFileCountLimit": "90"
}
}
]
}
| Member Name | Value |
|---|---|
| Serilog.MinimumLevel.Default |
The default value is "Information". Set to "Debug" to increase the level of logging for setup and debugging the configuration. This can be useful when setting up SAML2 integration. Production systems should not leave "Debug" level logging on under normal operating conditions. |
| Serilog.WriteTo[.Name="File"].Args.path |
The default value is "Files/Logs/TokenServiceLog.txt". Set to an alternative log file output path. The SilhouetteTokenService application pool must have Write and Modify access to this path. |
| Serilog.WriteTo[.Name="File"].Args.retainedFileCountLimit |
The default value is 90. Sets the number of rolled log files that kept. |
SAML2 Configuration
The Saml2 configuration section allows SSO with an external authentication provider. This configuration is only applied if there is a valid license for the SSO Integration optional feature.
"Saml2": {
"Enabled": true,
"AuthenticationSchemes": [
{
"Scheme": "Saml2",
"DisplayName": "Work ID",
"Metadata": "https://<domain name>/<path>/Saml2",
"ModulePath": "",
"IdentityProviders": [
{
"EntityId": "http://example.com/adfs/services/trust",
"Metadata": "https://example.com/FederationMetadata/2007-06/FederationMetadata.xml",
"LoadMetadata": true
}
],
"ClaimTypes": {
"FirstName": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname",
"LastName": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname",
"Email": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
"Group": "http://schemas.xmlsoap.org/claims/Group"
}
}
]
}
| Member Name | Value |
|---|---|
| Saml2.Enabled |
Set to true to allow sign-on with an external identity provider. If this value is set to true then at least one Saml2.AuthenticationScheme configuration object must be provided. Setting this value to false disables user login using external identity providers, leaving the provider configuration and user records in the Silhouette database. The default value is false. |
| Saml2.AuthenticationSchemes[].Scheme |
An identifier for the authentication scheme. Typically set this value to "Saml2" unless multiple authentication schemes are being defined. Removing or changing an authentication scheme, removes the ability to login using that identity provider and removes user records and provider claim to Silhouette group mapping configuration. |
| Saml2.AuthenticationSchemes[].DisplayName |
Set to a value that is reasonably short and meaningful to users logging in. The descriptive name used in the Silhouette UI. Some of the places it can be shown are:
|
| Saml2.AuthenticationSchemes[].Metadata |
Sets the Entity ID URI of the authentication scheme. The external Identity Provider will need to know this value. This value is typically the case sensitive SilhouetteTokenService Web Application URL plus the Scheme identifier. For example: https://private.example.com/silhouettetoken/Saml2
|
| Saml2.AuthenticationSchemes[].ModulePath |
Set to an empty string ("") unless there are more than one authentication schemes being configured. If set to an empty string the default value of Saml2 is used. This value explicitly sets where the SilhouetteTokenService hosts the various Saml2 endpoints, including the metadata and the Assertion Consumer services. Once set, the Saml2 relying party (RP) metadata can be downloaded from: https://<domain name>/<SilhouetteTokenService path>/<ModulePath>
The metadata downloaded from the metadata URL contains the Entity Id and the Assertion Consumer Services endpoints and can be used to configure a SAML2 Identity Provider (IdP). |
| Saml2.AuthenticationSchemes[].IdentityProviders |
This value is an array of objects describing identity providers that use this scheme. Silhouette expects a single identity provider object in this array. The identity provider object typically contains three members:
{ "EntityId": "http://example.com/adfs/services/trust", "Metadata": "https://example.com/FederationMetadata/2007-06/FederationMetadata.xml", "LoadMetadata": true }
|
| Saml2.AuthenticationSchemes[].ClaimTypes |
The ClaimTypes is an object that sets how the SilhouetteTokenService uses claims provided by the Identity Provider. The ClaimTypes object expects four members:
The typical configuration is listed here. { "FirstName": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname", "LastName": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname", "Email": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress", "Group": "http://schemas.xmlsoap.org/claims/Group" }
The claim type used for the User Name field (main account identifier) in Silhouette is not included in the ClaimTypes configuration. It uses either the JWT 'sub' claim or the Name ID (http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier) claim. |