https://github.com/hilliamt/node-auth-imperial
A Promise-based NodeJS authentication method for Imperial College student accounts
https://github.com/hilliamt/node-auth-imperial
authentication imperial-college-london nodejs
Last synced: 20 days ago
JSON representation
A Promise-based NodeJS authentication method for Imperial College student accounts
- Host: GitHub
- URL: https://github.com/hilliamt/node-auth-imperial
- Owner: HilliamT
- License: mit
- Created: 2019-09-21T18:14:06.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2021-01-05T14:38:50.000Z (over 4 years ago)
- Last Synced: 2025-03-27T13:12:39.093Z (about 1 month ago)
- Topics: authentication, imperial-college-london, nodejs
- Language: JavaScript
- Homepage:
- Size: 187 KB
- Stars: 4
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
# node-auth-imperial
A Promise-based NodeJS authentication method for Imperial College student accounts. You may find this useful for any applications you are building for student development initiatives on Imperial's campus.
[](https://www.npmjs.com/package/auth-imperial) [](https://www.npmjs.com/package/auth-imperial) [](https://www.npmjs.com/package/auth-imperial) [](https://www.npmjs.com/package/auth-imperial)
## Installing
Assuming you have `node` and `npm` installed, the package can be installed from `npm`'s public registry.
```
npm install auth-imperial
```
## Usage
The module exports one simple default method. Usage examples are below.
```
const authImperial = require("auth-imperial");
(async () => {
let loggedIn = await authImperial("SHORTCODE", "PASS");
console.log(loggedIn);
})();
// OR
authImperial("SHORTCODE", "PASS").then(loggedIn => {
console.log(loggedIn);
});
```
## Inspiration
This came about through the lack of methods to authenticate Imperial student accounts externally of the Imperial College website, with the only other provider on campus requiring setting up a Kerberos instance within the Imperial network to communicate with.
This hindered the development of student projects involving Imperial accounts, having to seek very special permissions from the Imperial ICT team.
## Original Method
After finding an undocumented public API upon the Imperial.ac.uk website, this module was created to allow for student-led projects to attach user accounts to their Imperial student accounts using this API. This was done via:
POST https://www.imperial.ac.uk/secure/login/
The body for the `POST` request is of the format
{
uname: string, // Username / Imperial Shortcode
pwd: string // Password for their Imperial account
}
The response from this endpoint would return the resulting HTML of the page to load, which will detail an error message just above the login form based on the success of the login, which was checked against using `cheerio`.
## Current Method
After the Imperial ICT team reached out to us to note that the API endpoint would be deprecated as it was an old webpage that should have been removed long ago but activity from societies and student projects using the endpoint made the ICT team aware of this legacy endpoint.
Luckily, the Imperial College Student Union does offer an endpoint for students to use, which this module has been adapted to using.
POST https://eactivities.union.ic.ac.uk/user/login
The body for the `POST` request is of the format
{
username: string, // Username / Imperial Shortcode
password: string // Password for their Imperial account
}
If the username or password is incorrect, a `HTTP 4XX ERROR` is thrown, which is caught and regarded as a failed login attempt. If the user's details are correct, a `HTTP 200 OK` is returned, with the user understood to be verified.