https://github.com/hackclub/auth
a better basket to put all your eggs in
https://github.com/hackclub/auth
idp oauth2 oidc saml saml2
Last synced: about 2 months ago
JSON representation
a better basket to put all your eggs in
- Host: GitHub
- URL: https://github.com/hackclub/auth
- Owner: hackclub
- Created: 2025-09-02T17:38:18.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2026-06-08T13:45:25.000Z (2 months ago)
- Last Synced: 2026-06-08T15:27:34.709Z (2 months ago)
- Topics: idp, oauth2, oidc, saml, saml2
- Language: Ruby
- Homepage: https://auth.hackclub.com
- Size: 44.8 MB
- Stars: 76
- Watchers: 1
- Forks: 50
- Open Issues: 62
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Hack Club Auth
This is the Rails codebase powering https://auth.hackclub.com!
## contributing
ask around in [#idv-dev](https://hackclub.slack.com/archives/C09D1E22CF5) or poke [nora](https://hackclub.slack.com/team/U06QK6AG3RD)!
avoid questions that can be answered by reading the source code, but otherwise i'd be happy to help you get up to speed :-D
kindly `bin/lint` your code before you submit it!
## local dev setup
### prerequisites
you'll need:
- ruby 3.4.4+ (i use [mise](https://mise.jdx.dev) to manage this)
- node.js + yarn
- postgres (see below)
- imagemagick & libvips (image processing)
- libxmlsec1 (SAML signing)
on macOS:
```bash
brew install imagemagick libvips libxmlsec1 yarn
```
### database
easiest way is docker. if you don't have it and you're on macOS, [orbstack](https://orbstack.dev) works well enough.
```bash
docker compose -f docker-compose-dbonly.yml up -d
```
this gives you a postgres instance at `postgresql://postgres@localhost:5432/identity_vault_development`.
if you've got your own postgres running somewhere, that works too – just point at it.
### environment
create a `.env.development` file:
```bash
DATABASE_URL=postgresql://postgres@localhost:5432/identity_vault_development
```
that's it for local dev – lockbox will use a deterministic dev key automatically. see [environment variables](#environment-variables) below for the full list.
### install & setup
```bash
bundle install
yarn install
bin/rails db:prepare
bin/rails db:seed
```
the seeds create a dev account with 2FA already set up. it'll print out the TOTP secret – add that to your authenticator app.
### running the thing
```bash
bin/dev
```
if you want hot reload on css & js, also run `bin/vite dev` in another terminal.
### logging in to the backend
1. go to http://localhost:3000/login
2. enter `identity@hackclub.com`
3. grab the verification code from http://localhost:3000/letter_opener
4. enter your TOTP code (from the authenticator app you set up during seeding)
5. head to http://localhost:3000/backend
the backend requires 2FA – that's why the seeds set up a TOTP for you.
## environment variables
### required
| var | description |
|-----|-------------|
| `DATABASE_URL` | postgres connection string |
### required in production
| var | description |
|-----|-------------|
| `SECRET_KEY_BASE` | rails secret key – generate with `openssl rand -hex 64` |
| `LOCKBOX_MASTER_KEY` | encryption key for lockbox fields – generate with `openssl rand -hex 32` |
### active record encryption
used for `encrypts` fields (like aadhaar data). generate these with `bin/rails db:encryption:init` or use random strings.
| var | description |
|-----|-------------|
| `ACTIVE_RECORD_ENCRYPTION_PRIMARY_KEY` | primary encryption key |
| `ACTIVE_RECORD_ENCRYPTION_DETERMINISTIC_KEY` | deterministic encryption key |
| `ACTIVE_RECORD_ENCRYPTION_KEY_DERIVATION_SALT` | key derivation salt |
### slack integration
| var | description |
|-----|-------------|
| `SLACK_BOT_TOKEN` | bot token (xoxb-*) |
| `SLACK_TEAM_ID` | workspace ID (T*) |
| `SLACK_SCIM_TOKEN` | SCIM API token for user provisioning |
| `SLACK_CLIENT_ID` | OAuth client ID |
| `SLACK_CLIENT_SECRET` | OAuth client secret |
| `SLACK_SIGNING_SECRET` | webhook request verification |
| `SLACK_ADULT_WEBHOOK_URL` | webhook for guardian notifications |
### SAML
| var | description |
|-----|-------------|
| `SAML_IDP_CERT_PATH` | path to SAML IdP certificate |
| `SAML_IDP_KEY_PATH` | path to SAML IdP private key |
generate a self-signed cert for local dev:
```bash
openssl req -x509 -newkey rsa:2048 -keyout saml_key.pem -out saml_cert.pem -days 365 -nodes -subj "/CN=localhost"
```
### OIDC
| var | description |
|-----|-------------|
| `OIDC_SIGNING_KEY` | RSA private key for JWT signing |
generate an RSA key:
```bash
openssl genrsa -out oidc_key.pem 2048
```
then set `OIDC_SIGNING_KEY` to the contents of `oidc_key.pem` (the whole thing including the BEGIN/END lines).
### email (production/staging/uat)
| var | description |
|-----|-------------|
| `SES_SMTP_HOST` | SES SMTP endpoint |
| `SES_SMTP_USERNAME` | SES SMTP username |
| `SES_SMTP_PASSWORD` | SES SMTP password |
### document storage (production)
| var | description |
|-----|-------------|
| `CLOUDFLARE_R2_ENDPOINT` | R2 endpoint URL |
| `CLOUDFLARE_R2_ACCESS_KEY_ID` | R2 access key |
| `CLOUDFLARE_R2_SECRET_ACCESS_KEY` | R2 secret key |
### other
| var | description |
|-----|-------------|
| `SENTRY_DSN` | error tracking |
| `GOOGLE_PLACES_API_KEY` | address autocomplete |
| `ANALYTICS_DATABASE_URL` | separate analytics DB (optional) |
| `DISABLE_ANALYTICS` | set to "true" to disable Ahoy |
| `SOURCE_COMMIT` | git commit for version display |
## security
this oughta go without saying, but if you find a security-relevant issue please either contact me directly or go through the security.hackclub.com flow –
if you just open an issue or a PR there's a chance a bad actor sees it and exploits it before we can patch or merge.