Add provider-neutral Google authentication

2026-07-20 21:42:56 -05:00
parent 48e19f138e
commit 72fd1e3e0f
20 changed files with 1084 additions and 36 deletions
@@ -0,0 +1,34 @@
+# External Authentication
+
+RanaZe supports provider-neutral external identities. Users can sign in with a configured provider or connect it from Profile. Every account remains password-backed, and an external identity is never linked automatically by matching email addresses.
+
+## Google setup
+
+Create separate Google OAuth 2.0 Web application clients for UAT and production. Configure these exact authorized redirect URIs:
+
+- UAT: `https://us3q.ranaze.com/api/Auth/external/google/callback`
+- Production: `https://s3q.ranaze.com/api/Auth/external/google/callback`
+
+Add the credentials as Gitea repository secrets:
+
+- `UAT_GOOGLE_CLIENT_ID`
+- `UAT_GOOGLE_CLIENT_SECRET`
+- `PRD_GOOGLE_CLIENT_ID`
+- `PRD_GOOGLE_CLIENT_SECRET`
+
+The deployment scripts treat Google as optional. If either credential is absent, Google is omitted from the API provider list and the client does not display its button.
+
+## Account-linking rules
+
+- A provider subject can belong to only one RanaZe user.
+- A RanaZe user can connect at most one identity per provider.
+- A verified Google email that already exists requires the user to choose **Link an existing RanaZe account** and enter that account's password.
+- Connected providers are intentionally not removable in the current UI to prevent accidental lockout and identity takeover edge cases.
+- Legacy `Users.SteamId` values are backfilled into `ExternalIdentities`; new Steam links are dual-written during the compatibility period.
+
+## Collections
+
+- `ExternalIdentities` stores durable provider-to-user mappings.
+- `ExternalAuthTransactions` stores short-lived login/link state and has a TTL index.
+
+Deleting a user purges both collections for that user.