Last update: October 19, 2022

Configuration

This section explains the basic configuration for the Notifications module.

IdentityOptions

There are options to configure the ASP.NET Core Identity system. For more information, read this guide.

Node	Default or sample value	Description
Password.PasswordHistory	E.g., 4	The number of recent user passwords to check during password validation. An old password cannot be reused for this number of cycles. If the value is set to 0 or not defined, the password history will be disabled.
Password.RepeatedResetPasswordTimeLimit	0:01:0	The time limit after which a user can request a password reset.
Password.PasswordChangeByAdminEnabled	true	Application setting to disable administrators from setting passwords for users in the system. If you set PasswordChangeByAdminEnabled to false, admin UI and API will limit changing the password for administrators.
User.MaxPasswordAge	90	The time span defining the maximum user password age until it expires. The user is forced to change the expired password upon login to the Platform Manager UI. If the value is set to 0 or not defined, password expiration will be disabled.
User.RequireUniqueEmail		A boolean setting that enforces unique email addresses for user accounts, when enabled. When this setting is enabled, users will not be able to register or use an email address that is already associated with another user account.
User.RemindPasswordExpiryInDays	7	Number of days to start showing a password expiry warning in the Platform Manager UI. Used only when password expiration is enabled.
Lockout.AutoAccountsLockoutJobEnabled	false	A boolean value indicating whether the automatic accounts lockout job is enabled.
Lockout.LockoutMaximumDaysFromLastLogin	365	An integer value representing the maximum number of days since the last login before an account is locked out.
Lockout.AutoAccountsLockoutJob	default: "0 0 * * *"	A string defining the cron expression for the automatic accounts lockout job.
Lockout.DefaultLockoutTimeSpan		The time span for which a user account is locked out when it exceeds the lockout thresholds. This setting defines how long a user's account will be locked after a certain number of failed login attempts.

Examples

Set PasswordChangeByAdminEnabled to falseSet AutoAccountsLockoutJobEnabled to true

The result will be as follows:

DataProtection

There are options to configure lifetimes for security tokens that are issued by platform like password reset.

Node	Default value	Description
DataProtection.TokenLifespan	"1.00:00:00" - Defaults to 1 day	The amount of time a generated token remains valid.

Example

Example settings for the DataProtection section:

"DataProtection": {
        "TokenLifespan": "24:00:00",        
    },

AzureAd

This node is used for authentication with Azure Active Directory. Check how to enable authentication with Azure Active Directory for details.

Node	Default or sample value	Description
Enabled	false	Enables authentication with Azure Active Directory. By default, this value is false, i.e. the authentication is deisabled.
UsePreferredUsername	false	If set to true, the system will check the preffered_username in case the upn claim returns empty.
Priority	0	Configures the priority of the Azure Active Directory login popup on the Login page. The lowest value means the highest priority.
AuthenticationType		Provides the authentication scheme. Must always have the AzureAD value set.
AuthenticationCaption		Sets a human-readable caption for the Azure AD authentication provider. Visible on the Sign In page.
ApplicationId	01234567-89ab-cdef-0123-456789abcdef	The ID of the Virto Commerce platform application registered in Azure Active Directory. You can find it in the Azure control panel through Azure Active Directory → App registrations → (platform app) → Application ID.
TenantId	abcdef01-2345-6789-abcd-ef0123456789	The ID of the Azure AD domain that will be used for authentication. You can find it in the Azure control panel through Azure Active Directory → Properties → Directory ID.
AzureAdInstance	https://login.microsoftonline.com	URL of the Azure AD endpoint used for authentication.
DefaultUserType	Manager Customer	Default user type for new users created upon first sign in by Azure AD accounts.
DefaultUserRoles	Order manager Store manager	Default user roles assigned to new users created upon first sign-in by Azure AD accounts.
MetadataAddress		An optional setting that enables the discovery endpoint for obtaining metadata. Must be set only when your app has custom signing keys.
UsePreferredUsername	false	Indicates whether to use the preferred_username claim as a fallback scenario in case the UPN claim is not set for getting user name.

Note

Note to the MetadataAddress node

If your app has custom signing keys as a result of using the claim mapping feature, you should append the appid query parameter containing the app ID in order to get a jwks_uri pointing to your app's signing key information. For instance, https://login.microsoftonline.com/{tenant}/v2.0/.well-known/openid-configuration?appid=6731de76-14a6-49ae-97bc-6eba6914391e contains a jwks_uri of https://login.microsoftonline.com/{tenant}/discovery/v2.0/keys?appid=6731de76-14a6-49ae-97bc-6eba6914391e.

Example

Example settings for the AzureAD section:

