NTLM

NTLM is a Windows authentication procedure. By having valid windows credentials one can access NTLM secured endpoints, e.g. served by an IIS. To access NTLM secured endpoints one has to follow the NTLM protocol (of exchanging three messages) to authenticate the current connection.

By using Membrane API Gateway with the NTLM interceptor one can easily access NTLM secured resources. The NTLM interceptor processes NTLM authentication requests and follows the needed protocol. By using the NTLM interceptor using NTLM authentication is as easy as providing ones credentials as headers in a (TLS secured) request.

Configuration

Note: This example does not use TLS as it would distract from the main point. It is highly advised to use TLS or else credentials are sent in plain text over the wire.

Listing 1 show an example configuration to enable authentication with an NTLM secured resource.

        <router>
          <serviceProxy port="80">
            <ntlm user="X-Username" pass="X-Password" />
            <target host="localhost" port="8111"/>
          </serviceProxy>
        </router>
      

Membrane is configured as a simple virtual endpoint listening on port 80. When connecting the request is routed through the NTLM interceptor to start the authentication process. For that the windows credentials of a valid user are needed. The NTLM interceptor (by default) fetches those from custom headers - here called X-Username and X-Password. When the authentication process has finished the original call is routed to the target resource specified in the target element.

The here given configuration for NTLM can be extended to encompass all four NTLM parameters. The following listing is a list of attributes that map an NTLM parameter to a custom header for usage by the NTLM interceptor.

• user - (Windows username)
• pass - (Corresponding password for username
• domain - (Domain the Windows server is residing in)
• workstation - (Workstation the user is assigned to)

Listing 2 shows a full example.

        <router>
          <serviceProxy port="80">
            <ntlm user="X-Username" pass="X-Password" domain="X-Domain" workstation="X-Workgroup" />
            <target host="localhost" port="8111"/>
          </serviceProxy>
        </router>
      

Custom Retrieval Methods for the NTLM Parameters

Note: This needs actual Java development on Membrane as a dynamically loaded library or forked version.

The NTLM interceptor can easily be extended by other means of retrieving the NTLM parameters. By default the custom header retrieval is used. One can expand the Membrane configuration to show the actual retrieval method.

        <router>
          <serviceProxy port="80">
            <ntlm>
              <headerRetriever user="X-Username" pass="X-Password" domain="X-Domain" workstation="X-Workgroup"/>
            </ntlm>
            <target host="localhost" port="8111"/>
          </serviceProxy>
        </router>
      

By implementing the NTLMRetriever interface one can exchange the headerRetriever element with a custom element e.g. to fetch the (technical user) credentials from a file when given a valid OAuth 2 token.

Getting Started

See examples/ntlm/README.txt in the membrane folder and try it yourself.