# Reconfigure

> Reconfiguring Forseti

- Skill: `franzos/reconfigure` (Agent Skill)
- Install (CLI): `npx skillmds@latest add franzos/reconfigure`
- Raw SKILL.md: https://api.skillmd.com/api/skills/franzos/reconfigure/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: franzos (https://skillmd.com/u/franzos)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/franzos/reconfigure

---


# Reconfiguring Forseti

Reconfiguration is goal-driven: what does the user want to achieve? The right change lives in different places (Forseti's `config.toml`, Kratos's `kratos.yml`, Hydra, or the admin UI). Read the relevant `docs/operator-guide.md` section for the current detail rather than working from memory, and validate before declaring done.

## 1. Establish the goal and the current state

Ask what the user wants to achieve if it is not already clear. Then locate the deployment: the active `config.toml` (`$FORSETI_CONFIG_PATH`), `infra/kratos/kratos.yml`, `infra/hydra/hydra.yml`, and how the stack is run (playground compose vs native). Note whether TLS/proxy is in front (it affects callback URLs).

## 2. Dispatch by goal

### Add a social login provider (GitHub, Google, Microsoft, GitLab, Apple, custom OIDC)

Configured in **Kratos**, not Forseti. In `kratos.yml` under `selfservice.methods.oidc.config.providers[]`, add an entry: `id`, `provider`, `client_id`, `client_secret` (via `${ENV}` substitution, not inline), `mapper_url`, and `scope`. Provide the claim-to-trait mapper as a Jsonnet file under `infra/kratos/` (e.g. `oidc.github.jsonnet`). At the IdP, register the callback as `https://<kratos-host>/self-service/methods/oidc/callback/<id>`. Forseti auto-renders one "Sign in with X" button per provider (known: github, google, microsoft, gitlab, apple, facebook; unknown ids get a generic icon). See operator-guide §oidc.

### Enable Linux / POSIX login

Forseti-native, via the OAuth Device Authorization Grant. Set the `[posix]` table in `config.toml` (uid/gid bands, `default_shell`, `home_prefix`, `free_seats`, `pam_client_id`/`pam_client_secret`, `hydra_issuer`). Mint the confidential Hydra device-auth client with `forseti posix-init-client`. Enroll the host at `/admin/hosts` (one-time `host_id:secret`), provision Kratos identities into POSIX accounts at `/admin/posix`, and install the `forseti-unix` host client (NSS + PAM + sshd `AuthorizedKeysCommand` + daemon; also packaged for Guix). Offline passphrase fallback is `/settings/offline-access`. Free up to `free_seats` (default 25); more needs a commercial license.

### Register a downstream OAuth client

Use the admin UI: `/admin/clients/new` (40+ prefilled app templates), or issue a DCR initial-access token at `/admin/dcr-tokens` for RFC 7591 self-registration. Harden with the `[oauth].dcr_reserved_names` denylist to block brand impersonation on the consent screen.

### Enable or switch the email provider

Set `[email]` in `config.toml`: `enabled`, `from_address`, `from_name`, `provider`, and the provider credentials (prefer env over inline). Kratos's courier SMTP is separate and lives in `kratos.yml`.

### Enable Enterprise SAML SSO (commercial)

Set `[saml]` in `config.toml` to point at a Jackson/Ory Polis instance (URL, API key, verifier, SP entity id); per-org connections are managed at `/sso/{org-slug}`. See `docs/commercial/saml.md`.

### Branding, rate limits, other subsystems

`[brand]`, `[auth]`/`[oauth]`/`[orgs]`/`[claim_email]`/`[handoff]` rate limits and TTLs are all in `config.toml`.

## 3. Validate and test

- Lint the Ory side: `forseti config-check` (`--strict`).
- Restart what changed: Kratos for `kratos.yml` edits, Forseti for `config.toml` edits (some values are hot, most are read at boot).
- Exercise the changed flow end to end in a browser (the new provider button, a POSIX login, the downstream authorize round-trip). Do not report the change as working without loading it.

For a full hardening pass rather than a single change, use the `forseti:audit` skill.