Creating physical web server resources

After you create logical HTTP connections, you must create physical web server resources and bind the logical HTTP connections to the physical resources so that you can use those resources to create tests and virtual services (stubs).

Before you begin

If you are using SSL, you must have valid certificate keystore files in your workspace.

About this task

This task involves the manual creation of physical web server resources. However, two alternative automatic methods are available to create these resources:
  • You can use topology discovery to model the components of your system under test.
  • You can synchronize with an external application or file.

Procedure

  1. Open the Physical View of the Architecture School perspective, and from the toolbar click Web > Web Server.

    Alternatively, open the Logical View, right-click an existing HTTP connection and click Set Binding in > <environment_name> > Create new Web Server.

  2. Optional: Enter a name in the Name field for the HTTP transport to distinguish this transport from other possible HTTP transports.
  3. Click Settings to configure the basic settings of the transport.
    These settings define which HTTP traffic to record:
    Table 1. Web server wizard Settings page fields
    Field Description
    Host

    The host name or IP address of the computer that hosts the web server to which to connect.
    Port The port number through which to connect.
  4. Optional: Configure the following settings, if applicable to the transport you are setting up.
    1. Configure the Client settings based on the details in the following table:
      Table 2. Web server wizard Client page fields
      Field Description
      Virtual Client Address The client equivalent of a bind address. This address refers to the network that is used to make the outbound connection. This address is also known as the local address.
      Max connections per host The maximum number of connections that HCL OneTest™ API can maintain with the host. The default value is 100.
      Proxy Server
      Proxy Host The host name or IP address of the computer that hosts the proxy server that is used in place of the web server.
      Proxy Port The number of the port through which to connect with the proxy server.
      Username The user name used to log on to the Proxy Host.
      Password The password associated with the user name of the proxy server.
      NTLM Domain The domain name used by NT LAN Manager as part of Microsoft's Integrated Windows™ Authentication.
      Authentication The following types of authentication are available:
      Option Description
      None No credentials are requested.
      Basic The user name and password are sent over the network in plain text.
      Digest A hash function is applied to the password before it is sent.
      Kerberos Single Sign-On (SSO), or the Kerberos principal and password are used.
      NTLM The user name, password, and NT LAN Manager domain are requested.
      All The user name, password, and domain are required.
      Use preemptive Basic authentication Select the check box to enable pre-emptive authentication or clear the check box to disable pre-emptive authentication.

      With pre-emptive authentication, the client sends the authorization header with all requests rather than only when it is requested by the server.

      The Username, Password, and Domain fields, if completed, are used to authenticate to the web server that lies behind the proxy server.

      Note: Basic authentication and pre-emptive authentication are not secure authentication methods as the user name and password are sent over the network in plain text. For more information, refer to the RFC 2617 documentation in Related information.
    2. Configure the Kerberos settings, if applicable to the transport.
      Specify the settings for SSO or the Kerberos principal and password for HTTP authentication. In case of a Kerberos principal and password, configure authentication to the HTTP server by using the following:
      • A Kerberos Realm and Key Distribution Center (KDC)
      • An external krb5 configuration file
      The following table describes the authentication settings:
      Field Description
      Use SSO (Run with current user credentials)
      SSO allows you to run HTTP transport tests without a user name and password. However, the following limitations apply:
      • SSO is available only on the Windows platform.
      • When running a test from HCL OneTest™ API as a Windows user, you must be authorized to access the configured HTTP server.
      • When running a test from a HCL OneTest™ API Agent, the agent must have been started as a Windows user that is authorized to access the configured HTTP server.
      • The computer on which the test is running must have a Windows registry setting as follows: 
        HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\Lsa\Kerberos\Parameters
