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/ 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:

mkdir -p ~/.streamlit
nano ~/.streamlit/secrets.toml

On Windows (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:

[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).

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):

# 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:

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):

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:

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

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:

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.


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 compose up -d

Remember to set redirect_uri to the public URL of the deployment.


Further Reading