blocks-frontend-local-https

name

blocks-frontend-local-https

description

Run a frontend React app locally over HTTPS on its real project domain, using a locally-generated SSL certificate — required so SELISE Blocks SSO/OIDC login works, because the auth callback sets a Secure, domain-scoped session cookie that the browser rejects on plain http://localhost. The skill: discovers the project's domain from /os/v4/Project/Gets (projects[].applications[].domain, filtered by environment) or asks the user, adds a hosts entry mapping that domain to 127.0.0.1, generates a self-signed local cert for it with openssl (and trusts it), configures the dev server (Vite/CRA/Next) to serve https on that domain + port, and runs it at https://your.domain.com:PORT. Use whenever the user needs to run/test a Blocks app locally over HTTPS, fix 'SSO cookie not set / session lost on localhost', set up a local dev cert, serve a custom domain locally, or make the OIDC redirect work in local dev. A real/owned domain name is required to issue the cert — you cannot make one without a domain.

Blocks Frontend — Local HTTPS on the Project Domain

Blocks SSO/OIDC (blocks-iam-sso-oidc-implementation) finishes by having /iam/v4/idp/callback set a Secure, domain-scoped session cookie. Browsers refuse to store that cookie on http://localhost, and they scope it to the project's cookie domain — so to test login locally the app must run on HTTPS at the project's real domain, not localhost. This skill makes that work: generate a trusted local cert for the domain, point the domain at your machine, and serve the dev server over HTTPS on it.

Pure local tooling — the only Blocks API call is the optional Project/Gets lookup to discover the domain.

The domain is the crux

You need a domain name to issue the certificate against and to run on — localhost won't do, because the cookie is scoped to the project's domain. Resolve the domain before generating the cert, in this order (never guess one):

1. From Project/Gets first — response is an array of tenant-groups; each has a projects array. Pick the project (and environment — ask if more than one applies). The applicationDomain lives in projects[].applications[].domain (often https://dfsgso.slsblx.com), not on the project object directly. One application → use its domain; multiple → ask the user which to pick. Strip https:// for the hostname used in hosts/cert/dev-server.
2. Only if none is found, ask the user. It must match the OIDC redirectUri origin, or login still fails.

You are not taking the real domain over the internet — you map it to 127.0.0.1 in your hosts file, so https://myapp.seliseblocks.com:5173 resolves to your local dev server while every other machine still reaches the real site.

Steps → flows/setup-local-https.md

1. Determine the domain (Project/Gets or ask).
2. Add a hosts entry: 127.0.0.1 <domain>.
3. Generate a self-signed cert for <domain> with openssl, and trust it so the browser stops warning.
4. Configure the dev server to serve HTTPS on <domain>:<port> with that cert — references/vite-config.md.
5. Run → open https://<domain>:<port>.
6. Use that exact origin as the OIDC redirectUri everywhere.

Tool: openssl

Use openssl (preinstalled on macOS/Linux, and in Git Bash on Windows) to issue a self-signed certificate for the domain. It's self-signed, so the browser shows a one-time "not private" warning until you either click through it (fine for local dev) or trust the cert in the OS store to make the warning disappear — both covered in flows/setup-local-https.md step 3. Include the exact domain in the cert's subjectAltName, or the browser rejects it even over HTTPS.

Gotchas

• Domain must match the cookie/redirect config. A cert for the wrong domain runs HTTPS fine but SSO still fails — the cookie won't be scoped to where you're browsing. Match cookieDomain / the registered redirectUri.
• Point the API base URL at the same registrable domain, or the session cookie won't store. The same same-site rule that forces HTTPS-on-the-real-domain locally also governs which API host the app calls: the Blocks session cookie is only kept when API requests go to a host under the app's registrable domain. Default https://api.seliseblocks.com is right only for *.seliseblocks.com apps; on a custom domain set VITE_BLOCKS_API_URL=https://blocksapi.<your-registrable-domain> (app abc.slsblx.com → https://blocksapi.slsblx.com; app xyz.blx10.com → https://blocksapi.blx10.com). Ask the user which base URL to use. See blocks-iam-sso-oidc-implementation.
• Hosts entry is required — without 127.0.0.1 <domain>, the browser resolves the real public IP instead of your dev server.
• The domain must be in the cert's subjectAltName (SAN) — a matching CN alone isn't enough for modern browsers.
• Port is part of the origin, not the cookie domain — https://myapp.seliseblocks.com:5173 shares the cookie domain myapp.seliseblocks.com, so Secure cookies set for that domain apply. Register the port-bearing origin as the redirectUri.
• Certs are per-machine, never committed — add the cert directory to .gitignore.
• Restart the browser after trusting the cert so the new trust is picked up.