NTLM authentication
improve this page | report issueOverview
The NTLM protocol is a challenge-response mechanism for authentication users in Windows operating systems.
This tutorial explains how to use a MobileFirst adapter when connecting to a back end or resource that is protected by NTLM protocol for user authentication.
Topics:
- Back-end connection settings (
connectAs="endUser/server"
) - Using NTLM authentication with
ServerIdentity
- Using NTLM authentication with
UserIdentity
Back-end connection settings (connectAs="endUser/server"
)
For MobileFirst Server to handle sessions when connecting to a back-end system, you can use either of the following 2 approaches:
connectAS="server"
:
All sessions use the same connection context to the back end.
This is the MobileFirst Server default behavior.connectAS="endUser"
:
Each session is authenticated separately and has a unique connection context against the back end.
For a procedure to be connected as "end user", you must declare it with a connectAs="endUser"
attribute in the adapter XML file:
<procedure name="MyProcedure" connectAs="endUser"/>
For more information about the
connectAs
attribute, read the blog post about Configuring HTTP adapters for stateless/stateful back-end connectivity and user identity propagation.
Using NTLM authentication with ServerIdentity
When you use a procedure to connect to a back-end server that uses NTLM protocol without specifying the connectAs
attribute, use the <serveridentity>
element of the adapter XML file as child element of the <authentication>
element. Also add the <ntlm workstation>
child element, so that MobileFirst Server knows which authentication method to use when connecting to the back end.
Make sure to pass the server and user names to the back-end server in the following pattern: `server-name/user-name`.
<connectivity>
<connectionPolicy xsi:type="http:HTTPConnectionPolicyType">
<protocol>http</protocol>
<domain>your-domain-here</domain>
<port>80</port>
<connectionTimeoutInMilliseconds>30000</connectionTimeoutInMilliseconds>
<socketTimeoutInMilliseconds>30000</socketTimeoutInMilliseconds>
<authentication>
<ntlm workstation="ServerName"/>
<serverIdentity>
<username>your-server-name/your-username-here</username>
<password>your-password-here</password>
</serverIdentity>
</authentication>
<maxConcurrentConnectionsPerNode>50</maxConcurrentConnectionsPerNode>
</connectionPolicy>
</connectivity>
Note: When the NTLM protocol is used, the user name is always specified in the {server-name/user-name} format.
Using NTLM authentication with UserIdentity
Configure MobileFirst Server authentication
- Create a security test to protect the procedure:
<customSecurityTest name="NTLMSecurityTest"> <test isInternalUserID="true" realm="NTLMAuthRealm"/> </customSecurityTest>
- Use
BasicAuthenticator
,AdapterBasedAuthenticator
, or any other authenticator that handlesuserIdentity
, as the class for the realm used by the security test:
<realm name="NTLMAuthRealm" loginModule="AuthLoginModule"> <className>com.worklight.integration.auth.AdapterAuthenticator</className> <parameter name="login-function" value="MyAdapter.onAuthRequired"/> <parameter name="logout-function" value="MyAdapter.onLogout"/> </realm>
- Add some login module to create and store user identities to be used by this realm:
<loginModule name="AuthLoginModule"> <className>com.worklight.core.auth.ext.NonValidatingLoginModule</className> </loginModule>
- Add the
<authentication>
element and its<ntlm workstation>
child element to the adapter XML file, so that MobileFirst Server knows which authentication method to use when connecting to the back end:
<connectivity> <connectionPolicy xsi:type="http:HTTPConnectionPolicyType"> <protocol>http</protocol> <domain>Put.Your.Domain.Here</domain> <port>80</port> <connectionTimeoutInMilliseconds>30000</connectionTimeoutInMilliseconds> <socketTimeoutInMilliseconds>30000</socketTimeoutInMilliseconds> <authentication> <ntlm workstation="wl-ntlm"/> </authentication> <maxConcurrentConnectionsPerNode>50</maxConcurrentConnectionsPerNode> </connectionPolicy> </connectivity>
- Assign this security test to the procedure that is used to connect to the back end protected by NTLM protocol, and add
connectAs="endUser"
to the procedure declaration in the adapter XML file:
<procedure name="getNTLMData" securityTest="NTLMSecurityTest" connectAs="endUser"/>
Adapter JavaScript code
Create a UserIdentity
that contains a user identifier and credentials properties. Format the userId
as servername/username
:
function submitAuthentication(username, password){
var userIdentity = {
userId: "MyServerName\/"+ username,
credentials: password
};
WL.Server.setActiveUser("NTLMAuthRealm", null);
WL.Server.setActiveUser("NTLMAuthRealm", userIdentity);
...
}
Create an http request to the NTLM protected back end:
function getSecretData(){
var input = {
method : 'get',
returnedContentType : 'html',
path : "index.html"
};
return WL.Server.invokeHttp(input);
}