{"id":21894164,"url":"https://github.com/hackgt/ground-truth","last_synced_at":"2025-07-24T06:06:33.236Z","repository":{"id":36436384,"uuid":"174927313","full_name":"HackGT/ground-truth","owner":"HackGT","description":"🛰 Single sign on for HackGT apps","archived":false,"fork":false,"pushed_at":"2023-03-05T21:52:18.000Z","size":2123,"stargazers_count":7,"open_issues_count":29,"forks_count":2,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-06-05T00:24:30.923Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://login.hack.gt","language":"TypeScript","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/HackGT.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,"zenodo":null}},"created_at":"2019-03-11T04:46:43.000Z","updated_at":"2023-01-24T21:09:53.000Z","dependencies_parsed_at":"2025-04-15T15:31:52.735Z","dependency_job_id":"d33b55a4-7553-4810-afae-ebbc79f1ff3e","html_url":"https://github.com/HackGT/ground-truth","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/HackGT/ground-truth","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HackGT%2Fground-truth","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HackGT%2Fground-truth/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HackGT%2Fground-truth/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HackGT%2Fground-truth/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/HackGT","download_url":"https://codeload.github.com/HackGT/ground-truth/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HackGT%2Fground-truth/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266801466,"owners_count":23986372,"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","status":"online","status_checked_at":"2025-07-24T02:00:09.469Z","response_time":99,"last_error":null,"robots_txt_status":null,"robots_txt_updated_at":null,"robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":[],"created_at":"2024-11-28T13:19:39.362Z","updated_at":"2025-07-24T06:06:33.207Z","avatar_url":"https://github.com/HackGT.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# HackGT Ground Truth 🛰️\n\nSingle sign on for hackathon apps and services using OAuth 2.0\n\n## What is it?\n\nGround Truth is an authentication mechanism for various hackathon services. It replaces various email / password systems living  in multiple apps in favor of a single, long lived account that can be easily reused.\n\nFor example, at HackGT, we use Ground Truth to provide authentication for:\n* [Event registration](https://github.com/HackGT/registration)\n\t* Users don't have to create a new account for every HackGT, HackGTeeny, BuildGT, or HackGT: Horizons event, reducing confusion.\n* Event check-in and badge scanning (organizing staff only)\n* Team formation site\n* HackGT event mobile app\n\n## Why should I use it?\n\nGround Truth allows participants to create a single HackGT account that stays around for their college careers as they apply to various HackGT-hosted hackathons. This reduces confusion about whether participants already have an account or not and makes for a simpler, streamlined registration and login process.\n\nAdditionally, by consolidating all authentication code into a single, dedicated repository, Ground Truth allows for better security auditing and practices that would be impractical in multiple codebases. While non-dedicated authentication systems might only support insecure username / password logins, integrating with Ground Truth allows for external provider login (e.g. Google, GitHub, Facebook) as well as FIDO2 passwordless login and two factor authentication.\n\n## What can it do?\n\nGround Truth allows users to log in to their HackGT account using the following methods:\n\n* Conventional password\n\t* Support for FIDO U2F coming soon\n* Google\n* GitHub\n* Facebook\n* [Georgia Tech CAS login system](https://login.gatech.edu)\n* FIDO2 passwordless login using a security key\n\nOther OAuth 2.0 and CAS login providers can be easily added in `src/auth/strategies`\n\nAdmins can enable or disable whichever login methods they desire.\n\n## How to Run\n\nTo setup, copy the `default.json` file to `development.json` in the `config` folder and configure the variables in this file. Enable certain login methods with the `loginMethods` config variable.\n\nAdditionally, Ground Truth can use environment variables for setup for use in production. The names of these variables can be found in `src/common.ts`. Note, you only need to fill in the secrets for the services you will be using.\n\nAfter filling in the config file or the environment variables, follow these steps:\n\n1. `yarn install`\n2. `yarn dev`\n\n## How do I use it?\n\nGround Truth acts like any other OAuth 2.0 compliant system.\n\nAs an admin, visit `/login` and click through to the admin panel.\n\n### Apps\n\nTo create an app, you'll need the name of your application and which URI(s) it will redirect back to once authentication is complete.\n\nThis can include something like `http://localhost:3000` during development, but you should ideally create different development and production apps for better security.\n\n![Add an OAuth application](https://i.imgur.com/aKxH2mH.png)\n\nPrivate / public app type determines whether your app can keep the client secret private (e.g. a typical server-hosted application) or if it is at risk of being revealed (e.g. a mobile app) and should use [PKCE](https://www.oauth.com/oauth2-servers/pkce/) instead.\n\nOnce an app is created, it's name and redirect URIs can be changed after. Additionally, its secret can be regenerated and the app can be deleted when needed.\n\n### Scopes\n\nScopes allow an application to access more information about a user. When an application provides a scope when authenticating, Ground Truth will include the information in the user data, and will ask the user for the necessary information if needed.\n\nExamples of scopes include asking for a slack username or a phone number.\n\n![Add a scope](https://i.imgur.com/QLByfds.png)\n\nThe scope question field determines the question to show to the user when asking for this information. The input type follows [HTML input types](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#Form_%3Cinput%3E_types) and the icon field can be any [font awesome icon](https://fontawesome.com/icons?d=gallery\u0026s=solid).\n\nIf the scope needs to be validated, both the validation code and validation error messaged need to be provided. The validation works by using the Node.js `vm.runInNewContext()` [method](https://www.geeksforgeeks.org/node-js-vm-runinnewcontext-method/). The context object provided is of TypeScript type `IScopeValidatorContext` and contains these fields:\n```js\n{\n\tname, \t// Name of user\n\temail, \t// Email of user\n\tscope, \t// Name of scope\n\ttype, \t// Input type of scope\n\tvalue \t// The value the user provides\n}\n```\n\nAn example validator that can be used for a phone number is `(/^\\(?(\\d){3}\\)? ?(\\d){3}-?(\\d){4}$/).test(value)`.\n\n## How do I integrate it?\nGround Truth follows standard [OAuth 2 protocol](https://auth0.com/docs/protocols/protocol-oauth2).\n\nHere are the URLs Ground Truth uses for authentication:\n- Authorization URL: `/oauth/authorize`\n- Token URL: `/oauth/token`\nSee the API Reference below for more information.\n\nAfter authorization, use the `/api/user` endpoint via GET to access user data. Authentication is done with a bearer token using the access token. The API will return a JSON with these fields of the user:\n```js\n{\n\tuuid,\t\t\t// UUID\n\tname,\t\t\t// Formatted full name\n\tnameParts: {\n\t\tfirst,\t\t// First name\n\t\tpreferred,\t// Preferred name (if provided)\n\t\tlast\t\t// Last name\n\t},\n\tadmin,\t\t\t// Boolean value if user is admin\n\tmember,\t\t\t// Boolean value if user is member\n\temail,\t\t\t// Email\n\tscopes\t\t\t// Object of scope data\n}\n```\n\n## OAuth API Reference\n\n### GET `/oauth/authorize`\nEndpoint to start OAuth flow\n| Parameter | Description |\n|---|---|\n| `response_type` | Tells the authorization server which grant to execute |\n| `client_id` | \tThe ID of the application asking for authorization |\n| `redirect_uri` | The URL to redirect to after a successful response |\n| `scope` | _(Optional)_ A space-delimited list of permissions that the application requires |\n| `code_challenge` | _(Optional - PKCE)_ A code challenge string based on the client generated code verifier\n| `code_challenge_method` | _(Optional - PKCE)_ Supports SHA256 hash - `S256` |\n\n### POST `/oauth/token`\nExchanges an authorization code for an access token\n| Parameter | Description |\n|---|---|\n| `grant_type` | Tells the authorization server which grant to execute |\n| `code` | \tThe authorization code provided from the redirect to exchange for an access token |\n| `redirect_uri` | The redirect URL that was used in the initial request |\n| `code_verifier` | _(Optional - PKCE)_ The code verifier for the PKCE request, that the app originally generated before the authorization request\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhackgt%2Fground-truth","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhackgt%2Fground-truth","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhackgt%2Fground-truth/lists"}