Sign-in and identity

What is available

Method	Status	Where credentials live
Email and password	Available	Your Postgres
Passkeys	Available	Your Postgres holds the public key. The private key never leaves the user's device
Multi-factor authentication	Available, and required during onboarding	Your Postgres
Password reset by email	Available when SMTP is configured	Your mail server sends the link
Microsoft Entra ID	**In development, not supported at the moment **

Nothing outside your cluster is involved in sign-in. Accounts, password hashes, passkeys and sessions are all in your own database. If you configure SMTP, invitation and password-reset emails go out through your mail server.

Single sign-on is not available yet

Microsoft Entra ID is in development. No generic OIDC provider, no SAML and no LDAP integration exists either.

If single sign-on is a requirement for you, tell us which provider, because that shapes what ships first.

The first account

Registration is invite-only and invites need an existing member, so a fresh install seeds one account with a published password. Signing in, completing onboarding and changing that password is a required install step, not an optional one.

See First sign-in.

The published address decides whether sign-in works

The dashboard derives its sign-in base URL from its own address, services.ui.ingress.hosts[0].host. If that does not match the address people actually type in the browser, every sign-in is rejected as an invalid origin.

Two rules:

1. Use the address people type. Not an internal service name, not a load balancer's own hostname.
2. Use the scheme people type. The ingress overlay sets externalScheme: https, which is right whenever they browse over HTTPS, wherever TLS terminates. Only for plain HTTP, set it to http:

--set externalScheme=http

See Add the certificate.

Passkeys

Users can register with a passkey instead of a password, and add, rename or remove passkeys under Profile. Signing in with a passkey does not ask for the authenticator-app code: the passkey's own PIN or biometric check stands in for it. Enrolling multi-factor is still required during onboarding.

A passkey is bound to the host name the dashboard is published on, taken from its sign-in URL. So:

• They need HTTPS and a DNS name. A plain-HTTP address or a bare IP cannot register one.
• Changing the dashboard's address makes every registered passkey stop working. That is services.ui.ingress.hosts[0].host. Users then sign in with a password, or register a new passkey on the new address.
• A user who registered with a passkey only has no password to fall back on. Ask them to set one under Profile, especially when SMTP is not configured and nobody can reset it by email.

Invitations and email

Invitations grant one or more workspaces, each with a role no higher than the inviter's own. Pending invitations are listed on the Team tab, where they can be revoked. A link expires after seven days, and inviting the same address again replaces the previous link.

With SMTP configured, the invitation is emailed and users can reset a forgotten password. Without it, the dashboard shows the invitation link for you to copy and send yourself, and the sign-in page offers no password reset.

SMTP is configured through the dashboard's environment, under services.ui in your overrides file. HOST_EMAIL is the only setting you need. Setting it turns email on.

my-overrides.yaml

services:
  ui:
    env:
      HOST_EMAIL: smtp.internal.example
      HOST_PORT: "25"

That is enough for a relay that accepts mail without a login, which is typical for an internal relay on port 25. If your relay needs a login, put it in a Secret first:

kubectl -n gen0sec create secret generic gen0sec-ui-smtp \
  --from-literal=HOST_AUTH_USER='<smtp-user>' --from-literal=HOST_AUTH_PASS='<smtp-password>'

Then reference it from the same file:

my-overrides.yaml

services:
  ui:
    env:
      HOST_EMAIL: smtp.example.com
      HOST_PORT: "587"
    envSecrets:
      HOST_AUTH_USER: { name: gen0sec-ui-smtp }
      HOST_AUTH_PASS: { name: gen0sec-ui-smtp }

Variable	Default	Notes
HOST_EMAIL	Unset, so no email	The SMTP server's host name
HOST_PORT	587	465 uses TLS from the start. Any other port upgrades to TLS when the server offers it
HOST_AUTH_USER, HOST_AUTH_PASS	Unset, so no login	Only for a relay that needs one. Keep them in the Secret above
HOST_ALIAS_EMAIL	HOST_AUTH_USER if it is an email address, otherwise no-reply@ and the dashboard's host	The sender address. Set it when your relay accepts only senders from certain domains
HOST_APP_URL	The dashboard's sign-in URL	The start of the links in emails. Leave it unset unless people reach the dashboard on another address

Emails come from Gen0Sec, at the sender address above.

The mail server's certificate must verify. Whenever the connection uses TLS, the dashboard checks the server's certificate. If it was issued by your own CA, the dashboard cannot verify it and the email is not sent. Use a relay with a publicly trusted certificate, or one that offers no TLS on an internal port.

Pass the file to every later helm upgrade as well. The dashboard's outbound connection to your mail server is listed on Ports and egress.

Sessions

The signing secret lives in g0s-db-ui, created with all the other database secrets in Install step 6.

Action	Effect on sessions
Re-running make-db-secrets.sh	None. The existing signing secret is preserved deliberately
Rotating the signing secret	Every session ends and every outstanding invite link stops working. Passwords and passkeys are unaffected
Changing the dashboard's address	Registered passkeys stop working
Upgrading	None. Upgrading from v0.1.x to v0.2.0 invalidates invite links issued before the upgrade

Turning the dashboard off entirely

If your operators use the API only:

--set services.ui.enabled=false

The agent-facing APIs are unaffected. Note that agent API keys are issued through the dashboard, so turn it off only once you have the keys you need.

If it fails

Symptom	Cause
Sign-in rejected as an invalid origin	The published host does not match the address typed, or the scheme is wrong. See above
Sessions drop after a re-run of the secret script	The signing secret changed. It should not; check whether the secret was deleted first
Every sign-in fails after an upgrade	Check that externalScheme and the host survived the upgrade. helm get values g0s -n gen0sec
The passkey prompt fails or offers no passkey	The address typed differs from the dashboard's address, the page is plain HTTP, or the host changed after the passkey was registered
Emailed links point at the wrong address	HOST_APP_URL is set to an old address. Remove it so links follow the dashboard
Invitations show a link instead of being emailed	SMTP is not configured, or sending failed. kubectl -n gen0sec logs deploy/g0s-ui | grep -i 'failed to send' shows why
Sending fails with a certificate error	The mail server's certificate comes from your own CA. See above
The relay rejects the sender	Set HOST_ALIAS_EMAIL to an address on a domain the relay accepts