Foglight Agent Manager 5.8.5.2

Windows Remote Management is the Microsoft® implementation of the Web Services Management Protocol (WSMAN) which is a Simple Object Access Protocol (SOAP) based protocol over HTTP/HTTPS and is used for system management. For more information, visit https://msdn.microsoft.com/en-us/library/aa384470%28v=vs.85%29.aspx.

WinRM has two authentication mechanisms that are used by the Agent Manager to establish connections:

•

Negotiate authentication is based on Kerberos authentication, involving tickets/keys obtained from a Key Distribution Center (KDC).

•

Basic authentication uses standard HTTP headers to communicate directly with the remote machine.

When the Agent Manager is installed on AIX, Negotiate authentication is not currently supported. In such cases, only Basic authentication can be used. For more information, see Available WinRM Connection Schemes when the Agent Manager Runs on AIX.

Understanding Negotiate/Kerberos Authentication

Kerberos is a network security protocol that involves three elements: the KDC, the client user, and the server with the desired service to access. The KDC is installed as part of the Domain Controller and acts as the authentication service and the ticket-granting service.

Each administrative domain has its own KDC, which contains information about the users and services for that particular domain. This administrative domain is a Kerberos realm.

The steps involved in Kerberos authentication involve the following actions:

Initial Authentication for a Kerberos Session (Kerberos step 1)

A client begins a Kerberos session by requesting a ticket-granting-ticket (TGT) from the KDC based on the domain user name. This is done automatically on Windows login, but can be repeated when a different KDC is needed for a service on a different realm.

The KDC creates a TGT and sends it back to the client, in encrypted form, based on the client's password. The client decrypts the TGT using the client's password.

In possession of a valid TGT, the client can request tickets for various services.

Subsequent Kerberos Authentications (Kerberos step 2)

When the client requires access to a service using Kerberos authentication, the client requests a ticket for the particular service, from the KDC by sending the TGT as proof of identity.

The KDC sends the ticket for the specific service to the client.

The client can then send this ticket to the remote server to establish a session with the server's service.

Finding the Kerberos Authentication File

Foglight Agent Manager always generates an auth.login.config file that is used for Kerberos. It is generated by the Agent Manager on both UNIX® and Windows®, and is used to configure the Kerberos module that the Agent Manager uses for authentication. This file is located in the <fglam_dir>/state/default/config directory, and must never be modified.

Observing the Contents of the Kerberos Configuration File

The Kerberos configuration file specifies the KDC from which tickets are obtained. Operating systems sometimes have their own Kerberos configuration files. If present, the Agent Manager uses them by default. They can be found in the following locations:

•

Windows: %WINDIR%\krb5.ini which typically translates to C:\Windows\krb5.ini

•

UNIX:

•

/etc/krb5.conf

Or:

•

/etc/krb5/krb5.conf

If none of these files are found, the Agent Manager attempts to create its own kerberos configuration file, based on the detected settings. The detection can only be done on Windows, so on Unix, the file is not generated. On Unix platforms, you need to create your own Kerberos configuration files to establish WinRM connections using Negotiate authentication.

To detect the settings on Windows, the following environment variables are checked:

•

%LOGONSERVER%: Provides the name of the domain controller that authenticated the client's logon to the machine. This value is just the simple name of the KDC, but the fully qualified name must be used in the configuration file.

•

%USERDNSDOMAIN%: Provides the fully qualified DNS domain that the currently logged on user's account belongs to.

These two environment variables are only present when the user credential used to login to the machine, is a domain credential, for example, when the user account belongs to the domain. If a local user account is used, these environment variables are not present, and an attempt to generate the Kerberos configuration file is made using the network information. If not found, the file is not generated.

If you are running the Agent Manager on a UNIX machine, to determine the values to use in the Kerberos configuration file for the remote machine, simply log in to the remote machine using a domain user credential and check the values. The format of the file is as follows:

[libdefaults]

default_realm = <REALM_NAME_IN_CAPS>

[realms]

<REALM_NAME_IN_CAPS> = {

kdc = <fully_qualified_kdc_name>

}

[domain_realm]

.<domain_in_lower_case> = <REALM_NAME_IN_CAPS>

If the Kerberos configuration file is generated by the Agent Manager, it is placed in the <fglam_dir>/state/default/config/krb5.config file, and an entry is added to the <fglam_dir>/state/default/config/fglam.config.xml file so that the Agent Manager is aware of the file location. An example of this entry on Windows is as follows:

<config:krb5-config-file>C:\Quest_Software\fms_6_2_0_206\state\fglam\state\default\.\config\krb5.config</config:krb5-config-file>

If the file is not generated, you can generate your own file, add a value for the krb5-config-file entry in the fglam.config.xml file, and restart the Agent Manager.

About the Kerberos Configuration File Format

The Kerberos configuration file typically looks like:

[libdefaults]

default_realm = EXAMPLE.COM

[realms]

EXAMPLE.COM = {

kdc = HOST1.EXAMPLE.COM

}

