Authenticate
The Authenticate web method authenticates a calling program and permits the program to call other xWeb web methods. Before calling any web method, the program first must call Authenticate successfully with a userName and password, get back an authentication token, and then pass that token to any subsequent web method calls. The return from any subsequent web method calls will provide a new token, which can then be passed to a subsequent web method call (if any).
Important! Authenticate will not work in a web browser. It can only work when called from within an application that can read and send SOAP headers. See xWeb Does Not Work on Browser for more.
Passing correct credentials to this method returns an authentication token - without an authentication token, the rest of the xWeb web methods will be inoperable. The authentication token is governed by the group privileges assigned to the xWeb User account invoking the xWeb web methods. Please consult with the administrator of the netForum database to ensure your level of authorization. This method MUST be the first method invoked at xWeb, as the authentication token that is returned is required for every xWeb method.
Managing Tokens Programmatically
See Authenticate Case Study for guidelines and best practices.
Parameters
Pass in the parameters for your xWeb User:
- userName (string). User Name to log in as.
- password (string). Unencrypted password.
Response
AuthorizationToken (string)
Sample Request
The following sample SOAP request works with the xWeb Authenticate method. The values for <userName> and <password> are supplied to you by Abila with your xWeb license.
<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>
<SOAP-ENV:SOAPAction>Test</SOAP-ENV:SOAPAction>
</SOAP-ENV:Header>
<SOAP-ENV:Body>
<ns:Authenticate xmlns:ns="http://www.avectra.com/2005/">
<ns:userName>xxx</ns:userName>
<ns:password>qqqqq</ns:password>
</ns:Authenticate>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Sample Response
Here is a sample SOAP response. Note the value of the <Token> returned in the header. You will need to capture this value and send it along in your next request. In this example, the value of the <Token> is 42d99a16-c6da-4aa0-bc6f-d16f95c87f9e.
<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 soap:actor="4accdea1-65b9-41be-8c03-e95d83cea6df" xmlns="http://www.avectra.com/2005/">
<Token>42d99a16-c6da-4aa0-bc6f-d16f95c87f9e</Token>
</AuthorizationToken>
</soap:Header>
<soap:Body>
<AuthenticateResponse xmlns="http://www.avectra.com/2005/">
<AuthenticateResult>http://www.avectra.com/2005/</AuthenticateResult>
</AuthenticateResponse>
</soap:Body>
</soap:Envelope>
Troubleshooting
You are not authorized to view this page Error
If you get a "You are not authorized to view this page" page error, or if you are forced for a network logon prompt, then this means the xWeb site is not set up properly. Tell the netFORUM Site Administrator that "anonymous access must be enabled in the 'secure' subfolder of xWeb." See XWeb:Install#IIS_Setup for more.
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<HTML><HEAD><TITLE>You are not authorized to view this page</TITLE>
<META HTTP-EQUIV="Content-Type" Content="text/html; charset=Windows-1252">
<STYLE type="text/css">
BODY { font: 8pt/12pt verdana }
H1 { font: 13pt/15pt verdana }
H2 { font: 8pt/12pt verdana }
A:link { color: red }
A:visited { color: maroon }
</STYLE>
</HEAD><BODY><TABLE width=500 border=0 cellspacing=10><TR><TD>
<h1>You are not authorized to view this page</h1>
You do not have permission to view this directory or page using the credentials that you supplied because your Web browser is sending a WWW-Authenticate header field that the Web server is not configured to accept.
<hr>
<p>Please try the following:</p>
<ul>
<li>Contact the Web site administrator if you believe you should be able to view this directory or page.</li>
<li>Click the <a href="javascript:location.reload()">Refresh</a> button to try again with different credentials.</li>
</ul>
<h2>HTTP Error 401.2 - Unauthorized: Access is denied due to server configuration.<br>Internet Information Services (IIS)</h2>
<hr>
<p>Technical Information (for support personnel)</p>
<ul>
<li>Go to <a href="http://go.microsoft.com/fwlink/?linkid=8180">Microsoft Product Support Services</a> and perform a title search for the words <b>HTTP</b> and <b>401</b>.</li>
<li>Open <b>IIS Help</b>, which is accessible in IIS Manager (inetmgr),
and search for topics titled <b>About Security</b>, <b>Authentication</b>, and <b>About Custom Error Messages</b>.</li>
</ul>
</TD></TR></TABLE></BODY></HTML>
Credentials Locked Out
If you get this error when calling Authenticate:
<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:Body>
<soap:Fault>
<faultcode>soap:Client</faultcode>
<faultstring>System.Web.Services.Protocols.SoapException: Credentials Locked Out
at Avectra.netForum.xWeb.xWebSecure.netForumXMLSecure.Authenticate(String userName, String password)
in c:\Inetpub\wwwroot\NF2Solution\xWeb\App_Code\Secure\netForumXML.asmx.cs:line 87</faultstring>
<faultactor>http://localhost/nf2solution/xweb/Secure/netForumXML.asmx</faultactor>
<detail/>
</soap:Fault>
</soap:Body>
</soap:Envelope>
You have exceeded the FailCount or MethodsFaultLimitPerDay limits as described in xWeb: Configuration Settings.
If this was done mistakenly, an administrator can reset your security by running this:
DELETE ws_security WHERE xws_usr_code = 'UserName' AND xws_expiration_policy IN ('Fail','Fault')
You can delete the Fail records one by one from the xWeb Authentication Activity Detail child form on the User profile page:
Failed Fault
Q. I am able to Authenticate, but any subsequent method calls give this error:
<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:Body>
<soap:Fault>
<faultcode>soap:Client</faultcode>
<faultstring>Failed</faultstring>
<faultactor>http://www.netforumsite.com/xweb/secure/netForumXML.asmx</faultactor>
<detail/>
</soap:Fault>
</soap:Body>
</soap:Envelope>
Possible resolution: This could be caused by an issue in the Authorization token expiration date. Network administrator must confirm that the server clock on the web and SQL server are in synch. See #Web_and_SQL_Server_Clocks_out_of_synch.
Inconsistent Login
Beginning with 2008.01, parts of Authenticate are cached for faster performance. See XWeb_2008.01#Authenticate_Performance for more. As a result, we have found that if an account starts acting irregularly and getting this error even though you know that the userName and password are correct:
Invalid Credentials Supplied
this could be caused by a certain combination of caching if you are making a lot of changes to xWeb user settings. This should not start happening to a stable account that has not been changed. To fix this, a site administrator must clear cache.
You will know this condition is occurring if you change the password on the user record to a different password, then authenticate successfully with the new password, but if you change back to the old password, it will not work.
FAQ
Time left on Token
Q: Is there a way to determine in xWeb if the usertoken has expired? We want to be able to proactively determine if the token has expired or if it is still active.
A: If the xWeb Expiration setting is Sliding, then each time you call a web method with an authentication token, that token's expiration datetime will be reset into the future by the number of minutes in the Timeout setting (default is 20 minutes). In your application, you could track that own timeout in a session variable or some other way to keep track of how long you have left for that token. If you are over the limit, then get a new token; if you're under the limit, then try with the current token, but you should always build in a "catch" routine for safety. If the Expiration setting is Absolute, then you will have a fixed expiration datetime (based on the Timeout setting) that will never get extended. You can track this datetime in the same way that you can track the expiration for a Sliding timeout.
JSON Method
Get a NetForum token for the given user name and password.
GET n/a
POST /xweb/JSON/Authenticate
DATA: JSON
{
"Authenticate" : {
"userName" : "UserName",
"password" : "Password"
}
}
SAMPLE RESULT
HTTP STATUS: 200
DATA: JSON
{
"Token": "c9a96124-cae4-4da8-ad37-53b13683bce5"
}