Implementing Out-of-the-Box Authentication Management

At an MCS/FCS server, user interaction is absent and credentials must be provided programmatically. This topic describes how system administrators can implement out-of-the-box authentication management.

Before you begin: Note that these steps must be done with every MCS/FCS server.
See Also
About FCS Network Security
About FCS Network Security Views
Implementing Custom Authentication Management
FCS Network Security Error Messages
  1. Set MX_HTTP_DEFAULT_CLIENT_AUTHENTICATION to true.
  2. Use MxValidateCredentials.class to validate the format of the credentials file. The syntax is as follows:
    java -classpath %CLASSPATH% MxValidateCredentials credentialfile
  3. Name the credential file mxNetworkCredentials.xml, and place it under %MATRIXINSTALL%/etc/. The format is explained below. The property MATRIX_INSTALL must be declared as the path of the matrix server directory (for example, C:/enoviav6r2011/server/).

    Warning: This folder is not created by default and must be created. Moreover, this folder must not be confused with the folder %MX_MATRIXINSTALL%/%OS%/etc/ .

  4. To encrypt the credentials file, set MX_ENCRYPT_NETWORK_CREDENTIALS to true.
    1. Use MxEncryptCredentials.class to create a key and encrypt the credentials file. The syntax is as follows:
      java -classpath %CLASSPATH% MxEncryptCredentials credentialfile

      The original credentials file can now be discarded.

    2. Optional: Use MxEncryptCredentials.class to reverse the credentials for verification. The syntax is as follows:
      java -classpath %CLASSPATH% MxEncryptCredentials -reverse

    • For encrypted credentials, it is technically OK to encrypt the credentials file once and copy it to all MCS/FCS servers, assuming that the credentials file content is the same.
    • MX_HTTP_CLIENT_AUTHENTICATION_CLASS has the first precedence.
    • MX_ENCRYPT_NETWORK_CREDENTIALS defaults to false.
    • You must restart the server if the credentials file is modified.
    • The MxValidateCredentials.class and MxEncryptCredentials.class can simply be launched inside MQL.

Example Credentials File

The credentials file is an XML-based file. The following is an example of a credentials file:

<auth>
   <credential>
      <username>creator</username>
      <password></password>
      <host>1.1.1</host>
      <port>*</port>
      <protocol>http</protocol>
      <scheme>BASIC</scheme>
      <prompt>80</prompt>
      <site>*</site>
      <url>*</url>
      <type>proxy</type>
   </credential>
</auth>

The XML file should have a single root node called <auth>, and contain zero or more <credential> nodes.

The <credential> element contains exactly ten child nodes:

  • username - the user name used to respond to the authentication challenge
  • password - the password used to respond to the authentication challenge
  • host - the host condition to use the username and password (* for anything)
  • port - the port condition to use the username and password (* for anything)
  • protocol - the protocol condition to use the username and password (http, https, or * for anything)
  • scheme - the scheme condition to use the username and password (BASIC, DIGEST, NLTM, or * for anything)
  • prompt - the prompt (also known as "realm") condition to use the username and password (* for anything)
  • site - the site condition to use the username and password (* for anything)
  • url - the target URL condition to use the username and password (* for anything)
    Note: The target URL is the URL to which the original request was sent.
  • type - the type condition to use the username and password (server, proxy, or * for anything)
Note: All nodes should be declared. Use * for nodes that are not of interest. The values of these nodes should not contain non-ASCII characters.