Skip to main content

appsettings.agent

The appsettings.agent.json file is meant to contain configuration data to be used by the agent to run Usercube.

It includes:

  • connections to the managed systems;
  • password reset settings;
  • connections to potential additional databases;
  • OpenId information;
  • specific task configuration.

JSON files can contain any additional information that you might find useful. See the example below.

For example, in order to store the agent's address, we can add:


appsettings.json

"UsercubeAgent": {
  "Url": "http://localhost:1234"
}

As Usercube does not know any object named UsercubeAgent, its content will be ignored, but it can still be used to store information for human use.

Supported Sections​

NameDetails
Connections optionalType List of Connections Description Connection information of all the systems managed by this agent, for synchronization and fulfillment configuration. This section contains a subsection for each connection containing the connection's agent settings. { � "Connections": { � "<ConnectionIdentifier>": { "<AgentSetting>": "<Value>": � } } }Example{ � "Connections": { � "Directory": { "Path": "C:\UsercubeDemo\Sources\Directory.xlsx" }, "ServiceNowExportFulfillment": { "Server": "https://INSTANCE.service-now.com/api/now/table", "Login": "LOGIN", "Password": "PASSWORD" } } } See how to configure connections' agent settings via the UI. See more technical details on connections.
Databases optionalType List of Databases Description Names and connection strings of all databases used by the agent through InvokeSqlCommandTask, other than Usercube's database and other than the databases provided in Usercube's available packages. This subsection contains a subsection for each additional database. { � "Databases": { "<DatabaseName>": "<DatabaseConnectionString>" } }Example{ � "Databases": { "UsercubeContoso": "data source=.;Database=Usercube;Integrated Security=SSPI;Min Pool Size=10;encrypt=false;" } }
OpenId optionalType OpenId Description OpenId information, i.e. the ClientIds and related ClientSecrets that the agent may use to authenticate to the server in order to launch jobs and tasks. In order to launch jobs and tasks, the profiles related to these OpenId credentials must possess the required permissions. See examples below.
PasswordResetSettings optionalType PasswordResetSettings Description Parameters which configure the reset password process for the managed systems that support it. See examples below.
SourcesRootPaths optionalType String Array Description List of folder paths from which Usercube is allowed to read. This option is used to validate the sources files defined in file-based connections. These paths are case sensitive. Example{ � "SourcesRootPaths": [ "C:/identitymanagerContoso/SourceHR", "C:/identitymanagerContoso/SourcesPhone" ] }
TaskAgentConfiguration optionalType TaskAgentConfiguration Description Various settings to customize the behavior of some agent tasks. See examples below.

OpenId​

NameDetails
AgentIdentifier requiredType String Description Identifier of the agent, as it is named in the XML configuration. Example With the following configuration: <Agent Identifier="MyAgent" DisplayName_L1="My Agent" URI="https://contoso.com" /> We could have the following setting in the agent's appsettings.agent.json: { � "OpenId":{ � "AgentIdentifier": "MyAgent" } }
DefaultOpenIdClient requiredType String Description ClientId that defines the default OpenId pair, from the OpenIdClients section, used by the agent to authenticate to the server. Example{ � "OpenId":{ "OpenIdClients": { "Job": "secret1", "Admin": "secret2", "Agent": "secret3" }, "DefaultOpenIdClient": "Agent" } }
OpenIdClients requiredType List of OpenIdClients Description Pairs of ClientIds and non-hashed ClientSecrets, to override the corresponding secrets specified in the XML configuration. Example { � "OpenId":{ "OpenIdClients": { "Job": "secret", "Admin": "secret2" } } }

PasswordResetSettings​

NameDetails
EncryptionCertificate requiredType [EncryptionCertificate] Description Location of the public key certificate and the private key used to handle input and output files' encryption.
MailSettings optionalType MailSettings Description Settings for configuring the SMTP server, used to send password reset email notifications.
NotificationSettings optionalType NotificationSettings Description Settings to configure password reset notifications.
TokenBuildingSettings optionalType TokenBuildingSettings Description Settings to build the confirmation token used by the password reset's two-Way mode. The confirmation token is a base-64 encoded JSON Web Token (JWT) token that contains the information required to complete password reset when in two-way mode. It is appended to the confirmation Uri.
TwoFactorSettings optionalType TwoFactorSettings Description Settings to configure the password reset's two-way mode, i.e. the process where Usercube sends emails containing links to users for them to click on it and reset their passwords.

EncryptionCertificate​

If you are using the certificate provided in the SDK, the agent will be unable to launch. You must create your own certificate.

Encryption certificate information can be set in one of two ways:

  • as a PKCS #12 archive (also called Personal Information Exchange file or .pfx file) stored in the agent's host file system. The archive contains both the public key certificate and the private key;

    NameDetails
    File requiredType String Description PKCS #12 archive path on the agent's host file system. Example{ � "PasswordResetSettings": { "File": "C:/identitymanagerAgentContoso/contoso.pfx" } }
    Password optionalType String Description PKCS #12 archive password. Example{ � "PasswordResetSettings": { "File": "C:/identitymanagerAgentContoso/contoso.pfx", "Password": "oarjr6r9f00" } }

  • as a certificate from a Windows' certificate store, identified by its subject distinguished name or its thumbprint. The Windows certificate also contains both the public key certificate and the private key.

    NameDetails
    DistinguishedName requiredif Thumbprint is emptyType String Description Subject distinguished name of the certificate. Example{ � "PasswordResetSettings": { "DistinguishedName": "UsercubeContoso" � } }
    StoreLocation requiredType String Description Location of the relevant Windows certificate. Example{ � "PasswordResetSettings": { � "StoreLocation": "LocalMachine" } }
    StoreName requiredType String Description Name of the relevant Windows certificate. Example{ � "PasswordResetSettings": { � "StoreName": "AuthRoot" } }
    Thumbprint requiredif DistinguishedName is emptyType String Description Thumbprint of the certificate. Example{ � "PasswordResetSettings": { "Thumbprint": "6261A70E599642A21A57A605A73B6D2AE7C5C450" � } }