Value Name: allowtgtsessionkey 
Value Type: REG_DWORD 
Value: 0x000000001 (default is 0)
      Principal

      A Kerberos principal represents a unique identity to which Kerberos can assign tickets to access Kerberos-aware services. Enter the alias of the principal that you want to use for authentication.
      Password

      The password of the principal that you want to use for authentication.
      Kerberos Realm

      A set of managed nodes that share the same Kerberos database. Typically, this is the fully qualified domain name. For example, MYDOMAIN.ABC.COM.
      KDC The fully qualified host name of the computer that contains the KDC service. This might also be the domain controller or Active Directory host. For example, DC.MYDOMAIN.ABC.COM.
      Use external krb5 config file The folder path to the krb5 configuration file. Click Browse to select one.
  5. Optional: Cick Server to configure client socket settings and socket overrides, by using the details in the following table:
    Note: These settings configure the behavior of the transport when it is used in a stub. Client socket settings define the response that is sent when this transport is used as a server as part of a stub and a request is received that is not matched to a running stub.
    Table 3. Web server wizard Server page fields
    Field Description
    Client Socket Settings
    Response Timeout (ms) The number of milliseconds a stub is given to respond before the default response is sent.
    Default Response code The default code to be returned by the stub if no match is found for the request. The default value is 503.
    Default Reason Phrase The default message to be returned by the stub if no match is found. The default value is "No Stub available that matches the request".
    Server Socket Overrides
    Port By default, the stub listens on the port specified in the Settings tab. If that port is in use by another program or process, the stub must listen on a different port. If no alternate port is specified in this field, one is chosen at random, which is not a problem as long as the proxy server is routing traffic. However, if the real client needs to address the stub directly, enter an alternate port number in this field.
    Bind Address

    You can enter a bind address to force the HTTP transport to listen to the incoming connections on a specific network interface. This bind address is then used in the routing rules when the HTTP traffic has to be redirected to stubs.

    If you do not enter a value in this field, the HTTP transport listens to the incoming traffic on all available network interfaces. The address of the first network interface that is available is used in the routing rule. This address can be overridden with the value that is specified in the Recording Bind Address field of Library Manager.
    Authentication The following types of authentication are available:
    Basic
    Username and Password are sent over the network in plain text.
    Digest
    A hash function is applied to the Password before it is sent.
    NTLM
    An NT LAN Manager Domain is requested in addition to the other required fields. Either Basic or Digest must also be selected.
    All
    Username, Password, and NT LAN Manager Domain are accepted.
    Realm You can specify a realm name to be prepended, with a slash (/), to a username, in the form realmName/personalName@domainName.
    Domain You can specify a domain name to be appended, with an at-sign (@), to a user name, in the form realmName/personalName@domainName.
    Send Nonce You have the option to send an arbitrary number to be used in digest access authentication.
    Opaque You can specify a string of data to be returned unchanged by the server. This field is used to send state information around a network.
    State You can save the current state between authentication requests.
    Algorithm Specify the algorithm to be used for digest authentication.
    QOP options Specify the quality of protection (QOP) for authentication. The following values can be used to indicate to the client how the digest value should be calculated:
    • auth
    • auth-int
    Auth Params Specify any additional authorization parameters required as name-value pairs.
  6. Optional: Click Header to add name-value pairs to the header properties.

    These headers are sent with every message action such as Send Request or Send Reply. You can use fixed values or environment tags. Also, you can override the values by manually adding the same header to the messaging action.

    Note: You can use these headers to automatically differentiate stub replies from the system replies. Proxied traffic routed to the system under test by way of the stub pass-through mechanism also contains these headers.
  7. Optional: Optionally, click SSL to configure the secure socket layer settings for the transport.
    Click SSL to configure the secure socket layer (SSL) settings for the transport. The SSL settings are described in the following table:
    Field Description
    Use SSL Select this check box to enable security for the transport.

    Selecting the check box makes the other controls on the SSL tab available. You can enable security for Testing (Client) or Virtualization (Server) or both.
    Server certificates to trust All available identity stores are displayed in the drop-down list. Select one of the following menu items:
    Field Description
    Trust All

    To accept any certificate presented by the server, regardless of its validity. This option is the default and assumes you are focused on testing an application rather than the security of the server.
    New

    To define a new identity store.
    Identity store To specify an identity store, that contains certificates that the client is to trust.
    Client identities to give to the server All available identity stores are displayed in the drop-down list. If you use mutual authentication, a suitable identity is selected from the chosen identity store. Select one of the following menu items:
    Field Description
    None

    If the server does not request an identity.
    New

    To define a new identity store.
    Identity store

    To use an existing identity store. Specify an alias in the Identity field.
    Certificate source All available identity stores are displayed in the drop-down list. You can select one of the following menu items:
    Field Description
    Generated

    To use a certificate that Rational® Integration Tester generates for you. The source for that certificate is displayed in the Signed by field.
    New

    To define a new identity store.
    Identity store

    To use a certificate from an identity store.
    Signed by If you chose Generated in the Certificate source field, this field holds the location of a certificate within the Rational® Integration Tester installation directory that is used to generate the new certificate. This is a read-only field.
    Identity If you specified an identity store in the Certificate source field, use this field to specify the alias of a key in that identity store.
    Certificate Authorities a stub will trust All available identity stores are displayed in the drop-down list. You can select one of the following menu items:
    Field Description
    Trust All

    To accept any certificate presented by the client.
    New

    To define a new identity store.
    Identity store

    To specify an identity store that contains certificates that the stub is to trust.
    Override default protocols If you are required to use a specific version of the secure sockets protocol, such as SSLv2 or TLSv1.2, enter that algorithm name here.
  8. Optional: Click Recording to configure the recording settings of the transport.
    1. Use the following table to configure the settings based on the transport you are configuring:
      Table 4. Web server wizard Recording page fields
      Field Description
      Recording Mode The following options are available:
      Packet Capture
      Requires packet capture software.
      • On Windows™ systems, Network Packet Capture is included in the installation program of HCL OneTest™ API.
      • On non-Windows™ systems, libpcap is typically installed by default. If necessary, you can download the latest package from http://www.tcpdump.org/.

      For more information about packet capture, refer to Limitations of packet capture in Related reference.

      External Proxy Server
      The proxies in HCL Quality Server are used by HCL OneTest™ API and HCL OneTest™ Virtualization to record all HTTP(S) traffic that is routed through the proxy. For more information, refer to HTTP/TCP proxy setup in Related concepts.
      Envoy Proxy (Experimental)
      The proxies in HCL Quality Server are used by HCL OneTest™ API and HCL OneTest™ Virtualization to record all HTTP(S) traffic that is routed through the Envoy Proxy (Experimental). You must provide the config id that you configured in the admin_config of the Envoy Proxy.
      Istio
      Select this option if you are recording the HTTP(S) traffic that is routed through the Istio services port in any Kubernetes cluster.
      Istio via HCL OneTest™ Server
      Select this option if you are recording the HTTP(S) traffic that is routed through the Istio services port in the Kubernetes cluster that hosts HCL OneTest™ Server.
    2. Optional: Complete the following steps to change the default options displayed in the Recording Mode list in the Recording tab.
      1. Open the Preferences window by clicking Project > Preferences in the menu bar. Alternatively, click Window > Preferences in the menu bar.
      2. Click Recording.
      3. Under Transport Specific Recording, click an option in the Default Method for IP based list.
      4. Click Apply.
      5. Click OK.
  9. Optional: Click the Experimental tab to configure the OpenID Connect settings for the transport.
    When you enable the OpenID Connect Offline Access, the settings entered in this tab are used to obtain an access token. The access token is used in the HTTP Authorization header of requests made over the transport.
    Note: You must be familiar with the OpenID Connect 1.0 specifications to configure the OpenID Connect Offline Access. For more information about the OpenID Connect specifications, refer to the OpenID Connect Documentation in related links.
    1. Select the Use OpenID Connect Offline Access check box to enable the fields.
    2. Configure the fields based on the descriptions in the following table:
      Table 5. Web server wizard, Experimental page fields
      Field Description

      Token endpoint

      The token endpoint is used by the client to obtain an access token by presenting its authorization grant or refresh token.

      The token endpoint can be specified either relative to the configured server for the transport or as a full URL.

      Client id

      The identity used when sending requests to the token endpoint.

      Client secret

      The secret or password that corresponds to the client ID to authenticate the client with the authorization server.

      Client assertion

      For additional security, you can use a client assertion instead of a client secret. With client assertion, the client uses an X.509 certificate to prove the token request came from the client.

      Refresh token

      The credentials used by the client to obtain access tokens from the authorization server.

      Scopes

      The scopes for which access is requested.
  10. Click Test Transport to verify that the connection works.
    Restriction: While you are configuring the transport for Istio, the Test Transport action is not able to complete the test as the Web Server configured in the settings tab is a service within the Kubernetes cluster and the host and port configured are not reachable to HCL OneTest™ API.
  11. Click OK.

Results

A new physical web server resource is added to your project. In the Physical view of the Architecture School perspective, the web server is displayed with the port number included in the name.

What to do next

To use a physical resource, you must bind it to a logical resource in an environment. See Creating logical HTTP connections.