Encrypt Credentials in .NET Agent Configuration

On this page:

Related pages:

By default the AppDynamics .NET Agent stores the following credentials in the config.xml file:

Controller account authentication
proxy server authentication

For environments where security policies require you to secure credentials stored on disk, you can run an unattended installation that encrypts the credentials for the .NET Agent and writes them to the Windows Credential Manager.

Storing credentials for the .NET Agent using the Windows Credential Manager updates the config.xml file to use a schema the AppDynamics Agent Configuration utility doesn't currently support.

If you follow these instructions, you can't use the configuration utility to make configuration changes afterward. If you launch the configuration utility on a server where you have stored credentials in the Windows Credential Manager, the utility will prompt you to delete the configurations.

Requirements

You run the AppDynamics.Agent.Coordinator service as the LocalSystem account.
To modify credentials after you install, you need Windows Sysinternals.

Setup Configuration File

You must generate a setup configuration file in order to run an unattended installation. For a detailed description, see 'Setup Configuration File Properties' on Unattended Installation for .NET.

New Installation

For new installations, use one of the following methods to create the setup configuration file:

Run the AppDynamics Agent Configuration utility from the command line and pass the -s parameter to specify the setup configuration file destination. For this options, you must execute the .NET Agent MSI installer package on one machine before running the configuration utility.
```
%ProgramFiles%\AppDynamics\AppDynamics .NET Agent\AppDynamics.Agent.Winston.exe -s <path to setup configuration file>
```
Manually create a setup configuration file from a sample template.

Remove any plain-text authentication elements from the setup configuration file. You pass the credentials as part of the unattended installation command:

Controller Account element:
<account name="myaccount" password="myaccesskey"/>

Proxy Authentication element: If you are using a proxy authentication, use the following format in the setup configuration file.

<proxy host="myproxy.example.com" port="3128" enabled="true">   
   <authentication enabled="true" domain="mydomain.com"/>  
</proxy>

Upgrade

If your upgrade meets the criteria for an in-place upgrade on Upgrade the .NET Agent for Windows, you can encrypt the credentials for the .NET Agent and upgrade the agent at the same time.

Copy the AppDynamics Agent element from your existing config.xml file to the setup configuration file. Remove any plain-text authentication elements from the setup configuration file. You pass the credentials as part of the unattended installation command:

Controller Account element:
<account name="mycontroller.saas.appdynamics.com" password="myaccesskey"/>
Proxy Authentication element:
<authentication enabled="true" user_name="my_proxy_user" password="password" domain="my_windows_domain"/>

Sample Setup Configuration File

The following example shows a setup configuration file that instruments: two IIS Applications, MainBC and SampleHTTPService; a Windows service, BasicWindowsService; and a standalone application, MyStandaloneApp.exe.

<winston>
  <logFileDirectory directory="C:\ProgramData\AppDynamics\DotNetAgent\Logs" />
  <logFileFolderAccessPermissions defaultAccountsEnabled="false">
    <account name="NT AUTHORITY\LOCAL SERVICE" displayName="LOCAL SERVICE" />
    <account name="NT AUTHORITY\SYSTEM" displayName="SYSTEM" />
    <account name="NT AUTHORITY\NETWORK SERVICE" displayName="NETWORK SERVICE" />
    <account name="IIS_IUSRS" displayName="ApplicationPool Identity" />
  </logFileFolderAccessPermissions>
  <appdynamics-agent xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <controller host="mycontroller.appdyanmics.com" port="443" ssl="true">
      <application name="My Business Application" />
    </controller>
    <machine-agent />

    <app-agents>
      <IIS>
        <applications>
          <application path="/" site="MainBC">
            <tier name="Main Site" />
          </application>
          <application path="/" site="SampleHTTPService">
            <tier name="HTTP Services" />
          </application>
        </applications>
      </IIS>
      <standalone-applications>
         <standalone-application name="BasicWindowsService" args="-x">
            <tier name="Windows Service Tier"/>
         </standalone-application>
         <standalone-application executable="MyStandaloneApp.exe">
            <tier name="Standalone App" />
         </standalone-application>
      </standalone-applications>
    </app-agents>

  </appdynamics-agent>
</winston>

Install from the Command Line

To install the .NET Agent from the command line:

Download the .NET Agent MSI Installer Package from the AppDynamics Download Center.
Launch an elevated command prompt with full administrator privileges. See Start a Command Prompt as an Administrator.

Logging on to Windows as a member of the Administrators group does not grant sufficient permissions to run the installer.
Stop IIS and, if you're upgrading, stop instrumented Windows services and Standalone applications.

Run the following command to install the agent with encrypted credentials. See below for a description of command line options.

msiexec /i <path_to_MSI_installer_package> /l log.txt /q AD_SETUPFILE=<path_to_setup_configuration_file> AD_SECURED_CREDENTIALS=true AD_CONTROLLER_ACCOUNT_NAME=<SaaS or multi-tenant account> AD_CONTROLLER_ACCOUNT_ACCESS_KEY=<access key> AD_PROXY_USERNAME=<proxy user name> AD_PROXY_PASSWORD=<proxy password>

For example:

msiexec /i "%USERPROFILE%\Downloads\dotNetAgentSetup.msi" /l log.txt /q AD_SETUPFILE="%USERPROFILE%\Documents\SetupConfig.xml" AD_SECURED_CREDENTIALS=true AD_CONTROLLER_ACCOUNT_NAME=MyAppDynamicsAccount AD_CONTROLLER_ACCOUNT_ACCESS_KEY=changeme AD_PROXY_USERNAME=MyProxyUser AD_PROXY_PASSWORD=ProxyPass

The MSI installer package installs the .NET Agent and encrypts the credentials and writes them to the Windows Credential Store. It adds the Controller secure attribute to the Controller element in the config.xml file and sets the value to true:

<controller host="mycontroller.appdyanmics.com" port="443" ssl="true" secure="true">

Start IIS. Restart or start instrumented Windows services and standalone applications.

Update Credentials in the Windows Credential Manager

The .NET Agent includes a Credentials Tool so you cam modify credentials stored in the Windows Credential Manager. To change credentials under the Local System account, you need to use PsExec to launch the command prompt.

If you have not already, download and install Windows Sysinternals.
Use PsExec to launch a command prompt as the Local System account.
```
psexec -i -s cmd.exe
```

Run the Credentials Tool and pass the updated credentials.

"%programfiles%\AppDynamics\AppDynamics .NET Agent\AppDynamics.CredentialsTool.exe" AD_CONTROLLER_ACCOUNT_NAME=<SaaS or multi-tenant account> AD_CONTROLLER_ACCOUNT_ACCESS_KEY=<access key> AD_PROXY_USERNAME=<proxy user name> AD_PROXY_PASSWORD=<proxy password>

Command Line Options

AD_SECURED_CREDENTIALS: Set to true to encrypt credentials to the Windows Credential Store and configure the agent to use the encrypted credentials.
AD_CONTROLLER_ACCOUNT_NAME: The account name for the SaaS or multi-tenant Controller.
AD_CONTROLLER_ACCOUNT_ACCESS_KEY: The account access key for the SaaS or multi-tenant Controller.
AD_PROXY_USERNAME: The proxy server user account.
AD_PROXY_PASSWORD: The password for the proxy server user account.