> ## Documentation Index
> Fetch the complete documentation index at: https://starforge.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication and Accounts

> Local accounts, OIDC single sign-on, Google / GitHub / Hugging Face sign-in, and the platform's token system

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
sf admin user-add alice
sf login --server https://starforge.your-company.com
```

Three ways in, and a deployment can run any combination of them.

**Local accounts** work with no configuration: an administrator creates them, users sign in with a
username and password. On a fresh deployment the first administrator is created through the
console's first-visit onboarding.

**OIDC single sign-on** is turned on by setting `FORGE_OIDC_ISSUER`, `FORGE_OIDC_CLIENT_ID` and
`FORGE_OIDC_CLIENT_SECRET` — Casdoor, Keycloak and anything else that speaks OIDC. The CLI's browser
and device-code logins follow the same flow without extra configuration.

**Google, GitHub and Hugging Face** are configured from the admin settings page and take effect
without a restart. Read the warning below before turning one on: with no allow-list, anyone with an
account at that provider can create one here.

Check which a deployment offers before assuming:

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
curl https://starforge.your-company.com/api/auth/config
```

## Two account systems

<Tabs>
  <Tab title="Local accounts">
    Works out of the box: admins create accounts with `sf admin user-add`, and users log in with username and password. On a fresh deployment, the first administrator is created via the console's first-visit onboarding (`/api/auth/setup`).
  </Tab>

  <Tab title="OIDC single sign-on">
    Configure `FORGE_OIDC_*` (Issuer / Client ID / Secret) to integrate IdPs such as Casdoor and Keycloak. The CLI's browser and device-code logins automatically follow the OIDC flow.
  </Tab>
</Tabs>

Two role levels: **admin** (governance and full visibility) and **operator** (own projects and jobs).

## Google, GitHub and Hugging Face sign-in

Configured from **Settings → Access → Google / GitHub / Hugging Face sign-in**, not from the
environment, and live the moment you save — the button appears on the login page with no restart.
Nothing is offered until a provider has both its client ID and its secret.

Google is genuine OIDC and is discovered from `accounts.google.com`. GitHub is **not** OIDC: it
publishes no discovery document and issues no ID token, so identity comes from its REST API, and an
account whose address is private is read from `/user/emails`. Hugging Face is OIDC-shaped with
fixed endpoints, and its sign-in asks only for identity scopes — separate from the account binding
that pulls gated repositories.

Register these redirect URIs, one per provider:

| Provider     | Redirect URI                                                  |
| ------------ | ------------------------------------------------------------- |
| Google       | `https://<your console>/api/auth/social/google/callback`      |
| GitHub       | `https://<your console>/api/auth/social/github/callback`      |
| Hugging Face | `https://<your console>/api/auth/social/huggingface/callback` |

<Warning>
  **An empty allow-list means anyone.** With no `google_allowed_domains`, any Google account on
  earth can create an account on a console reachable from the internet; the same goes for
  `github_allowed_orgs`. Set them, or keep the console off the public internet. New accounts get
  the role in `oidc_default_role`.
</Warning>

CLI and device-code logins work through these providers too, so `sf login` needs no separate
configuration.

**Google One Tap** is off by default and switched on separately, because the prompt appears without
the visitor asking for it. While it is off, Google's script is never loaded and the endpoints behind
it are closed. The prompt and the button end in the same session, so a visitor who dismisses it
loses nothing.

One Tap is the only sign-in path where the browser hands the console a token instead of the console
fetching one, so it carries two checks the redirect flows do not need: the credential's signature is
verified against Google's published keys and must name this console's own client ID, and it must
carry a single-use nonce this console issued. Without the nonce a credential that leaked anywhere
within its hour of validity could be exchanged for a session.

## Token system

The platform issues **domain-isolated** tokens per purpose — no token can impersonate another kind:

| Token            | Issued to          | Purpose and boundaries                                                                    |
| ---------------- | ------------------ | ----------------------------------------------------------------------------------------- |
| Web session      | Browser            | Cookie session; with Redis, logout revokes instantly                                      |
| CLI access token | `sf login`         | API calls; stored in `~/.forge/` (0600)                                                   |
| Ingest token     | Training container | Ingest endpoints only, bound to a single run, limited validity; rejected by the web guard |
| MCP OAuth        | AI Agent           | OAuth 2.1 + PKCE, per-tool authorization                                                  |
| Share snapshot   | Read-only link     | Scoped to a single snapshot                                                               |

## Security baseline

* `FORGE_WEB_JWT_SECRET` must be set to a fixed strong random string (identical across replicas);
* Configure `FORGE_REDIS_URL` in production: instant token revocation on logout / ban, distributed rate limiting;
* Cluster and storage credentials stay server-side only; the job side sees only presigned URLs and run-scoped ingest tokens;
* CLI packaging has a sensitive-file blocklist (`.env`, `*.pem`, `id_rsa*`…), so secrets never end up inside job packages;
* All sensitive operations enter the [audit trail](/en/console/admin).

<Warning>
  `FORGE_NO_AUTH=1` is for local development only: it skips all authentication and makes everyone admin. Never enable it in any multi-user environment.
</Warning>