# Google OAuth Setup Guide This guide provides detailed instructions for setting up Google OAuth authentication in TomoTree. --- ## Requirements - **Streamlit version 1.42 or higher** (with built-in OAuth support) - A **Google Cloud project** with OAuth 2.0 credentials - Access to the **TomoTree configuration** files --- ## Step 1: Create a Google Cloud Project ### 1a. Go to Google Cloud Console Open [https://console.cloud.google.com/](https://console.cloud.google.com/) and sign in with your Google account. ### 1b. Create a new project 1. Click the project dropdown at the top 2. Click **NEW PROJECT** 3. Enter a project name (e.g., `TomoTree`) 4. Click **CREATE** ### 1c. No API needs to be enabled Sign-in uses Google's OpenID Connect endpoint, which is available to every project. (The old *Google+ API* has been shut down and is not needed.) --- ## Step 2: Create OAuth 2.0 Credentials ### 2a. Create OAuth 2.0 Credentials 1. Go to **APIs & Services** → **Credentials** 2. Click **+ CREATE CREDENTIALS** → **OAuth 2.0 Client IDs** 3. If prompted to configure the OAuth consent screen: - Choose **User type: External** - Click **CREATE** - Fill in the form with your app details: - **App name**: TomoTree - **User support email**: (your email) - **Developer contact**: (your email) - Click **SAVE AND CONTINUE** through all screens - Add scopes as needed (default is usually fine) - Click **SAVE AND CONTINUE** again ### 2b. Create the OAuth 2.0 Client ID 1. Return to **Credentials** page 2. Click **+ CREATE CREDENTIALS** → **OAuth 2.0 Client IDs** 3. Select **Web application** as the application type 4. Choose or enter a name (e.g., `TomoTree Web`) ### 2c. Add Authorized Redirect URIs In the **Authorized redirect URIs** section, add: - For **local development**: `http://localhost:8501/oauth2callback` - For **production**: `https://your-domain.com:8501/oauth2callback` (replace with your actual domain) Click **CREATE**. ### 2d. Publish the app (switch from Testing to Production) By default, the OAuth app is in **Testing** mode, which limits login to explicitly listed test users. To allow any Google account to log in, you must publish the app: 1. In the left sidebar, go to **APIs & Services** → **OAuth consent screen** (or **Audience**) 2. At the top you will see the **Publishing status: Testing** 3. Click **PUBLISH APP** 4. Confirm the dialog — the status will change to **In production** > **Note:** If you keep the app in Testing mode, only users added under **Test users** will be able to log in. Everyone else will see an "Access blocked" error. ### 2e. Save your credentials A dialog will appear with: - **Client ID** (looks like: `123456789-abcdefg.apps.googleusercontent.com`) - **Client Secret** (a string of characters) **Copy both values** — you'll need them in the next step. You can also download a JSON file for reference. --- ## Step 3: Configure Streamlit Secrets ### 3a. Create or edit `~/.streamlit/secrets.toml` On **Linux/macOS**: ```bash mkdir -p ~/.streamlit nano ~/.streamlit/secrets.toml ``` On **Windows (PowerShell)**: ```powershell mkdir -Path $env:USERPROFILE\.streamlit -Force notepad $env:USERPROFILE\.streamlit\secrets.toml ``` ### 3b. Add your Google OAuth credentials Paste the following into `~/.streamlit/secrets.toml`: ```toml [auth] redirect_uri = "http://localhost:8501/oauth2callback" cookie_secret = "some-random-string" [auth.google] client_id = "YOUR_CLIENT_ID.apps.googleusercontent.com" client_secret = "YOUR_CLIENT_SECRET" server_metadata_url = "https://accounts.google.com/.well-known/openid-configuration" ``` TomoTree calls `st.login("google")`, so the credentials **must** be in the named `[auth.google]` section; a flat `[auth]` section with `client_id` is not used. If you also use logto.io, add an `[auth.logto]` section next to it (see [Logto.io Setup Guide](logto_setup.md)). Replace: - `YOUR_CLIENT_ID` with the Client ID from Step 2e - `YOUR_CLIENT_SECRET` with the Client Secret from Step 2e - `redirect_uri` — must match the redirect URI you registered in Google Cloud Console - `cookie_secret` — any random string used to sign the session cookie - `server_metadata_url` — Google's OpenID Connect discovery endpoint (leave as-is) ### 3c. Save the file Make sure the file has **restrictive permissions** (readable only by you): ```bash # Linux/macOS chmod 600 ~/.streamlit/secrets.toml ``` --- ## Step 4: Alternative — Project-level secrets file Streamlit reads the `[auth]` configuration only from a `secrets.toml` file — environment variables are **not** supported. Instead of `~/.streamlit/secrets.toml` you can put the same content into `.streamlit/secrets.toml` in the directory from which you start TomoTree. --- ## Step 5: Update TomoTree Configuration ### 5a. Copy configuration template If you haven't already: ```bash cp config/config.yaml.dist config/config.yaml cp config/login.yaml.dist config/login.yaml ``` ### 5b. Enable Google OAuth in `config/config.yaml` Add `google` to `oidc_providers` (the name must match the section `[auth.google]` in `secrets.toml`): ```yaml oidc_providers: google: label: Google # optional, text on the login button (default: the name) icon: "🔑" # optional (default: 🔑) ``` Login buttons follow the order given in `oidc_providers`, the first one is highlighted; a click starts the login at once. Password login is in a collapsed panel below them. ### 5c. Define role mappings (optional) Users are identified by their **Google email address**. You can assign roles based on email: ```yaml oidc_providers: google: label: Google roles: admin@example.com: [admin, developer, user] reviewer@example.com: [developer, user] viewer@example.com: [user] # Any email not listed gets the default 'user' role (comparison is case-insensitive) ``` --- ## Step 6: Run TomoTree ### 6a. Start the application ```bash streamlit run app.py # or make www ``` ### 6b. Test the login 1. Open **http://localhost:8501** in your browser 2. You should see the button **Login with Google** (with the `label` of the provider) and below it the collapsed panel **Password login** 3. Click **Login with Google** 4. You'll be redirected to Google's login page 5. Authorize the TomoTree app 6. Return to TomoTree — you should now be logged in ### 6c. Assign roles (if needed) If your email is not in `roles` of the `google` provider, you'll get the default `user` role. To give yourself admin access, add your Google email to `config/config.yaml`: ```yaml oidc_providers: google: roles: your.email@gmail.com: [admin, developer, user] ``` Then restart the application. --- ## Troubleshooting ### Issue: Google is not offered on the login screen, or a Google user is logged out at once **Solution:** Ensure `google` is listed in `oidc_providers` in `config/config.yaml` and restart the app. `make check-config` warns about the removed keys `authenticated_by_google` and `oauth_roles` and points to `oidc_providers`. ### Issue: Redirect URI mismatch error **Solution:** Check that the redirect URI in Google Cloud Console matches your Streamlit hostname: - Local: `http://localhost:8501/oauth2callback` - Production: `https://yourdomain.com:8501/oauth2callback` ### Issue: Credentials not found **Solution:** Verify that `~/.streamlit/secrets.toml` (or `.streamlit/secrets.toml` in the working directory) contains an `[auth]` section with `redirect_uri` and `cookie_secret` and an `[auth.google]` section with `client_id`, `client_secret` and `server_metadata_url`. ### Issue: Login works but no roles are assigned **Solution:** - Users not in `roles` of the provider get the default `user` role — this is normal - To give higher privileges, add the user's Google email to `roles` of the `google` provider in `oidc_providers` ### Issue: Login is refused: e-mail address not verified TomoTree identifies an OIDC user by the e-mail address, so it accepts a login only if the provider sends the claim `email_verified = true`. Otherwise anyone who registers someone else's address at the provider would get that user's data and roles. A refused login is logged as `OIDC login refused: provider=... reason=email_not_verified email_verified=...`; every accepted login logs `email_verified` too. **Solution:** Let the user verify the address at the provider (or the connected social account), or require e-mail verification in the provider's settings. Set `trust_email: true` for the provider in `oidc_providers` only if the provider verifies every address itself but does not send the claim; the installation check then shows a warning. ### Issue: Role does not take effect after updating config **Solution:** Restart the Streamlit app after modifying `config/config.yaml`. ### Issue: After logout the user is still logged in at Google **Explanation:** Google has no OIDC logout endpoint (the console shows `No end_session_endpoint found for provider google`), so logout ends only the TomoTree session. This is expected; the next login via Google may not ask for the password again. More OIDC problems and console messages: [installation guide, Troubleshooting OIDC login](installation.md#troubleshooting-oidc-login). --- ## Security Best Practices 1. **Never commit credentials** to version control - Keep `~/.streamlit/secrets.toml` local (not in git) - Use `.gitignore` to exclude it 2. **Keep the secrets file out of the image in production** - Docker: `secrets.toml` stays on the host, in the mounted `.streamlit/` directory (see below) - Cloud: Use secret management services (AWS Secrets Manager, GCP Secret Manager, etc.) to provision the file 3. **Rotate credentials periodically** - Go to Google Cloud Console - Delete old credentials and create new ones - Update `~/.streamlit/secrets.toml` 4. **Restrict redirect URIs** - Only add your actual domains to the OAuth app - Be specific (`https://yourdomain.com:8501/`, not just `https://yourdomain.com/`) 5. **Use HTTPS in production** - Streamlit's OAuth requires HTTPS for public URLs - Use a reverse proxy (nginx, Caddy) to handle TLS --- ## Docker Deployment With `docker/compose.yml` put your `secrets.toml` (with the `[auth]` and `[auth.google]` sections from Step 3b) into the `.streamlit/` directory of the data directory (`TOMOTREE_DIR`, the repository root by default); it is mounted to `/app/.streamlit/`. `setup_check --init` creates it with a random `cookie_secret`. See [docker/README.md](../docker/README.md). ```bash docker compose up -d ``` Remember to set `redirect_uri` to the public URL of the deployment. --- ## Further Reading - [Streamlit OAuth Documentation](https://docs.streamlit.io/deploy/authentication) - [Google Cloud OAuth 2.0 Documentation](https://developers.google.com/identity/protocols/oauth2) - [TomoTree Installation Guide](installation.md) - [Logto.io Setup Guide](logto_setup.md) — alternative OIDC provider that also supports Google, GitHub, and more