Creating physical web server resources

After you create logical HTTP connections in IBM® DevOps Test Integrations and APIs (Test Integrations and APIs), 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).

If you are using SSL, you must have valid certificate keystore files in your workspace.
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.
  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. 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 hostname 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 Client settings based on the details in the following table, if applicable to the transport.
    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 Test Integrations and APIs can maintain with the host. The default value is 100.
    Proxy Server
    Proxy Host The hostname 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 Integrated Windows™ Authentication specifications.
  5. Optional: Click 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 Select an authentication that you want to use for the connection from the following options:
    • Basic
    • Digest
    • NTLM
    • All
    After you select the authentication type, some or all the fields are enabled and you can enter the details as described in the following table:
    Field Description
    Realm

    Enabled when you select Basic, Digest, and ALL.

    You can specify a realm name to be prefixed, with a slash (/), to a user name, in the form realmName/personalName@domainName.

    The following fields are enabled when you select the Digest or All authentication type.

    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: Click Authentication to configure the authentication type.
    1. Select an authentication type from the list.
      The following authentication types are available for selection:
      • None
      • Basic
      • Digest
      • NTLM
      • Basic, Digest and NTLM
      • Kerberos
      • OAuth2
    2. Perform the actions for the authentication type that you selected as described in the following table:
      Authentication type Actions
      None There are no credentials that are required to authenticate the connection.
      Basic
      Perform the actions as described in the following table:
      Field Action

      Username

      Enter the user name.

      Password

      Enter the password that is used to authenticate the connection.

      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.

      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.
      Digest
      Perform the actions as described in the following table:
      Field Action

      Username

      Enter the user name.

      Password

      Enter the password that is used to authenticate the connection.

      Note: A hash function is applied to the password before it is sent.
      NTLM
      Perform the actions as described in the following table:
      Field Action

      Username

      Enter the user name.

      Password

      Enter the password that is used to authenticate the connection.

      Domain

      Enter the domain name of the NT LAN Manager.

      Basic, Digest and NTLM
      Perform the actions as described in the following table:
      Field Action

      Username

      Enter the user name.

      Password

      Enter the password that is used to authenticate the connection.

      Domain

      Enter the domain name of the NT LAN Manager.

      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.

      Kerberos

      Perform the actions desribed in the following table:

      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 Action
      Use SSO (Run with current user credentials)
      Select your action from the following options:
      • Select the Use SSO (Run with current user credentials) check box, if you want 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 Test Integrations and APIs as a Windows user, you must be authorized to access the configured HTTP server.
        • When running a test from a Test Integrations and APIs 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)
      • Clear or do not select the Use SSO (Run with current user credentials) check box, to use the Kerberos credentials.
      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 hostname 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.
      External krb5 config file Perform the following steps:
      1. Select the External krb5 config file option, if you are using a krb5 configuration file.

        When selected, the Config Path field is enabled.

      2. Enter the path or click Browse to locate the folder that contains the krb5 configuration file.
      OAuth2
      Perform the actions as described in the following table:
      Field Action

      Token endpoint

      Enter the URL of the authorization server that is used by the client to obtain an access token by presenting its refresh token.

      Client id

      Enter the identity provided to the client by the authorization server.

      Client secret

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

      Client assertion

      Optionally and 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.

      Scopes

      Enter the scopes for which access is requested.

      Generate
      1. Click Generate to obtain the refresh token.
        Note: You must have entered the values in the previous fields.

        Image of the Generate Refresh Token dialog.

      2. Enter the URL of the authorization server in the Authorization Endpoint field.
      3. Use the default redirect URI or enter the URI to which the authorization server sends the generated refresh token and is used to extract the refresh token received in the Redirect URI.
        Note: The URL must match the URL that you provided during the registration process. You can change the port in the URL if the default port is used by some other process. Test Integrations and APIs starts the endpoint that is in this URL to receive the refresh token.

      The refresh token is received at the location specified.

      Refresh token

      When you generate the refresh token by using Test Integrations and APIs this field is automatically populated by Integration Tester when it receives the refresh token.

  8. 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 Test Integrations and APIs 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 Test Integrations and APIs 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.
  9. Optional: Click Recording to configure the recording settings for 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 Test Integrations and APIs.
      • 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 Test Virtualization Control Panel are used by Test Integrations and APIs and Test 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.
    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.
  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 Test Integrations and APIs.
  11. Click OK.

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.

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