# Choose the dev-box sign-in provider

Local Keycloak is the default (`AAI_MODE=local`). It provides the dev box's test
users. External mode uses existing registrations at a hosted AAI for Themelio,
Waldur and GitLab. Ask the AAI administrator to register all three clients before
switching. No administrator password for the hosted AAI is required.

## Pharos DX

1. Open **Dev box → Sign-in provider** and enable **Use external AAI**.
2. Enter the **realm issuer**, for example
   `https://staging.aai.pharos.grnet.gr/auth/realms/pharos`.
   Remove `/protocol/openid-connect/auth` from an authorisation URL.
3. Choose a private JSON file and click **Create private template**. Fill its
   client IDs and secrets using your editor. The app never reads the secrets into
   its webview. On Windows, use a file path inside the selected WSL distribution.
4. Click **Check external AAI**, then **Save sign-in settings**. The saved `.env`
   contains only the mode, issuer and private file path.
5. Hand back any services running locally, then use **Compatibility → Deploy this
   commit**. For a new VM, continue with **Check dev box → Set up dev box**.

To return to local Keycloak, disable the switch, save and deploy again. Its existing
users, database and passwords are retained. Sign out of existing browser sessions
when changing provider: changing configuration does not revoke already-issued
application sessions or migrate accounts between providers.
Return to local mode and deploy it before using a checkout from before provider
selection; those older tools understand only the local-provider record format.

## Make commands

Create the private template from the repository root:

```sh
make aai-template
```

By default it is `.local/local-aai/<TARGET>/external.json` (or
`.local/aai/external.json` until a target is selected). The file is created with
mode `0600`; an existing file is preserved. Keep it ignored by Git, owned by your
user, and free of symbolic or hard links. Fill in these bindings:

```json
{
  "clients": {
    "pharos-control-plane": {"client_id": "REPLACE_CLIENT_ID", "client_secret": "REPLACE_CLIENT_SECRET"},
    "pharos-tools": {"client_id": "REPLACE_CLIENT_ID", "client_secret": "REPLACE_CLIENT_SECRET"},
    "pharos-gitlab": {"client_id": "REPLACE_CLIENT_ID", "client_secret": "REPLACE_CLIENT_SECRET"}
  }
}
```

The names on the left identify the local consumers: Themelio, Waldur and GitLab,
respectively. The registered IDs on the right may be different. Set the following
**non-secret** values in `.env`, using your target's actual private file path:

```dotenv
AAI_MODE=external
AAI_ISSUER=https://staging.aai.pharos.grnet.gr/auth/realms/pharos
AAI_CREDENTIALS_FILE=.local/local-aai/dev-yourname/external.json
```

Then run:

```sh
make aai-check
make handback
make reconcile
```

`make aai-show` prints only those three settings. `make aai-save AAI_MODE=local`
saves the default provider again; follow it with `make reconcile`. First-time
installations can use `make devbox-setup` with either provider.

## Registration and trust requirements

Use separate confidential OIDC clients with authorisation-code flow and PKCE S256.
Register these callbacks for the standard dev-box URLs:

| Consumer | Callback |
|---|---|
| Themelio | `https://themelio.localtest.me/api/auth/callback/openid_connect` |
| Waldur | `https://waldur.localtest.me/api-auth/keycloak/complete/` |
| GitLab | `https://gitlab.localtest.me/users/auth/openid_connect/callback` |

Use the actual browser origin if your deployment changes it. Register Waldur's
`/login/` as a post-logout redirect. Themelio also requires the Pharos identity
scopes and claims documented in [the client registry](../../../devops/aai/clients.json).
External AAI must provide them; this switch does not install the local mapper or
change hosted realm policy. Account linking and user authorisation remain owned
by the applications.

Discovery must advertise the exact HTTPS issuer, HTTPS endpoints on the same
origin and PKCE S256. The workstation and dev box must both reach that issuer.
Publicly trusted certificates use system trust. For a private CA, add an optional
`ca_certificate` containing **public PEM certificates only** to the JSON file.
Discovery checks do not validate a client secret or prove browser login; test all
three sign-in flows after deployment.

Icarus is a separate laboratory. External mode exports its issuer/audience only
when the private file includes `"resources": {"pharos-icarus": "registered-audience"}`.
Its token-exchange and custom-claim behaviour needs separate provider qualification.

Credentials travel over authenticated SSH input into private runner state, then
into the named Kubernetes Secret bindings. They are excluded from `.env`, process
arguments, progress events and logs. The runner remains a trusted deployment
administrator. Kubernetes Secrets and the private runner file are recoverable
plaintext for that administrator. The password catalogue labels retained local
Keycloak accounts explicitly; hosted AAI passwords are managed by its operator.

After rotating a client secret in the private file, run `make reconcile` at the
same commit. The changed credentials trigger reconciliation and reuse the
runner's verified source without creating another Git bundle. Invalid or
incomplete private input leaves the previous credentials in place and stops
delivery.