[domain_realm]

.example.com = EXAMPLE.COM

•

Any line that begins with a number sign '#' is considered a comment, and is ignored.

•

The default_realm value is used to determine what KDC should be used, if the realm cannot be determined from the domain.

•

The [realms] section is used to provide the KDC for the specified realm

•

The [domain_realm] section is used to map the domain to the realm to use.

So for example, if connecting to a host A with user credential example.com\UserX, the kerberos file is used as follows:

The domain is determined from the user credential, so in this case the domain name is example.com.

The domain example.com maps to the realm EXAMPLE.COM in the domain_realm section.

The realm EXAMPLE.COM is then found, and its KDC value is used to determine the KDC to use for authentication.

The KDC, HOST1.EXAMPLE.COM, is then communicated with for authentication.

In another example, if connecting to a host B with user credential other.domain\UserY, the same Kerberos file is used as follows:

The domain is determined from the user credential, so in this case the domain name is other.domain.

The domain other.domain does not map to any realm in the domain_realm section, so the KDC is attempted to be resolved from the DNS.

Typically, the DNS does not find the KDC for the different domain, and so the default_realm value, EXAMPLE.COM is used instead.

The realm EXAMPLE.COM is then found, and its KDC value is used to determine the KDC to use for authentication.

The KDC, HOST1.EXAMPLE.COM, is then communicated with for authentication of the user credential.

To specify a non-default realm to use for the other.domain value is the second example, the Kerberos configuration file can be modified as follows

[libdefaults]

default_realm = EXAMPLE.COM

[realms]

PROD.QUEST.CORP = {

kdc = HOST1.EXAMPLE.COM

}

OTHER.DOMAIN = {

kdc = MYKDC.OTHER.DOMAIN

}

[domain_realm]

.example.com = EXAMPLE.COM

.other.domain = OTHER.DOMAIN

Now, if a domain of other.domain is encountered, the realm used will be OTHER.DOMAIN instead of the default_realm value since there is a domain mapping entry. This can be repeated for other domains and realms.

This is the reason that fully qualified domain names be used for the domain value of the credential. Also, to prevent any possible DNS issues with the KDC, the fully qualified name of the host should be used, such as A.example.com or B.other.domain.

There are other sections and properties that can be used in the Kerberos configuration file, but for the Agent Manager purposes, the ones described above are sufficient.

About the Cross-Realm Negotiate Authentication Behavior

Cross-realm or cross-domain is the mechanism of using WinRM Negotiate authentication to establish a connection to a machine in a different domain. There are also some differences here between behavior when the Agent Manager uses Java 6 and Java 7.

Understanding Basic Authentication

The Basic authentication mechanism simply provides HTTP headers to the remote machine, to provide the credentials that should be used for authentication. There is no use of a configuration file or a KDC. The mechanism provides no protection for the transmitted credentials, since they are simply encoded in base64 and not encrypted or hashed. To address any security concerns, it is recommended that Basic authentication attempts are made over an HTTPS and not HTTP connection. Since the KDC is not involved in the authentication process, the credentials used for Basic authentication must be local user credentials, such as local user credentials for the remote machine, and not domain user credentials.

When the remote machine is contacted, the remote machine responds indicating that Basic authentication needs to be used by the client. The client side then base64-encodes the user name and password and sends an HTTP request with an HTTP header containing the base64-encoded result to the remote machine, which then validates the provided credential.

Since local user credentials are used, and a KDC is not needed, the domain the host is on is irrelevant for Basic authentication.

About WinRM Authentication and the Agent Manager

The Agent Manager supports Basic and Negotiate WinRM authentication schemes with Windows credentials. The Negotiate authentication scheme is enabled by default in WinRM and is the recommended way to authenticate in most environments.

In order to establish connections over Windows® Remote Management (WinRM), you must provide a Windows credential. For more information, see Configuring Credentials.

The Negotiate authentication scheme requires fully-qualified domain accounts. For example, instead of using the NetBIOS domain, the Windows credential should be configured with the fully qualified domain.

The Basic authentication scheme requires local Administrator accounts; you cannot use domain accounts. For more information, see Promoting remote users to administrators on local machines through the Domain Controller. Basic authentication is insecure because it transmits user names and passwords in an easily decoded string, and therefore it should not be used on an untrusted network. If Basic authentication is required, and security is a concern, configure the target system to accept only HTTPS traffic. For more information, see Manually configuring WinRM HTTPS access. If Basic authentication is not acceptable in your environment because of some specific security concerns, it can always be disabled.

Basic and Negotiate authentication schemes are not mutually exclusive when it comes to their configuration. The remote system can be enabled to use both authentication schemes, given a specific order of preference. For example, a remote machine can be configured to first attempt the Negotiate authentication, and it fails, to subsequently try the Basic authentication. Therefore, if you enable Basic authentication, there is no need to disable Negotiate authentication requests, and the other way around. However, you can disable either scheme, as required.