"AzureAd": {
        "Enabled": true,
        "AuthenticationType": "AzureAD",
        "AuthenticationCaption": "Azure Active Directory",
        "ApplicationId": "b6d8dc6a-6ddd-4497-ad55-d65f91ca7f50",
        "TenantId": "fe353e8f-5f08-43b4-89d1-f4acec93df33",
        "AzureAdInstance": "https://login.microsoftonline.com/",
        "DefaultUserType": "Manager",
        "UsePreferredUsername": false,
        "Priority": 0
    },

Crud

This configuration node defines settings for the CRUD operations within the system.

Node	Default or sample value	Description
MaxResultWindow	2147483647	The maximum value for the combination of skip and take parameters in search requests. By setting this value to 2147483647, there are no specific limits on the number of records that can be retrieved in a single search request. This effectively allows retrieving a large number of records in a single query.

Example

"Crud": {
    "MaxResultWindow": 2147483647
}

Application Insights

Add and customize the Application Insight section in the appsettings.json file.

Node	Default or sample value	Description
SamplingOptions.Processor	Adaptive Fixed	Lets you choose between two sampling methods: Adaptive sampling: automatically adjusts the volume of telemetry sent from the SDK in your ASP.NET/ASP.NET Core app, and from Azure Functions. Read more Fixed-rate sampling: reduces the volume of telemetry sent from both applications. Unlike adaptive sampling, it reduces telemetry at a fixed rate controlled by SamplingPercentage setting.
IncludedTypes	Dependency Event Exception PageView Request Trace	A semi-colon delimited list of types to be sampled. The specified types will be sampled. All telemetry of other types will always be transmitted. All types are included by default.
ExcludedTypes	Dependency Event Exception PageView Request Trace	A semi-colon delimited list of types not to be sampled. All telemetry of the specified types is transmitted. The types that aren't specified will be sampled. Empty by default.
EnableSqlCommandTextInstrumentation	true false	For SQL calls, the name of the server and database is always collected and stored as the name of the collected Dependency Telemetry. Another field, called data, can contain the full SQL query text. To opt in to SQL Text collection, set this setting to true.
IgnoreSqlTelemetryOptions		Controls the Application Insights telemetry processor that excludes SQL queries related to dependencies. Any SQL command name or statement that contains a string from the QueryIgnoreSubstrings options will be ignored.

Example

To configure 'ApplicationInsights':

1. Use current active telemetry configuration which is already initialized in most application types like ASP.NET Core:

   {
     "ApplicationInsights": {
       "ConnectionString": "<Copy connection string from Application Insights Resource Overview>"
     }
   }
   

2. Configure Platform AP telemetry behavior inside the VirtoCommerce:ApplicationInsights section:

   {
     "VirtoCommerce": {
       "ApplicationInsights": {
         "SamplingOptions": {
           "Processor": "Adaptive",
           "Adaptive": {
             "MaxTelemetryItemsPerSecond": "5",
             "InitialSamplingPercentage": "100",
             "MinSamplingPercentage": "0.1",
             "MaxSamplingPercentage": "100",
             "EvaluationInterval": "00:00:15",
             "SamplingPercentageDecreaseTimeout": "00:02:00",
             "SamplingPercentageIncreaseTimeout": "00:15:00",
             "MovingAverageRatio": "0.25"
           },
           "Fixed": {
             "SamplingPercentage": 90
           },
           "IncludedTypes": "Dependency;Event;Exception;PageView;Request;Trace",
           "ExcludedTypes": ""
         },
         "EnableSqlCommandTextInstrumentation": true,
         "IgnoreSqlTelemetryOptions": {
           "QueryIgnoreSubstrings": [
             "[HangFire].",
             "sp_getapplock",
             "sp_releaseapplock"
           ]
         }
       }
     }
   }
   

PasswordLogin

This node enables authentication with username and password.

Node	Default or sample value	Description
Enabled	true	Always enabled by default. Setting to false will disable logging in with username and password.
Priority	0	Configures the priority of the password login popup on the Login page. The lowest value means the highest priority.

LoginPageUI

This node is used for configuration of the background screen and background pattern of the Login page.

Node	Default or sample value	Description
BackgroundUrl		Login page background URI. If set, takes priority over the preset.
PatternUrl		Login page background pattern URI. If set, takes priority over the preset.
Preset	demo	Login page background preset name. If set, searches the preset from the preset list and applies BackgroundUrl and PatternUrl from it.
Presets		A list of background presets.

Example

Example settings for the Presets node:

"Presets": [
    {
      "Name": "demo",
      "BackgroundUrl": "",
      "PatternUrl": "/images/pattern-demo.svg"
    },
    {
      "Name": "prod",
      "BackgroundUrl": "",
      "PatternUrl": "/images/pattern-live.svg"
    }
]