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
Click the project dropdown at the top
Click NEW PROJECT
Enter a project name (e.g.,
TomoTree)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
Go to APIs & Services → Credentials
Click + CREATE CREDENTIALS → OAuth 2.0 Client IDs
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
Return to Credentials page
Click + CREATE CREDENTIALS → OAuth 2.0 Client IDs
Select Web application as the application type
Choose or enter a name (e.g.,
TomoTree Web)
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:
In the left sidebar, go to APIs & Services → OAuth consent screen (or Audience)
At the top you will see the Publishing status: Testing
Click PUBLISH APP
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_IDwith the Client ID from Step 2eYOUR_CLIENT_SECRETwith the Client Secret from Step 2eredirect_uri— must match the redirect URI you registered in Google Cloud Consolecookie_secret— any random string used to sign the session cookieserver_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
Open http://localhost:8501 in your browser
You should see the button Login with Google (with the
labelof the provider) and below it the collapsed panel Password loginClick Login with Google
You’ll be redirected to Google’s login page
Authorize the TomoTree app
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/oauth2callbackProduction:
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
rolesof the provider get the defaultuserrole — this is normalTo give higher privileges, add the user’s Google email to
rolesof thegoogleprovider inoidc_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
Never commit credentials to version control
Keep
~/.streamlit/secrets.tomllocal (not in git)Use
.gitignoreto exclude it
Keep the secrets file out of the image in production
Docker:
secrets.tomlstays 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
Rotate credentials periodically
Go to Google Cloud Console
Delete old credentials and create new ones
Update
~/.streamlit/secrets.toml
Restrict redirect URIs
Only add your actual domains to the OAuth app
Be specific (
https://yourdomain.com:8501/, not justhttps://yourdomain.com/)
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
Logto.io Setup Guide — alternative OIDC provider that also supports Google, GitHub, and more