mirror of
https://github.com/System-End/identity-vault.git
synced 2026-04-19 19:45:08 +00:00
174 lines
4.9 KiB
Markdown
174 lines
4.9 KiB
Markdown
# 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.
|