Table of Contents
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 the information provided by metaKGP services protected by Heimdall.
To set up a local instance of the application, follow the steps below.
The following dependencies are required to be installed for the project to function properly:
To create the credentials.json file, set up the things below by following the respective guides:
- OAuth consent screen.
- OAuth client ID credentials.
- While creating OAuth client ID credentials, set the redirect URL to any port of localhost.
- Save the downloaded JSON file as
credentials.jsonin the project's root directory. - Then enable Gmail API to enable receiving OTP.
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 .envChoose a strong JWT_SECRET_KEY and edit the
.envfile accordingly. -
Install Go dependencies
go mod download
-
Compile the code
go build
-
Execute the script
./heimdall
When prompted to enter the authorization code, visit the link provided in the 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 a token.json file. You need to create this token only once, and it will be valid for 6 months.
The above steps set up the backend server required for Heimdall. To launch the frontend, please refer to the instructions here
Enter your institute mail ID in the box provided on the 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. This verifies that you are a present 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.
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 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.
Note
The above functionality is implemented in the main (/) route
When the user enters the institute mail ID, an OTP is sent (/get-otp) and once they verify the OTP (/verfiy-otp), a cookie is generated which is valid only for the domain *.metakgp.org (including its subdomains like naarad.metakgp, gyft.metakgp, etc.). This cookie contains the user's institute mail ID, which can be retrieved from it.
The endpoint /validate-jwt validates the cookie that is sent along with the request to access internal services like Naarad and Gyft. Once the user's mail ID is verified, they can access the above services, making sure that they are accessible only to institute students.
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.
Also, one service - to protect all of our services. Reducing code repetition and easy integration.
📫 Metakgp -