You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
_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._
64
-
65
-
<palign="right">(<ahref="#top">back to top</a>)</p>
66
-
67
-
<divid="supports"></div>
68
-
69
-
### Supports:
70
-
71
-
<!-- UPDATE -->
72
-
73
-
1. Shells
74
-
-`bash`
75
-
-`zsh`
76
-
2. OS(s)
77
-
- any `*nix`[`GNU+Linux` and `Unix`]
64
+
_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._
78
65
79
66
<palign="right">(<ahref="#top">back to top</a>)</p>
80
67
@@ -86,16 +73,16 @@ To set up a local instance of the application, follow the steps below.
86
73
87
74
The following dependencies are required to be installed for the project to function properly:
To create credentials.json file, create the [OAuth consent screen](https://developers.google.com/workspace/guides/configure-oauth-consent#configure_oauth_consent) and then create [OAuth client ID credentials](https://developers.google.com/workspace/guides/create-credentials#oauth-client-id) 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.
95
-
96
-
Then enable [Gmail API](https://console.cloud.google.com/apis/library/gmail.googleapis.com) to enable receiving OTP.
79
+
To create the `credentials.json` file, set up the things below by following the respective guides:
-[OAuth client ID credentials](https://developers.google.com/workspace/guides/create-credentials#oauth-client-id).
82
+
- While creating OAuth client ID credentials, set the redirect URL to any port of localhost.
83
+
- Save the downloaded JSON file as `credentials.json` in the project's root directory.
84
+
- Then enable [Gmail API](https://console.cloud.google.com/apis/library/gmail.googleapis.com) to enable receiving OTP.
97
85
98
-
99
86
<palign="right">(<ahref="#top">back to top</a>)</p>
100
87
101
88
### Installation
@@ -113,9 +100,9 @@ _Now that the environment has been set up and configured to properly compile and
113
100
cd ./heimdall
114
101
cp .env.template .env
115
102
```
116
-
Choose a strong JWT_SECRET_KEY and edit the .env file accordingly.
103
+
Choose a strong JWT_SECRET_KEY and edit the `.env` file accordingly.
117
104
118
-
3. Install go dependencies
105
+
3. Install Go dependencies
119
106
```sh
120
107
go mod download
121
108
```
@@ -128,29 +115,27 @@ _Now that the environment has been set up and configured to properly compile and
128
115
./heimdall
129
116
```
130
117
131
-
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.
118
+
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.
132
119
133
-
Above steps set up the backend server required for Heimdall. Now, to get access to services [Naarad](https://github.com/metakgp/naarad) and [Chillzone](https://github.com/metakgp/chillzone), enter the institute mail id at the frontend. To launch the frontend, please refer the instructions [here](https://github.com/metakgp/heimdall/blob/master/frontend/README.md)
120
+
The above steps set up the backend server required for Heimdall. To launch the frontend, please refer to the instructions [here](https://github.com/metakgp/heimdall/blob/master/frontend/README.md)
134
121
135
122
<palign="right">(<ahref="#top">back to top</a>)</p>
136
123
137
124
### How to use?
138
125
139
-
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.
126
+
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.
140
127
141
-
Next, you will have access to services like [Naarad](https://github.com/metakgp/naarad) and [Chillzone](https://github.com/metakgp/chillzone) which are available only for KGPians. These can be accessed via the campus network.
128
+
Next, you will have access to services like [Naarad](https://github.com/metakgp/naarad) and [Chillzone](https://github.com/metakgp/chillzone), which are available only for KGPians. These can be accessed via the campus network.
142
129
143
130
<palign="right">(<ahref="#top">back to top</a>)</p>
144
131
145
132
<!-- BACKGROUND INFORMATION -->
146
133
147
134
## How does this work?
148
135
149
-
<!-- UPDATE -->
136
+
IIT Kharagpur has its internal campus network, which is the primary source of Internet for its students, staff, and faculty.
150
137
151
-
IIT Kharagpur has its internal campus network which is the primary source of Internet for its students, staff and faculty.
152
-
153
-
For connection to the outside network (normal internet services), it uses a [NAT Gateway](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-nat-gateway.html) 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.
138
+
For connection to the outside network (normal internet services), it uses a [NAT Gateway](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-nat-gateway.html), 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.
154
139
155
140
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.
156
141
@@ -161,24 +146,32 @@ While just doing this would have sufficed, we do not know whether these Public I
<palign="right">(<ahref="#top">back to top</a>)</p>
152
+
> [!Note]
153
+
> The above functionality is implemented in the main (`/`) route
168
154
169
-
When user enters institute mail id and verifies using 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 user's institute mail id, which can be retrieved from it.
155
+
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.
170
156
171
-
The endpoint `/validate-jwt` validates the cookie which is sent along with the request to access internal services like Naarad and Gyft. Once user's mail id is verified, he/she can access above services, making sure that they are accessible only to institute students.
157
+
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.
172
158
173
-
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?
159
+
### Why heimdall as a service?
174
160
175
-
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](https://github.com/metakgp/chillzone) or [ERP Auto Login](https://github.com/metakgp/iitkgp-erp-auto-login), this simple API call can do the required work.
161
+
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?
162
+
163
+
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](https://github.com/metakgp/chillzone) or [ERP Auto Login](https://github.com/metakgp/iitkgp-erp-auto-login), this simple API call can do the required work.
164
+
165
+
Also, one service - to protect all of our services. Reducing code repetition and easy integration.
166
+
167
+
<palign="right">(<ahref="#top">back to top</a>)</p>
176
168
177
169
## Maintainer(s)
178
170
179
171
<!-- UPDATE -->
180
172
181
173
-[Chirag Ghosh](https://github.com/chirag-ghosh)
174
+
-[Arpit Bhardwaj](https://github.com/proffapt)
182
175
183
176
<palign="right">(<ahref="#top">back to top</a>)</p>
0 commit comments