Google OAuth setup
Each self-hoster creates their own Google OAuth client, once. Portunus uses it to sign you in and to read and write its vault file in your Drive.
Steps
- In the Google Cloud Console, create a project and enable the Google Drive API.
- Go to APIs & Services → OAuth consent screen and configure it. External is fine for personal use; add yourself as a test user.
- Go to Credentials → Create OAuth client ID and choose Web application.
- Add the authorized redirect URIs:
http://localhost:3000/api/auth/callback/googlefor local usehttps://your-domain/api/auth/callback/googlewhen deployed
- Copy the client ID and secret into your environment as
AUTH_GOOGLE_IDandAUTH_GOOGLE_SECRET(see Configuration).
The redirect URI's origin must match AUTH_URL. If you serve Portunus at https://vault.example.com, the redirect URI is https://vault.example.com/api/auth/callback/google.
What Portunus asks Google for
The app requests only the drive.file scope (https://www.googleapis.com/auth/drive.file). With it, Portunus can see only the files it created, never the rest of your Drive. The vault is stored as portunus.vault.json in a Portunus Application folder.
A compromised Portunus server can't silently widen that scope. Broadening it would send you back through Google's consent screen.
Troubleshooting
redirect_uri_mismatch: the redirect URI registered in step 4 doesn't exactly matchAUTH_URL+/api/auth/callback/google. Check the scheme (httpvshttps), host, and port.- "Access blocked" / app not verified: while the consent screen is in testing, only the test users you added in step 2 can sign in.
- No Google account handy? Use demo mode to try the UI without one.
