Newzware Authentication Overview
The auth70_xml.jsp page receives an HTTPS request containing parameters that instruct the page to respond in specific ways depending on the parameter values in the request. Read this section very carefully. This page will authenticate a user's login/email and password combination while checking for valid subscriptions or adequate funds. Regular subscriptions, such as Print, Mail or Internet can be authenticated down to the subscriptions active status and issue type.

E-Copy (Pay as you go) authentication checks will perform an A/R transaction (Reduce the available subscribers balance) if the date and edition have not yet been viewed by the account. Already viewed dates and pubs will be granted access with no additional funds extracted from the user's account. All questions regarding the processing of the E-Copy accounts should be directed toward an ICANON engineer or sent to [email protected].

There are two types of XML responses that can be returned with an optional redirect with the XML as a parameter value. See the responses for detailed information.

The following examples are configured to hit the authentication module installed on the server generating this page.

Facebook and Twitter

The authentication module now supports or can grant access to subscribers that have linked a facebook or twitter user id to their online account. A network and network_id parameter should be sent instead of the traditional login and password. Valid values for the network parameter are: FB or TW. Facbook (FB), Twitter (TW). The network_id is the user id for the social network and must be obtained by the caller. This module does not look up the user id.

Newzware Authentication Examples

Authentication for Active Subscriptions To Any Issue and Any Edition
Login ID:
Password:
Query By Account:
Subscriber Account Number (Used in Query By Account):
Subscriber Last Name (Used in Query By Account):
Site:
Network:
Network ID:
Active Only (No Future Subscription Check): (Y|N)
If Future Subscription Check, How Many Days(Default 90):
DOM XML Response: (Y|N)
Return Page (Optional): (URL to return response to - The xml response is encoded (UTF-8) and sent back as the value for the parameter newzwareResponse)

Authentication For Active Subscriptions To A Specific Edition
Login ID:
Password:
Network:
Network ID:
Edition Code:
Publication Date: (Optional - Use with E-Content)
Site:
Active Only (No Future Subscription Check): (Y|N)
If Future Subscription Check, How Many Days(Default 90):
Return Page (Optional): (URL to return response to - The response is encoded (UTF-8) and sent back as the value for the parameter newzwareResponse)
DOM XML Response: (Y|N)

Authentication For Active Subscriptions To Specific Issue and Edition Combination
Login ID:
Password:
Network:
Network ID:
Edition Code:
Issue Code:
Publication Date: (Optional - Use with E-Content)
Site:
Active Only (No Future Subscription Check): (Y|N)
If Future Subscription Check, How Many Days(Default 90):
Return Page (Optional): (URL to return response to - The response is encoded (UTF-8) and sent back as the value for the parameter newzwareResponse)
DOM XML Response: (Y|N)

-->

Newzware 7.0 Subscription and E-Copy Authentication Developer Documentation
 
The authentication page (auth70_xml.jsp) takes the following parameters.
 
NECESSARY PARAMETERS
 
@param login_id The user's email address or login id. This is a unique value in the Newzware Webprofile database.
@param password The user's password.
@param site The site name. This is provided by a Newzware engineer and must be passed to this page.
 
************** Or ******************
 
@param queryByAccount (Optional)Whether to query by subscriber account instead of login and password. Possible values Y or N. Default is "N". If "Y", subaccount parameter must be sent in request.
@param subaccount The subscriber's account number. Used only for query by account. queryByAccount parameters must by "Y".
@param site The site name. This is provided by a Newzware engineer and must be passed to this page.
OPTIONAL PARAMETERS (Read Carefully)
 
@param edition(optional) The Newzware edition code. If passed, subscriptions are checked for this value and only subscriptions to the edition will be authenticated. This value is returned in the response as edition-value. NOTE - The edition parameter MUST BE PRESENT if authenticating with the e-copy retail rates.
@param active_only(optional) Default is N. Determines whether the authentication mechanism will only look at currently active subscriptions. If not passed, future subscriptions are checked. If passed with a value of Y, active subscriptions only will be checked.
@param dom(optional) The dom parameter allows the response to be formatted in an AJAX friendly manner. If set to Y, the response returned is easily managed by the DOM in any browser.
@param issue(optional) The Newzware issue code. If passed, subscriptions are checked for this value and only subscriptions to the issue and falling on a publishing day for the issue, will be authenticated. This is used in conjunction with the pubDate parameter. This is not used in the Newzware e-content module.
@param rpage(optional) The rpage parameter is the return url to forward back to after any processing is done. The xml response will be encoded and sent as a parameter value for the parameter name newzwareResponse.
@param pubDate(optional - MM/DD/YYYY) The pubDate parameter is required in the Newzware E-Content module, but may be passed on standard authentication requests when using the issue parameter.