MailSettings​

NameDetails
FromAddress requiredif PickupDirectory is emptyType String Description Email address used by Usercube to send notifications. Example{ � "PasswordResetSettings": { � "MailSettings": { "FromAddress": "no-reply@acme.com", � } } }
Host requiredif PickupDirectory is emptyType String Description SMTP server domain name or an IP address. Note: to be used only when UseSpecifiedPickupDirectory is set to false.
Password requiredType String Description Password that Usercube will use to login to the SMTP server. Note: used only when the SMTP server is password-protected and UseSpecifiedPickupDirectory is set to false.
PickupDirectory requiredif FromAddress/Host are emptyType String Description Path to the pickup directory. See more details on the pickup directory feature. Note: to be used only when UseSpecifiedPickupDirectory is set to true. Example{ � "PasswordResetSettings": { � "MailSettings": { "PickupDirectory": "../Mails", � } } }
Username requiredType String Description Username for Usercube to login to the SMTP server. Note: used only when the SMTP server is password-protected and UseSpecifiedPickupDirectory is set to false.
AllowedDomains optionalType String Description List of domains to which the SMTP server is authorized to send emails. Domain names must be separated with ;.
CatchAllAddress optionalType String Description Catch-all address that will receive all of Usercube's emails instead of usual users. Note: this is helpful for testing before going live. Example{ � "PasswordResetSettings": { � "MailSettings": { "CatchAllAddress": "administrator@acme.com", � } } }
CatchAllCCAddress optionalType String Description Catch-all address that will receive all of Usercube's emails as cc (carbon copied). Example{ � "PasswordResetSettings": { � "MailSettings": { "CatchAllCCAddress": "administratorcc@acme.com", � } } }
Enabled default value: TrueType Boolean Description True to enable email sending. When set to false, no email is sent by Usercube.
EnableSsl default value: FalseType Boolean DEPRECATED: EnableSsl won't be supported in the future. Please specify a SecureSocketOption instead. To keep the same behavior as EnableSsl: True, use the setting SecureSocketOption: StartTls. Description True to encrypt communication with the SMTP server. Note: to be used only when UseSpecifiedPickupDirectory is set to false.
SecureSocketOption default value: AutoType String Description Specifies the encryption strategy to connect to the SMTP server. If set, this takes priority over EnableSsl. None: No SSL or TLS encryption should be used. Auto: Allow the mail service to decide which SSL or TLS options to use (default). If the server does not support SSL or TLS, then the connection will not be encrypted. SslOnConnect: The connection should use SSL or TLS encryption immediately. StartTls: Elevates the connection to use TLS encryption immediately after reading the greeting and capabilities of the server. If the server does not support the STARTTLS extension, then the connection will fail and a NotSupportedException will be thrown. StartTlsWhenAvailable: Elevates the connection to use TLS encryption immediately after reading the greeting and capabilities of the server, but only if the server supports the STARTTLS extension. Note: to be used only when UseSpecifiedPickupDirectory is set to false.
Port default value: 0Type String Description SMTP server port. Note: to be used only when UseSpecifiedPickupDirectory is set to false.
UseDefaultCredentials default value: FalseType Boolean Description True to use the default username/password pair to login to the SMTP server. When set to false, Windows authentication is used. Note: to be used only when UseSpecifiedPickupDirectory is set to false.
UseSpecifiedPickupDirectory default value: FalseType Boolean Description True to write emails as local files in the specified PickupDirectory instead of sending them as SMTP packets. See more details on the pickup directory feature. Example{ � "PasswordResetSettings": { � "MailSettings": { "UseSpecifiedPickupDirectory": true, � } } }

NotificationSettings​

NameDetails
Cultures default value: ["en"]Type String Array Description List of languages in which reset-password email notifications will be sent, among: fr; en. Example{ � "PasswordResetSettings": { � "NotificationSettings": { "Cultures": ["fr", "en"] } } }

TokenBuildingSettings​

NameDetails
ValidFor default value: 03:00:00Type String Description Validity period of the issued token, and thus of the password reset link. The format must be HH:mm:ss. Example{ � "PasswordResetSettings": { � "TokenBuildingSettings": { "ValidFor": "03:00:00" } } }

TwoFactorSettings​

NameDetails
ApplicationUri requiredType String Description URI of the Usercube application. Note: this helps create the links in the emails for two-way password reset. Example{ � "PasswordResetSettings": { � "TwoFactorSettings": { "ApplicationUri": "http://localhost:5000" � } } }
ResetConfirmationUri requiredType String Description Base URI for the password reset link that is sent to the user. The password reset confirmation token is appended to the ResetConfirmationUri. The resulting URI is sent to the user. Example{ � "PasswordResetSettings": { � "TwoFactorSettings": { � "ResetConfirmationUri": "http://localhost:5000/PasswordReset/Activate/?activationCode=" } } }

TaskAgentConfiguration​

NameDetails
HttpClientTimeoutSupplement default value: 0Type Integer Description Additional minutes that extend the default timeout (30 minutes) of the HttpClient instance used to send requests to the server. Example Here the total timeout will be 50 minutes: { � "TaskAgentConfiguration": { � "HttpClientAdditionalTimeout": 20 } }