Page History

h2. A Developer's Guide To Handling the ISIS IP Address Mismatch Errors

*Article Type:* Technical
*Intended Audience:*  Developers who maintain ISIS-enabled applications 

h3. Introduction

With the reinstatement of the IP matching violation errors (604010, 904099) ISIS once again terminates a user's session when the user's brower IP address changes within an ISIS session. This document offers guidelines on how applications should handle the reinstated IP matching violation errors.

_A note to end users:_ If you stumbled onto this page looking for ways to resolve your log in woes, [this article|UserGuideToHandling604010Errors] may provide more useful help information.

h3. Background

[Proposal to Rinstate IP Address Matching Rule in ISIS|ProposalToReinstateISISIPMatchingRule]
[A 2003 Article Explaining the IP Matching Rule and its Related Issues|ISISAuthnWithUnstableIP]

h3. How to handle 604010 error in your application

When ISIS detectes a browser IP address change, it returns either error code 604010 or 904099. The following error message is returned with the 604010 error code:

{quote}We cannot verify the authenticity of the session. User's IP address has changed since the initial Logon. This is a Security Violation and the session has been terminated. For more details please visit <url-to-be-inserted>{quote}

*DO NOT SHOW THE GENERIC 604010 ERROR PAGE.  DO NOT SIMPLY REDIRECT TO OUR TEMPLATE.  USE THE INFORMATION ON OUR SAMPLE TO CREATE YOUR OWN VISUALLY ACCURATE ERROR PAGE SO AS TO NOT CONFUSE THE USER*

If you receive error code 604010, redirect user to a page displaying following information:
# The above error message returned with 604010 code.
# Work around: VPN to ucla network, close all brwosers and try again. Check with [UCLA VPN|http://www.bol.ucla.edu/services/vpn] for VPN infomation.
# Here is a sample error page.  Please use the template and create your own error page, customizing for aesthetic compatibility and appropriate help desk contact info: [Sample|https://i4w.ais.ucla.edu/ils/604010.html]
# If user still has the same error with VPN, contact the IAMUCLA team at [iamucla at ucla.edu|mailto:iamucla@ucla.edu],  with the followng information:

* Your Logon ID (DO NOT send password. A legitimate support organization will never ask you for your password.)
* Application you wanted to sign in to
* The approximate time you encountered the error
* Your location (home, office, etc.)
* If you have the information, which browser you used.
* If you have it, a screen capture of the error message

{builder-hide}
There are few steps ISIS consumers(applications) can take to help alleviate the problem and improve the user experience:

h4.Interpret the error code 604010 and display the appropriate message to the user. 
You may also replay the above message to the browser. Direct the user to a VPN instruction [page|https://spaces.ais.ucla.edu/display/iamucla/UserGuideToHandling604010Errors]

h4.If you query ISIS verifySession Web Service directly
It should be a trivial change to interpret the error codes and handle them accordingly.

h4.If you use a third party custom library which interacts with ISIS verifySession
If the custom library reports the error code/text back to your application you can handle them easily; if the custom library processes the error codes and returns a simple Yes/No or True/False answer to your application contact the library providers in this case.

See pseudo-code to handle verifySession response [IsisWebServiceResponseHandler|IsisWebServiceResponseHandler]

h4.ISIS has the capability to whitelist campus networks that have set up private NATted networks within their department. 
We can exempt those networks from IP Address restriction so user's session will not be terminated in the event of IP address change.

If you have set up a private network in your department please provide us a list of (a) ISIS enabled applications hosted within those networks and (b) private IP addresses/ranges of those networks and the public IP addresses that's visible outside your department.

If there is an IP Address conflict during verifySession, ISIS checks if the IP Address is within the whitelist IP range for the given application. If so ISIS returns successful response with only a 904099 warning.
Please note we will whitelist upon approval from IT Security office ONLY.
{builder-hide}
h3.904099

A 904099 error code in the verifySession response is in fact a warning, not a fatal error. It means user's IP address has changed within a ISIS session, and session was exempted (kept alive) because application has been whitelisted. It's recommended to log it in your transaction log.
\\
\\

* Also see [For Help Desks|HelpDeskGuideToHandling604010Errors]