E-Content

For E-Content, this is the date of the E-Article or the date the paper was published that you would like to authenticate against. The pubDate and edition provide the mechanism for authenticating against e-content subscriptions.

Standard Authentication

For standard authentication requests, this date represents a day of the week. The issue code must also be passed when using the pubDate parameter on standard authentication requests. The issue code represents the days of the week for the subscription. If the pubDate parameter is not passed, the current date is used to determine the day of week for the authentication request. This is only used when the issue parameter is passed.

Date must be formatted as MM/DD/YYYY. This value is returned in the response as pubDate.
@param token(optional) The token is any string value that is automatically passed back in the response.
@param futureDays(optional) The amount of days to go forward to check for future subscriptions. Default is 90 days.
Response An XML response like one of the following with an exit code: exit codes are as follows:

0 - Successful
1 - Invalid login and password combination
2 - No valid subscriptions found
5 - Insufficient Funds
9 - Invalid subscriber account number
-99 - Authentication is dependent on the subscription in response. Must check subscription tag.
If the rpage parameter is sent, the xml string is encoded and passed back as a parameter in the return page url. The parameter name is newzwareResponse. This response can be parsed easily and loaded into the DOM by using the following javascript in an onload event. This assumes the newzware.js library is being included in the page. If the content is being secured by another measure or language, or Newzware is not protecting your content, skip this section. 
function newzware_getParameterValue(variable){
	var query = window.location.search.substring(1);
	var vars = query.split("&");
	for (var i=0;i<vars.length;i++) {
		var pair = vars[i].split("=");
		if (pair[0] == variable) {
			return pair[1];
		}
	}
}
function newzware_getXMLDoc(xmlString){
	try {
		xmlDoc=new ActiveXObject("Microsoft.XMLDOM");
		xmlDoc.async="false";
		xmlDoc.loadXML(xmlString);
		return xmlDoc;
	}
	catch(e) {
		parser=new DOMParser();
		xmlDoc=parser.parseFromString(xmlString,"text/xml");
		return xmlDoc;
	}
}
var xmlResponse = newzware_getParameterValue("newzwareResponse");
if(xmlResponse != null){
	var message = "";
	xmlResponse = decodeURIComponent(xmlResponse);
	xmlResponse = xmlResponse.replace(/\+/g, " ");
	var xmlDoc          = newzware_getXMLDoc(xmlResponse);
}

Authenticated XML Responses

The following are the authenticated xml responses returned from the auth70_xml.jsp page. Authenticated xml responses contain subscription information.
 
Description of Fields
Root Node
authenticated - Yes, No, Dependent - Used to test if the subscriber has a valid subscription.
Yes - Subscriber has a valid subscription
No - Subscriber does not have a valid subscription
Dependent - The valid on pub date must be checked to determine whether or not the subscriber is valid.
token - If a token is passed in the request, the same token is returned as this value.
login - The subscriber login id.
password - The subscriber password
lastlogin - The last time the subscriber log into the Self Service Module or was Authorized.
usertype - The user type for the subscriber or general user. Valid values are S and G for subscriber) and general user.
pubDate - If a publication date was passed, it is returned as this value.
exit-code - The exit code. Explained above.
edition-value - The Newzware edition code. If passed, subscriptions are checked for this value and only subscriptions to the edition will be authenticated. This value is returned in the response as edition-value.
extension-name - The Newzware extension name.
extension-value - The Newzware extension value.
Subscrip Node
unique - The Newzware subscription unique id.
account - The Newzware subscriber account number (unique in Newzware).
fname - The subscriber's first name.
lname - The subscriber's last name.
email - The subscriber's email address, if any.
edition - The Newzware edition code for the subscription.
paytype - The subscription rate's payment type. How a subscriber pays for the subscription, such as Carrier Collect (CA), Pay Paper Direct - PIO (P), Arrears (A), Complimentary (CO).
deltype - The subscription rate's delivery type. How the subscription is delivered, such as Carrier (C), Auto (A), Mail (M), Email (E), Internet (I), E-Copy (EC), E-Article (EA).
issue - The subscription frequency of delivery. Issue codes are defined in Newzware and are not constants. An edition code list can be provided by an ICANON engineer. NOTE - These values can be updated/added at any time.
abc - The subscriptions ABC zone.
vacation - The vacation id. If the value is > 0, this subscription is on vacation. Vacations are directly tied to subscriptions, not subscribers.
beg - The subscription begin/start date.
end - The subscription end or paid thru date. Any adjustments to the subscriber account will modify the end or paid thru date.
rateid - The subscription's rate id. This is a unique identifier.
ratezone - The zone for the rate that this subscription is currently on.
valid-on-pub-date - Used only with the Dependent value for the authenticated node. If a pub date is passed, this is used to determine if the subscription is valid on the pub date passed, since a subscriber can have multiple subscriptions present in the response that may or may not be valid on that pub date. Possible values returned: Y and N. If Y, the subscription is valid on the pub date passed. If N, the subscription is not valid on the pub date passed.
 

