The heimdall from dami-18

Heimdall

The network checker for IIT KGP
Report Bug · Request Feature

Table of Contents

About The Project
- Supports
Getting Started
- Prerequisites
- Installation
Usage
Maintainer(s)
Contact
Additional documentation

About The Project

Heimdall checks the client's IP to know whether the request has originated from inside the IIT Kharagpur network and verifies their institute email ID. This helps to ascertain if the client is a current member of the institute and should have access to certain information.

(back to top)

Supports:

Shells
- bash
- zsh
OS(s)
- any *nix[GNU+Linux and Unix]

(back to top)

Getting Started

To set up a local instance of the application, follow the steps below.

Prerequisites

The following dependencies are required to be installed for the project to function properly:

go
nodejs

To create credentials.json file, create the OAuth consent screen and then create OAuth client ID credentials by following the steps provided there. While creating OAuth client ID credentials, set redirect URL to any port of the localhost. Then save downloaded json file as credentials.json in the project's root folder.

Then enable Gmail API to enable receiving OTP.

(back to top)

Installation

Now that the environment has been set up and configured to properly compile and run the project, the next step is to install and configure the project locally on your system.

Clone the repository

git clone https://github.com/metakgp/heimdall.git

Configure environment variables
```
cd ./heimdall
cp .env.template .env
```
Choose a strong JWT_SECRET_KEY and edit the .env file accordingly.
Install go dependencies
```
go mod download
```
Compile the code
```
go build
```
Execute the script
```
./heimdall
```

When prompted to enter authorization code, visit the link provided in terminal which will redirect to localhost. Then inspect the url after redirection and copy the string after code= and paste it in the terminal. This will create token.json file. You need to create this token only once and it will be valid for 6 months.

Above steps set up the backend server required for Heimdall. Now, to get access to services Naarad and Chillzone, enter the institute mail id at the frontend. To launch the frontend, please refer the instructions here

(back to top)

How to use?

Enter your institute mail id in the box provided on screen. You will receive an OTP if the provided mail id is a valid institute mail id. In that case, enter the OTP received at the provided email address and verify. These verifies that you are a current member of the institute.

Next, you will have access to services like Naarad and Chillzone which are available only for KGPians. These can be accessed via the campus network.

(back to top)

How does this work?

IIT Kharagpur has its internal campus network which is the primary source of Internet for its students, staff and faculty.

For connection to the outside network (normal internet services), it uses a NAT Gateway which handles all requests going outside. While doing so, the client IP address in those requests is changed from the internal IP to any one of the pool of public IP addresses assigned to IIT Kharagpur.

So, to check whether a request has originated from inside the IIT Kharagpur network, we just check whether the client's IP address belongs to one of those public IPs.

While just doing this would have sufficed, we do not know whether these Public IPs are permanent or are subject to change over time. We therefore do a Whois lookup of the IP address and check its response to decide whether this IP address belongs to IIT Kharagpur. A screenshot of such a Whois lookup is shown below.

For complete Whois information check here.

(back to top)

All this time you might be wondering why you need a different server to just check this. Can't we do this in any project where such a feature is required?

Well yes. Provided it has a backend server. This cannot be done in the front-end because the Web Browser does not provide the IP information to the Javascript engine. So for projects that do not need a backend, like Chillzone or ERP Auto Login, this simple API call can do the required work.