Skip to content

Sign-in and email

People sign in without passwords: they type their email address, Keycloak emails them a six-character code, and the code signs them in. The one exception is the default administrator, admin, which has a password and must change it at its first sign-in (installation setup). Anyone can use Explore without an account; signing in is for people someone has invited. Keycloak only proves who someone is: what they may do lives in CHART's database (access control).

How it works

infra/keycloak/sync-realm.js (run by make identity-sync and by every deploy) sets the chart realm up:

  • the browser flow chart email code: an existing session, or the email address followed by a code sent to it;
  • codes are 6 characters, last 10 minutes, can be resent after 60 seconds, and at most SIGN_IN_CODE_LIMIT (default 5) are sent to one person in 15 minutes, so nobody can flood an inbox;
  • self-registration and password reset are off. An unknown or disabled address gets an error and no email;
  • Keycloak sends the email itself through the SMTP server below;
  • after the code, CHART opens the dashboard of the person's own area (the area the Planning center would pick; for Kenya, Kajiado), or the page that asked them to sign in.

The two screens, CHART login (email) and Check your email (code), use CHART's fonts and colours. On screens 960px and wider they follow the design's sign-in frame: a charcoal panel on the left with the wordmark, "Plan for climate-health risk, together." and the three steps, and the form on its right. Narrower screens keep the bar and a full-width form. The email step also offers Explore the map without an account and says that an administrator adds accounts. They are the chart login theme: infra/keycloak/themes/chart/login/ holds their templates (login-username.ftl, login-email-otp.ftl, and footer.ftl for the brand panel), wording (messages/messages_en.properties) and styles (resources/css/chart.css).

Keycloak serves theme files under a path that changes only with the Keycloak version, and browsers keep them for 30 days. So theme.properties names the stylesheet as css/chart.css?v=<date>. Change that date whenever chart.css changes; otherwise people who have signed in before keep the old styles next to the new templates.

The code step is the for-keycloak email OTP authenticator (Unlicense), committed as infra/keycloak/providers/email-otp-authenticator-v1.8.1-kc-26.6.4.jar (SHA-256 8013758fe4f24dfb561d57f83c0853387fb18c9b35925c77fb60ccd9af7cedea). infra/keycloak/Dockerfile builds it, the theme and the realm seed into the chart-keycloak image that deployments run (pre-built, so Keycloak starts in seconds), and the sync script into chart-keycloak-config. To upgrade Keycloak, change KEYCLOAK_VERSION there and replace the jar with the release built for that version.

How long you stay signed in

Once signed in, you stay signed in for up to 30 days, whether or not you use CHART in that time: there is no sign-out after inactivity. The browser keeps the refresh token in an httpOnly cookie and renews the short-lived access token in the background, including when a tab wakes from sleep. You are asked to sign in again after 30 days, after signing out (which ends every tab), or when an administrator disables your access. The 30 days are Keycloak's session idle and maximum lifetimes, applied to the realm on every deploy by infra/keycloak/sync-realm.js.

Email settings

Any SMTP service works; changing provider only changes these settings. In production they go in ~/chart-deploy/aws/.env.prod. The deploy stops before changing anything if SMTP_HOST or SMTP_FROM is missing, because without mail nobody could sign in.

Setting Meaning Default
SMTP_HOST SMTP server required
SMTP_PORT Port 587
SMTP_SECURITY starttls, ssl or none (local Mailpit only) starttls
SMTP_USERNAME, SMTP_PASSWORD Credentials, set together none
SMTP_FROM Sender address, on a domain you have verified required
SMTP_FROM_NAME Sender name CHART
SMTP_REPLY_TO Reply-to address none
SIGN_IN_CODE_LIMIT Codes per person per 15 minutes (0 turns the cap off) 5
SMTP_HOST=email-smtp.eu-north-1.amazonaws.com
SMTP_PORT=587
SMTP_USERNAME=<SES SMTP username>
SMTP_PASSWORD=<SES SMTP password>
SMTP_FROM=no-reply@chartforclimateaction.org
  1. In SES (same region as the server), create a domain identity for chartforclimateaction.org. With the domain in Route 53, SES adds the three DKIM records for you.
  2. Set a custom MAIL FROM domain, mail.chartforclimateaction.org, and add the MX and SPF records SES shows.
  3. Add DMARC: TXT _dmarc = v=DMARC1; p=none; rua=mailto:<a monitored inbox>. Tighten to p=quarantine once reports look clean.
  4. Request production access. A sandboxed SES account only delivers to verified addresses.
  5. Create SMTP credentials (SES → SMTP settings). They are not your AWS access keys.

