{"id":18813286,"url":"https://github.com/stustanet/helgrind","last_synced_at":"2025-04-13T21:26:17.221Z","repository":{"id":115880605,"uuid":"129565878","full_name":"stustanet/helgrind","owner":"stustanet","description":"Welcome to hell (if authenticated).","archived":false,"fork":false,"pushed_at":"2020-12-07T11:07:39.000Z","size":32,"stargazers_count":4,"open_issues_count":0,"forks_count":1,"subscribers_count":6,"default_branch":"master","last_synced_at":"2023-03-06T05:19:34.348Z","etag":null,"topics":["authentication","authentication-proxy","certificate","client-auth","gateway","helgrind","mutual-authentication","tls"],"latest_commit_sha":null,"homepage":"https://gitlab.stusta.de/stustanet/helgrind","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stustanet.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-04-15T00:58:09.000Z","updated_at":"2024-06-19T10:10:17.752Z","dependencies_parsed_at":null,"dependency_job_id":"b52a37c8-12c5-4cce-96a0-d783d8d8d3f8","html_url":"https://github.com/stustanet/helgrind","commit_stats":null,"previous_names":[],"tags_count":0,"template":null,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stustanet%2Fhelgrind","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stustanet%2Fhelgrind/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stustanet%2Fhelgrind/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stustanet%2Fhelgrind/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stustanet","download_url":"https://codeload.github.com/stustanet/helgrind/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248784217,"owners_count":21161077,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["authentication","authentication-proxy","certificate","client-auth","gateway","helgrind","mutual-authentication","tls"],"created_at":"2024-11-07T23:36:58.310Z","updated_at":"2025-04-13T21:26:17.199Z","avatar_url":"https://github.com/stustanet.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Helgrind\nHelgrind is an HTTPS Authentication Gateway with strong focus on security.\n\n## Gateway Setup\n\nMake sure Git and Go 1.8+ (on Debian Stretch one can use stretch-backports) are installed on the host system.\n\n```sh\ngo get gitlab.stusta.de/stustanet/helgrind\n```\n\nHelgrind requieres a TLS certificate to offer HTTPS. You can acquire one e.g. via [Let's Encrypt](https://letsencrypt.org/) and [certbot](https://certbot.eff.org/).\n\n### Certificate Authority\nGenerate a CA certificate and private key:\n\n```sh\nopenssl genrsa -aes256 -out ca.key 4096\nchmod 400 ca.key\nopenssl req -new -x509 -sha256 -days 3650 -key ca.key -out ca.crt\nchmod 444 ca.crt\n```\n\nThe `ca.key` should be kept private in a secure offline storage. The `ca.crt` has to be copied to the gateway server.\n\n### Helgrind Config\nFirst copy the example file to `/etc/helgrind.json`:\n\n```sh\ncp $GOPATH/src/gitlab.stusta.de/stustanet/helgrind/etc/helgrind.json.example /etc/helgrind.json\n```\n\nThen adjust the `/etc/helgrind.json` config file.\nEach backend service has to be configured in its own block.\nUser access is granted per service.\n\n### systemd service\n\nFirst, create a separate user for helgrind:\n\n```sh\nuseradd --system -s /bin/false -M helgrind\n```\n\nThen copy the systemd unit files:\n\n```sh\ncp $GOPATH/src/gitlab.stusta.de/stustanet/helgrind/systemd/helgrind.* /etc/systemd/system/\n```\n\nAdjust `/etc/systemd/system/helgrind.socket` and `/etc/systemd/system/helgrind.service` if necessary.\n\nAfterwards, run:\n\n```sh\nsystemctl enable helgrind.socket helgrind.service\nsystemctl start helgrind.socket helgrind.service\n```\n\n## Adding a Service\nCreate a new entry in `services` in the `/etc/helgrind.json` and set the target (URL to be reverse-proxied). HTTPS should be used.\n\nAlso set a unique base64 encoded secret (which will be shared with the backend) to create the HMAC signatures.\nYou can for example generate a random 64 bytes (the length of the secret does not need to be 64 bytes) long base64 string as follows:\n\n```sh\nbase64 --wrap=0 /dev/urandom |head -c 64\n```\n\nThe backend server should verify the signature and parse the user information sent by the helgrind server. For that, the [`hel`](https://godoc.org/gitlab.stusta.de/stustanet/helgrind/hel) package can be used.\n\n\n## Adding a User\nFirst the **user** has to generate a private key and a signing request for it:\n\n```sh\nopenssl genrsa -out client.key 2048\nopenssl req -new -key client.key -out client.csr\n```\n\nThen the `client.csr` (the private key must not be shared) has to be sent to the **gateway admin**, which has to sign the certificate:\n\n```sh\nopenssl x509 -req -days 730 -sha256 -in client.csr -CA ca.crt -CAkey ca.key -set_serial 1 -out client.crt\nopenssl x509 -noout -fingerprint -sha256 -inform pem -in client.crt\n```\n\nThe SHA256 fingerprint of the certificate is required to grant access to a backend service, which can be configured in the `/etc/helgrind.json` on the helgrind server.\n\nThe `client.crt` then has to be sent back to the user, who then creates a PKCS#12 file from the private key and the certificate, which can then imported in the browser (Firefox) or system keychain (Chrome).\n\n```sh\nopenssl pkcs12 -export -clcerts -in client.crt -inkey client.key -out client.p12\n```\n\n### Browser Import\nFirefox: Preferences \u003e Advanced \u003e Certificates \u003e View Certificates \u003e Your Certificates\n\nChrome: Import in the system keychain instead, which is used by Chrome.\n\n\n## Access Revocation\nAccess can easily be managed in `/etc/helgrind.json`. Either the user can be removed entirely or the specific user or user device can be set to `Enabled = false`.\n\n## TODO\n- create a signature (HMAC) for the whole request body and selected headers\n- include a timestamp in the HMAC\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstustanet%2Fhelgrind","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstustanet%2Fhelgrind","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstustanet%2Fhelgrind/lists"}