You are here:

WebLogin

Initial Build	2006.02
xWEB	Web Method
Response Type	string

This web method is used to validate a user's login and password as it is stored in netFORUM.

A successful match on userLoginPlain and passwordPlain returns an authentication token for a valid customer login and password. With this token, you can then call WebValidate to get the customer key of the user, and then go from there. If there are more than one record with the exact same login and password combination, then the service returns the first match.

The value for the userLoginPlain field depends on a netFORUM System Option useEmailForAuthorization, so please check with the netFORUM administrator for the setting. Depending on the system option, it is either an email address or a free-form field. Either way, this setting is transparent to this web method.

The keyOverride parameter is an implementation specific parameter (a web.config change that an administrator will need to make) to force xWeb to return the customer key (cst_key) for a valid credential. This will allow you to skip the call to xWeb:WebValidate. (System Administrators: see XWeb:Configuration_Settings#keyOverrideValue for instructions on how to get the value for this.)

Please note that this web method is different from Authenticate. The Authenticate web method validates a program that wants to use xWeb. WebLogin is used to validate an individual's username/password to log in to an application.

Note: The WEBWebUserLogin method can be used for the same purpose as this web method.

Recommendation

We recommend that integrators get the keyOverride value from the xWeb site administrator and pass that value to the keyOverride parameter. This will enable the application to skip calling the xWeb:WebValidate web method.

The only reason you would not want to do this is for specific applications that need to generate a Token for single sign-on purposes, in which you would need to supply this Token value to other outside applications.

If you have an application and you simply need to log someone in, then you should always pass the keyOverride parameter.

Note that beginning in the 2008.01 release of netFORUM, there is a XWeb:WEBWebUserLogin web method similar to WebLogin but which returns more information. Consider using this method if the additional information is helpful.

Single Sign On Usage

Please note that this method is only used to confirm the user's login and password are correct and to match that login/password to a Customer. When used in conjunction with Single Sign On for eWeb, the token returned by this can be passed to eWeb to automatically log the user in. Calling this method will not start an eWeb session for the user, the user must be logged in to eWeb as a separate step.

Parameters

userLoginPlain (string). plain text username
passwordPlain (string). plain text password
keyOverride (string).

Response

String—if a valid keyOverride value is passed, then the value returned will be a customer key (cst_key) which can then be used for other purposes such as a call to web methods xWeb:GetIndividualInformation or to xWeb:GetQuery. Otherwise, the return value will be a Token that you will then pass to xWeb:WebValidate.

Sample Request without keyOverride

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<SOAP-ENV:Header>
<m:AuthorizationToken xmlns:m="http://www.avectra.com/2005/">
<m:Token>e8c67a3a-ab77-4686-bc63-a3c1ce51be99</m:Token>
</m:AuthorizationToken>
</SOAP-ENV:Header>
<SOAP-ENV:Body>
<m:WebLogin xmlns:m="http://www.avectra.com/2005/">
<m:userLoginPlain>mjemio@avectra.com</m:userLoginPlain>
<m:passwordPlain>password</m:passwordPlain>
<m:keyOverride></m:keyOverride>
</m:WebLogin>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Sample Response without keyOverride

The value returned in the <WebLoginResult> is a Token that you next will pass to the xWeb:WebValidate method, which returns the cst_key associated with that Token.

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/03/addressing"
xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"
xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
<soap:Header>
<AuthorizationToken xmlns="http://www.avectra.com/2005/">
<Token>23b12254-55ee-4093-98f9-96a12165aed3</Token>
</AuthorizationToken>
<wsa:Action>http://www.avectra.com/2005/WebLoginResponse</wsa:Action>
<wsa:MessageID>uuid:b2895ca4-6d1b-47f2-96c7-7fbdf36d999d</wsa:MessageID>
<wsa:RelatesTo>uuid:b78b7c99-98c0-447e-8be2-27925afe49ec</wsa:RelatesTo>
<wsa:To>http://schemas.xmlsoap.org/ws/2004/03/addressing/role/anonymous</wsa:To>
<wsse:Security>
<wsu:Timestamp wsu:Id="Timestamp-f42c1666-d7de-4d44-a8d2-1d22f1f7bf8e">
<wsu:Created>2006-09-26T13:47:25Z</wsu:Created>
<wsu:Expires>2006-09-26T13:52:25Z</wsu:Expires>
</wsu:Timestamp>
</wsse:Security>
</soap:Header>
<soap:Body>
<WebLoginResponse xmlns="http://www.avectra.com/2005/">
<WebLoginResult>9e2eee63-07cc-4ac3-aff3-dfe34d995c42</WebLoginResult>
</WebLoginResponse>
</soap:Body>
</soap:Envelope>

Sample Request With keyOverride

Note: if the keyOverride element has a value that matches the web.config setting in the xWeb/web.config file, then the method returns the cst_key for the individual. If there isn't a keyOverride value match, then the method returns the empty guid.

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<SOAP-ENV:Header>
<m:AuthorizationToken xmlns:m="http://www.avectra.com/2005/">
<m:Token>23b12254-55ee-4093-98f9-96a12165aed3</m:Token>
</m:AuthorizationToken>
</SOAP-ENV:Header>
<SOAP-ENV:Body>
<m:WebLogin xmlns:m="http://www.avectra.com/2005/">
<m:userLoginPlain>mjemio@avectra.com</m:userLoginPlain>
<m:passwordPlain>password</m:passwordPlain>
<m:keyOverride>8BCA2B05-48B7-49A6-9AA3-1133BB7C5948</m:keyOverride>
</m:WebLogin>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Sample Response With keyOverride

This is an example of a success response. The value of the <WebLoginResult> is a Customer Key (cst_key).

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/03/addressing"
xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"
xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
<soap:Header>
<AuthorizationToken xmlns="http://www.avectra.com/2005/">
<Token>0d8553d2-fd01-4045-b160-2308cb7a639a</Token>
</AuthorizationToken>
<wsa:Action>http://www.avectra.com/2005/WebLoginResponse</wsa:Action>
<wsa:MessageID>uuid:13e55f63-d125-4450-8a7b-abbf34132d99</wsa:MessageID>
<wsa:RelatesTo>uuid:fc962182-354a-4916-9596-75b3e9dd09e3</wsa:RelatesTo>
<wsa:To>http://schemas.xmlsoap.org/ws/2004/03/addressing/role/anonymous</wsa:To>
<wsse:Security>
<wsu:Timestamp wsu:Id="Timestamp-87cb4a86-9f30-46ae-bb9e-0debbbf84b10">
<wsu:Created>2006-09-26T13:49:21Z</wsu:Created>
<wsu:Expires>2006-09-26T13:54:21Z</wsu:Expires>
</wsu:Timestamp>
</wsse:Security>
</soap:Header>
<soap:Body>
<WebLoginResponse xmlns="http://www.avectra.com/2005/">
<WebLoginResult>5bb1722f-dc51-4424-aee9-3b204fcf09b6</WebLoginResult>
</WebLoginResponse>
</soap:Body>
</soap:Envelope>

If the userLoginPlain/passwordPlain combination do not match, then the <WebLoginResult> will be a string of zeroes 00000000-0000-0000-0000-000000000000 like this:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<soap:Header>
<AuthorizationToken xmlns="http://www.avectra.com/2005/">
<Token>68d74e37-63e4-434c-adf8-ded6e1a6a67c</Token>
</AuthorizationToken>
</soap:Header>
<soap:Body>
<WebLoginResponse xmlns="http://www.avectra.com/2005/">
<WebLoginResult>00000000-0000-0000-0000-000000000000</WebLoginResult>
</WebLoginResponse>
</soap:Body>
</soap:Envelope>

FAQ

Use Token Multiple Times

Q. Can a token be used more than once?

A. Yes, the token can be used multiple times, until WebLogout is called or until the token expires.

Response of Customer Key or Token

Q. I am calling WebLogin, then I pass the Customer Key I get in the response to xWeb:GetIndividualInformation, but I get no records in the response, as if that Customer Key does not even exist. What's happening?

A. First, you must realize that the WebLogin web method returns either a Tokenor a Customer Key, depending on whether you supply a correct value to the keyOverride parameter. If you leave the keyOverride value empty (see Sample Response without keyOverride above for sample), then the web method returns a token that you must then pass as a parameter to the xWeb:WebValidate method; WebValidate then returns a customer key. If you pass the correct value to the keyOverride parameter, the WebLogin returns a Customer Key; see Sample Response With keyOverride above for an example.

So, if you are finding that you get no records in the response from GetIndividualInformation, then it could be because you are trying to pass a Token value and not a Customer Key.

How can you know what the keyOverride value is? The xWeb system administrator will need to tell you this. See XWeb:Configuration_Settings#keyOverrideValue for more.

Passwords with Special Characters Don't Work

Q. Customers with special characters in the password like & ' " < > don't work.

A. See XWeb_Troubleshooting#Special_Characters_Do_Not_Work for explanation.