Clients

README.md

@@ -22,10 +22,49 @@ Ansible Vault-encrypted vars file:
 - `openldap_readonly_password`: existing LDAP search-account password.
 - `matrix_dex_oidc_client_id` and `matrix_dex_oidc_client_secret`: existing MAS client.
 - `postgresql_admin_password`: needed only if deliberately enabling DB management.
-- Optional `www_dex_client_secret`: enables the website client and its separate
-   `www-ldap`/`entryUUID` connector, without changing legacy identities. It must
-   match the website's `DEX_CLIENT_SECRET`. Leave absent to preserve Matrix-only
-   behavior. Review and declare any other deployed clients before rollout.
+- `www_dex_client_secret`: matches the website's `DEX_CLIENT_SECRET`.
+- `gitea_dex_client_secret`, `discourse_dex_client_secret`,
+   `peertube_dex_client_secret`, `mastodon_dex_client_secret`, and
+   `nextcloud_dex_client_secret`: one distinct confidential-client secret per app.
+
+The site playbook now registers all seven clients explicitly in
+`dex_static_clients` and disables the Matrix convenience client to avoid a
+duplicate. None of these secrets is optional unless you deliberately remove its
+client from your inventory/playbook. Existing secrets must be preserved, not
+regenerated on each deploy. No real secrets are included in source control.
+
+### Application configuration required after client registration
+
+All applications use issuer **https://dex.eom.dev/** and discovery document
+**https://dex.eom.dev/.well-known/openid-configuration**, with `openid profile
+email` scopes (and `groups` only when used). Configure the matching ID/secret in
+each service. Client creation in Dex **does not enable SSO in the application**.
+
+| Application | Client ID | Exact callback / prerequisite |
+| --- | --- | --- |
+| Matrix Auth Service | Existing `matrix_dex_oidc_client_id` | Original `https://mas.eom.dev/upstream/callback/01K96AQEZKKABW34PY3R6BVNJ4` retained |
+| www | `www-membership` | `https://www.eom.dev/members/oidc/callback/` |
+| Gitea | `gitea` | `https://gitea.eom.dev/user/oauth2/dex/callback`; add OpenID Connect authentication source named **dex** |
+| Discourse | `discourse` | `https://discourse.eom.dev/auth/oidc/callback`; enable discourse-openid-connect and confirm callback for your installed plugin version |
+| PeerTube | `peertube` | `https://peertube.eom.dev/plugins/auth-openid-connect/router/code-cb`; install/configure official auth-openid-connect plugin |
+| Mastodon | `mastodon` | `https://mastodon.eom.dev/auth/auth/openid_connect/callback`; retained from its configured OIDC_REDIRECT_URI; verify installed OIDC implementation supports that route |
+| Nextcloud | `nextcloud` | `https://nextcloud.eom.dev/index.php/apps/user_oidc/code`; install **user_oidc**, not the OIDC provider app or oidc_login |
+
+Callback paths are not interchangeable. Gitea's source name affects its URL;
+Nextcloud's admin screen supplies the exact callback, which can omit index.php
+when URL rewriting is enabled. If using **oidc_login** instead, explicitly replace
+the callback with its `/apps/oidc_login/oidc` route rather than enabling both by
+guesswork. The existing Mastodon deployment points to Google; changing it to Dex
+is a separate app-side migration, not another set of automatically active OIDC
+environment variables. Keep a tested administrator fallback and avoid automatic
+email-only account linking when migrating existing users.
+
+The website's `www-ldap` connector uses entryUUID while the legacy `ldap`
+connector uses uid. Those produce different subjects for the same directory
+entry: do not switch existing accounts between connectors without an explicit
+linking/migration plan. The legacy connector still filters for Dex Users; merely
+registering an application does not bypass this restriction or grant paid room
+access. Each relying application must implement its own authorization policy.
 
 Run the playbook on the controller with its kubeconfig and this role available
 in `ANSIBLE_ROLES_PATH`. Load your encrypted variables with Ansible's `--extra-vars`
@@ -70,8 +109,8 @@ The site playbook maps legacy inventory variables explicitly:
 | `openldap_readonly_password` | `dex_ldap_bind_password` |
 | `matrix_dex_oidc_client_id` / `matrix_dex_oidc_client_secret` | Existing Matrix Auth Service client |
 
-The site playbook enables the existing Matrix client. Its original
-redirect URI is explicit in `dex_matrix_redirect_uris`; override to match your
+The site playbook explicitly includes the existing Matrix client. Its original
+redirect URI is explicit in `dex_static_clients`; override to match your
 actual MAS configuration. Other clients previously added directly to Helm must
 be declared in `dex_static_clients` before running this role. Helm values are
 reset to this role's complete values: undeclared manual Helm customizations are