In general, if Basic authentication is not suitable, it should be disabled. If both Negotiate and Basic authentication are enabled, and Negotiate fails, Basic authentication is still attempted, and the credentials are transmitted in an easily decoded string. Because of different credential requirements for Negotiate (a domain user credential) and Basic (a local administrator credential), a credential only applies to one authentication type. Therefore a general recommendation is that if Basic authentication is required, Negotiate authentication does not have to be disabled. But if Negotiate authentication is needed, best practice is to disable Basic authentication requests.

You can also use Windows Group Policy Objects to automatically configure HTTP or HTTPS listeners in WinRM. For more information, see Using Group Policy Objects to configure WinRM.


	IMPORTANT: For WinRM connections on Windows Vista, Service Pack 1 (SP1) or later must be installed.

Configuring the Target (Monitored) System

Recent versions of Windows® OS include WinRM, but it is disabled by default. There are two ways to configure HTTP or HTTPS: manually or using Group Policy Objects.

Manually Configuring WinRM HTTP Access

To manually configure the target machine for WinRM authentication:

Open a command prompt window on the target machine.

Type the following:

winrm quickconfig

This enables the default WinRM configuration and disables payload-level encryption.


	IMPORTANT: Payload-level encryption encrypts only the contents of the messages that are exchanged between the Agent Manager and the monitored system. It does not affect the security of any credentials passed between the target system and the Agent Manager. If you require full encryption, configure the WinRM server to use HTTPS. HTTPS safely and securely encrypts all data transmitted between the Agent Manager and the monitored system.

The default WinRM settings allow only Negotiate authentication.


	NOTE: You can enable Basic authentication without disabling Negotiate authentication. Some systems can have both Negotiate and Basic authentication enabled, in that order of preference. If Negotiate authentication fails, a Basic authentication request is attempted.

To enable Basic authentication:

Open a command prompt window on the target machine.

Type the following:

winrm set winrm/config/service/auth @{Basic="true"}

winrm set winrm/config/service @{AllowUnencrypted="true"}

Optional. If Negotiate authentication is enabled, and you want to disable it, type the following:

winrm set winrm/config/service/auth @{Negotiate="false"}


	TIP: To enable or disable either Basic or Negotiate authentication, use the following command syntax: winrm set winrm/config/service/auth @{<Basic\|Negotiate>="<true\|false>"}

Manually configuring WinRM HTTPS access

If additional security is required, for example if data is transferred across untrusted networks, you can configure WinRM to use HTTPS. A valid server authentication certificate must be installed on the target machine in order to enable HTTPS.


	NOTE: You cannot use self-signed certificates.

The certificate must be granted by a recognized certificate-granting authority (CA) in order for the Agent Manager to authenticate it. Otherwise you must install the root CA certificate in the Agent Manager’s trusted keystore, as described in Installing HTTPS certificates.


	TIP: Install the certificates in the following location: Certificates (Local computer)/Personal/Certificates

To enable HTTPS access:

Open a command prompt window on the target machine.

Issue the following command:

winrm quickconfig -transport:https

The above command enabled HTTPS access using the certificate installed on the host.

If you want to use a different certificate, you can create a new HTTPS listener and specify the certificate:

winrm create winrm/config/listener?Address=*+Transport=HTTPS

@{Hostname="<host>";CertificateThumbrint="<thumbprint>"}

Where:

•

host is a fully qualified host name, as it appears in the certificate.

•

thumbprint is the certificate thumbprint, with spaces removed.

Using Group Policy Objects to configure WinRM

You can use Windows Group Policy Objects to automatically configure HTTP or HTTPS listeners in WinRM. Enable or disable the appropriate default group policies that are pre-installed with Windows, or use the defaults as a template to develop new policies.

To view the default policies:

On the target machine, click Start.

Type run and press Enter.

In the Run dialog box that appears, type mmc and click OK.

The Console Root window appears.

In the Console Root window, choose File > Add/Remove Snap-In.

In the Add or Remove Snap-ins dialog box that appears, in the Available snap-ins area, select Group Policy Object, and click Add.

In the Select Group Policy Object dialog box that appears, click Finish to close it.

Click OK to close the Add or Remove Snap-ins dialog box.

In the Console Root window, in the navigation tree on the left, choose Local Computer Policy > Computer Configuration > Administrative Templates > Windows Components > Windows Remote Management (WinRM) > WinRM Service.

Review the settings on the right. Double-click a setting to edit its state.

After you have edited the settings as necessary for your environment, close the Console Root window.

Installing HTTPS certificates

In environments where an in-house certificate granting authority (CA) is in use, the CA’s certificate must be added to the Agent Manager’s trust keystore. The Agent Manager then assumes that the authority, and any signed certificates it issues, are trusted.

To add a certificate to the keystore:

Ensure that the Agent Manager is running.

Launch a command shell on the Agent Manager machine, and navigate to the <fglam_home>/bin directory.

Issue the following command:

fglam --add-certificate alias=/path/to/saved.ca.certificate

If the import succeeds, the Agent Manager automatically recognizes and uses the certificate.