 |
There are two ways to get eduLogon to function at your campus. If you use either of these methods to help me get eduLogon working at your campus, I'll give you license keys for yourself and up to 15 friends. I am trying to get eduLogon to work at as many campuses as possible, and would very much appreciate your help.
Option 1: Send me the information
I can set up the eduLogon program to work with your campus network if I know a few simple things about how the logon system at your campus works. Some of the information is a tiny bit technical, but if you can operate a web browser (and you can, you're reading this :)) you can send me what I need. You can send this information to my email,  .
Eight details I need for your campus:
Note: You'll need to grab this information while on campus, right after connecting to wireless. Don't log on until you've got everything.
- The abbreviation for your campus
You know, MIT, or CMU :). This is just used in messages displayed onscreen, but I don't always know what the right abbreviation for a school is, and it would probably look pretty bad if I got it wrong.
- The domain name (or "DNS Suffix") assigned to your computer when you connect.
To find this out, open a command prompt by:
In Windows XP:
- going to the start menu and clicking run
- typing "cmd" in the window that appears and clicking OK
or on vista:
- searching for "command prompt"
Once you have a command prompt open, type "ipconfig" at the prompt. Text should appear similar to that displayed below.
All you need to send me is the part circled in yellow. Usually this is similar to your school's web address.
- The URL of the first page you get sent to when you open your browser.
When you are not logged in to your campus network, you will get redirected to one or more web pages so you can log in. On many campuses, the first page you get redirected to is the one with the actual form that allows you to log in, but not always. If the first page you get sent to does not have the actual logon form, send me the url (copied/pasted from your browser) of this first page.
- The URL of the page containing the form you use to log on
If different from the address in part 3.
- A copy of the webpage containing the form you use to log on
To send me this, go to file->save as (or save webpage as) when you are at the logon page in your browser. Attach the file you save to the email. (Alternatively, if you know how to view the HTML source of the page, you can copy/paste the html source into the body of the email.)
- The message displayed if you try to log on with a username that doesn't exist
Just put in a bogus username and password, and copy/paste the error message from your web browser that it gives you into your email. I do not need entire html documents/pages here, just the text of the error message itself.
(This enables the eduLogon program to display an error message to the user if a wrong username is used, and allows them to try logging in with different credentials.)
- The message displayed if you try to log on with your username but the wrong password
Same as before, but use your real username and put a typo in your password. Again, copy/paste the error message that it gives you. If it's the same as the last one, you can just note that.
- And finally, The message displayed when you enter a correct username and password.
Same idea as the last two. Copy/paste from your web browser. If you are sent directly to the web page you were originally trying to access, with no explicit confirmation of being logged in, let me know that instead.
Option 2: Edit config.xml yourself
For those more comfortable with HTML and HTTP, you can download eduLogon and add an entry in the config.xml file for your school. If you succeed in or want help with this, PLEASE contact me. Use the existing entries in the file, the above enumeration of the necessary information, and the below instructions as a guide. Config.xml can be found in the directory you install eduLogon to. There is also a formal document type definition for config.xml distributed in the installer, named config.dtd. If you have a dtd-aware xml editor, (Visual Studio is one,) use it. The DTD is enforced by the eduLogon agent, and it will exit if your edits to config.xml violate the dtd.
Note: you'll usually have to quit and restart eduLogon for it to read your changes to conf.xml.
Here's documentation on the structure of the xml and the purpose of the tags.
- Network tag: - Encapsulates all information needed for a particular campus.
Attributes:
domain: The domain name given to machines on the network by dhcp. This is the portion circled in yellow in the above screenshot of ipconfig.
institution: The common, human-readable name for this campus. Used in onscreen user interface displays.
abbreviation: The common, human-readable abbreviation for this campus. I.E. UMN. (Can be more than three letters.)
- testsite tag: - Describes a site eduLogon should attempt a connection to when it needs to test if the user is already authenticated and has Internet access. The premise is that if a connection to the test site yields some string (either in HTTP header or in body) that is known to occur in the institution's authentication redirect or authentication page, and not on the actual page at the test site address, then we have determined that the request was in fact serviced by the authentication server, and we are not authenticated. (Details about selection and specification of the string to search for is described in the trigger tag.) You must provide at least two testsites per network. I think eduLogon will crash with only one, and one would not be sufficiently robust.
A good test site will: *Be reliable, *Respond quickly, *Be small, if the entire document at the testsite address must be fetched. *Have predictable content, particularly if the negate attribute of trigger is set.
Some good test site examples: *If on-campus intranet sites are blocked when the user is not yet logged on, one good choice is the institution's homepage. *If the institution's authentication server provides a page that says the current user's authentication status, this is another possibility. *The Google homepage is a good default standby.
Attributes:
address: The url of the test site
- trigger tag: - Describes the content in the http response from the testsite that will trigger authentication.
At institutions that employ http redirection to send users to their logon page, triggers for all your testsites can be of type "header", the name attribute can be set to "Location", and the trigger value can be the address of the page users are redirected to where they perform authentication. (with the possible exception of a testsite that is the institution's authentication page that says whether or not you are logged on, see UMD's port.d.umn.edu testsite for an exmaple.)
Attributes:
type: ["header" | "body"]. Whether the triggering content appears in the http header of the response or in the complete html at the address.
name (Only when type is "header"): The name of the http header field in the response to search.
negate (Optional): ["true" | "false"]: The standard behavior is to assume authentication is necessary if the string specified as the trigger's value is found in the response; set this to true to always authenticate unless the string specified as the trigger's value is found in the response. Using this attribute, it is possible to set up triggers that cause authentication to occur if some expected phrase is absent in the response. This is only suitable if the content of the true testsite is stable and predictable; use sparingly.
Value: (contained between trigger start and end tags)
The string to search for in the response.
- login tag: - Models the https request that causes authentication to occur.
Attributes:
service: The complete url of the authentication web service, beginning with https. Defined in the "action" attribute of the <form> html tag on your institution's logon page - see the html source.
signature (Optional): A digital signature for the service address, computed using my private key. Omit when testing new networks. See security statement below.
referrer (Optional): The complete url of the page to report as referrer in the http head of the request. Some logon services need this - if so, it will probably be the url of the page containing the logon form.
- username tag:
Attributes:
name: The name of the input field containing the username. This is defined in an <input> html tag in the form on your institution's logon page; see the page's html source.
- password tag:
Attributes:
name: The name of the input field containing the password. This is defined in an <input> html tag in the form on your institution's logon page; see the page's html source.
- static-fields tag: - A collection of other fields included in the form on your institution's logon page. See html source of the form. These are usually things like <input type="hidden" name="action" value="login">, specifiers of authentication domains, etc. All must be name/value pairs that appear in the logon form html and are the same for all users. (If your institution requires additional non-static fields in their form besides username and password, contact me.)
- input tag (multiple instances of this tag are permissible): Describes a static name/value pair to submit as part of the logon request. Do not include an entire input tag from an html form - only the name and value attributes are valid here.
Attributes:
name
value
- responses tag: - Identifies strings to search for in the response from the logon server to determine if the authentication was successful or if an invalid password was entered.
- success tag: - When everything goes well, the value of this tag (between start and end tags) can be found in the server's response. Usually a phrase like "You are now logged on" or "logon successful" or somesuch is returned as part of the html, if so that works well.
- bad-credentials tag (multiple instances of this tag are permissible): - The value of this tag should be the error returned by the server when the user enters a bad username or password. At institutions that return different errors for unknown username and bad password, you can include a separate bad-credentials tag for each error string. (eduLogon does not differentiate between the two types of logon failure, but needs to know both error strings to detect and handle the authentication error.)
As a security feature, the url's to which usernames and passwords are sent contain digitial signatures in the xml file that must compliment the url's in order for automatic logon to take place. These are based on an RSA private key; you will not be able to sign logon url's that you add to the file yourself. As a result, eduLogon will display a security warning and require manual password entry when sending to logon services you have defined yourself. However, this is sufficient for testing whether your xml settings are correct for your campus and verifying that successful authentication via eduLogon is possible. Once this is complete, send me your conf.xml file, and I will verify and sign the authentication server url and send the file back to you. (This prevents attackers from writing malware that changes your conf.xml to send passwords to their own server. Forced manual password entry prevents passwords from being revealed in the case of physical theft of a customer's laptop.)
If your campus uses the Cisco Clean Access/Perfigo access control and authentication system, it is known not to work with eduLogon and is likely never to be supported, see this blog post.
|
|