AUTHENTICATED - TRADITIONAL XML RESPONSE

Response (no dom parameter sent or sent as N)
Publication date and edition values are sent back in the response only if they are present in the request. Otherwise, a value of null may be returned. 
<newzware>

	<authenticated>Yes</authenticated>

	<token>token</token>

	<login>loginid</login>

	<password>password</password>

	<lastlogin>10/17/2011</lastlogin>

	<usertype>S</usertype>

	<pubDate>null</pubDate>

	<exit-code>0</exit-code>

	<edition-value>null</edition-value>

	<extension>

		<name>Birth Year</name>

		<value>19191</value>

	</extension>

	<subscrip>

		<unique>64065</unique>

		<account>1001</account>

		<fname>JAY</fname>

		<lname>SHOMAN</lname>

		<email>[email protected]</email>

		<edition>DEI</edition>

		<paytype>P</paytype>

		<deltype>I</deltype>

		<issue>D7</issue>

		<abc>40</abc>

		<vacation>0</vacation>

		<begin>10/01/2011</begin>

		<end>10/01/2011</end>

		<rateid>80</rateid>

		<ratezone>C</ratezone>

		<valid-on-pub-date>NA</valid-on-pub-date>

	</subscrip>

</newzware>

AUTHENTICATED - DOM XML RESPONSE

Response (dom parameter sent and set to Y) See above authenticated response for pubDate and edition-value comments 
<newzware>
	<authenticated value="Yes" edition-value="null" pubDate="null" token="token" login="[email protected]"/>
	<exit-code code="0" message=""/>
	<subscrip unique="99388" account="384678" fname="JAY" lname="SHOMAN" email="[email protected]" edition="SN" paytype="P" issue="D" abc="10" vacation="0" begin="09/17/2009" end="null" deltype="EC"/>
</newzware>
 

Failed Responses
 

FAILED - TRADITIONAL XML RESPONSE

Response (no dom parameter sent or sent as N) 
<newzware>
	<authenticated>No</authenticated>
	<token>token</token>
	<pubDate>null</pubDate>
	<edition-value>null</edition-value>
	<login>[email protected]</login>
	<exit-code>1</exit-code>
	<message>
		Invalid login and password combination for [email protected].
	</message>
</newzware>

FAILED - DOM XML RESPONSE

Response (dom parameter sent and set to Y) See above authenticated response comments for pubDate and edition-value. 
<newzware>
	<authenticated pubDate="null" edition-value="null" value="No" token="token" login="[email protected]"/>
	<exit-code code="1" message="Invalid login and password combination for [email protected]."/>
</newzware>
 
 

Optional Response - Redirect using rpage parameter


An optional response can be done when using the "rpage" parameter. The xml response is encoded (UTF-8) and sent back as the value for the parameter newzwareResponse in the return pages query string. For example: if the rpage value is www.mydomain.com, then once the authentication request is fulfilled, the response is redirected to www.mydomain.com with a parameter newzwareResponse with the value of the XML string returned from the authentication page. See below

Authentication page sends the same xml response as above, but as a parameter value for the parameter "newzwareResponse" like this:


www.mydomain.com?newzwareResponse=ENCODED XML STRING