Other providers

The same settings work with any SMTP service, for example:

Provider SMTP_HOST SMTP_PORT Username
Resend smtp.resend.com 587 resend (password: API key)
Postmark smtp.postmarkapp.com 587 server token (password: same)
Google Workspace SMTP relay smtp-relay.gmail.com 587 per relay settings

Verify the sending domain with the provider and publish its SPF and DKIM records, or codes will land in spam. Running your own mail server is not recommended: AWS blocks outbound port 25 by default and a new server IP has no sending reputation.

Local development and E2E

make identity-sync points Keycloak at Mailpit with no credentials. Read the codes at http://127.0.0.1:8025 (also through the remote-dev tunnel). The live E2E suite (make e2e-outlook) runs its own Mailpit and reads each code through Mailpit's API, so browser tests sign in exactly as people do.

Test the email settings

After a deploy (or make identity-sync), send a test message from Keycloak: admin console (/identity in production, http://127.0.0.1:8080 locally) → realm chart → Realm settings → Email → Test connection. The test goes to the signed-in Keycloak administrator's email address, so give that account an address first. Then sign in to CHART with a real account and check the code arrives within a minute and is not in spam.

Inviting people

Anyone with people write in a workspace invites in Settings → People: full name, email, one or more grants (a role at a place; a grant covers the place and everything below it), and departments, adding a missing department on the way if they may. Nobody can grant a role higher than their own at a place.

  1. CHART records the invitation (POST /workspaces/{id}/invitations) and makes a Keycloak account with no password if there is none.
  2. Keycloak emails You are invited to CHART through the email settings above. The invitation lasts 7 days.
  3. The link opens Accept your CHART invitation; accepting confirms the address and offers Go to CHART login.
  4. They sign in with their email address and a code. That first sign-in accepts the invitation, and they land on their place's dashboard.

Someone who already uses CHART (in another workspace) gets the access at once, with no email. If the email could not be sent, the invitation still stands and Settings says so; Resend emails it again and extends it, and Revoke withdraws a pending one. Someone who signs in without an invitation holds nothing. The emails use CHART's layout and wording: the chart email theme in infra/keycloak/themes/chart/email/.

Changing access

  • People manage changes a member's grants and departments (Edit access), or disables them in the workspace. Both apply on the member's next request; disabling their last membership also ends their Keycloak sessions.
  • The Keycloak administration console (/identity/admin) is for operators, not everyday work. Its sign-in, headed CHART admin, also uses CHART's look; the user is admin and the password is KEYCLOAK_ADMIN_PASSWORD from .env.prod. That is Keycloak's own administrator, a different account from CHART's admin. Roles and groups set there are ignored.
  • If the only platform admin is locked out, re-enable them from an operator shell. This also restores their platform-admin flag in CHART's database. They then sign in with a code as usual:
chart-admin-recover --username <name> --email <address> --confirm <name>

Troubleshooting

  • No code arrives: check spam, then the Keycloak log (docker logs chart-keycloak) for SMTP errors, and the provider's sending dashboard. SES in sandbox mode drops mail to unverified addresses.
  • "Too many codes have been requested": the person hit SIGN_IN_CODE_LIMIT; it clears within 15 minutes.
  • The deploy stops at "set SMTP_HOST in .env.prod": add the email settings above to .env.prod.