DEV Community

foxck016077
foxck016077

Posted on

Gmail OAuth client_id is not a secret â design notes for self-host Actors

#api #architecture #google #security

This question keeps coming up:

"My Gmail OAuth client_id got leaked. Is the system compromised?"

Short answer: client_id was never a secret. What you actually need to protect is the token, the client_secret (if your flow uses one), and the overall authorization exchange boundary.

This matters more in a self-host Actor scenario, because you are not shipping a single deployment — every user runs it their own way.

Public identifier, not sensitive credential

The OAuth client_id is closer to an application identifier than a password. It needs to be visible to the OAuth server and the front-end flow. In many scenarios it appears in places that are reasonable to see.

Treating client_id like a password and "hiding" it is usually a misunderstanding:

  • You cannot hide it (front-end, request URLs, logs all expose it)
  • Hiding it does not raise overall security
  • Worse, it can distract you from the real attack surface

The question worth asking is: if an attacker knows your client_id, what can they still do? If the answer is "nothing — they cannot complete an authorization exchange or obtain a valid token", your design is pointing in the right direction.

Where the security budget actually goes

For a self-host Actor, security is about flow integrity, not a single magical value. I focus on four layers:

  1. redirect URI allowlist — only registered and verifiable callbacks
  2. state / anti-CSRF — every authorization round-trip is bound to the originating session
  3. token storage and rotation — least privilege, shortest exposure, revocable
  4. tenant isolation — every token is namespaced to a tenant and never crosses boundaries

If these four layers are solid, client_id visibility is not a primary risk.

Common mistake: budget in the wrong place

I have seen projects spend real effort on "obfuscating client_id" while ignoring problems that actually cause incidents:

  • weak callback endpoint validation
  • tokens accidentally landing in logs with broad ACLs
  • error handlers leaking internal state to the caller
  • inconsistent multi-tenant key naming that lets one tenant trip into another's data

Those are the things that bite.

Security is not about mystique. It is about staying recoverable in the worst case.

What this means for multi-tenant Actor design

Once you accept "client_id is visible by design", the architecture gets cleaner. Attention naturally shifts to:

  • scope minimization — request only the permissions you truly need (in my Actor, gmail.readonly and nothing else)
  • explicit token lifecycle — when it renews, when it expires, when it can be revoked
  • auditable execution path — which tenant triggered which run when

These decisions directly affect product trust and how much firefighting future-you will be doing.

Self-host does not exempt you from threat modeling

A tempting shortcut: "It's self-host, so the risk lives with the user."

That is half right. Yes, deployment responsibility moves to the operator. But as the author you still owe secure defaults:

  • safe defaults rather than risky defaults
  • explicit documentation rather than verbal hints
  • observable errors rather than silent failures

Otherwise you are not reducing risk, you are just shifting it.

Documentation pattern

For OAuth-touching repos, I now write three things first:

  1. Which values are public, which must stay private
  2. The lifecycle and revocation path for every token
  3. What a user can actually do when an authorization error happens

Two effects:

  • new users do not get blocked on a panic about the wrong thing
  • experienced reviewers can audit your security logic quickly

The clearer you are, the easier it is for the community to trust your project.

Open-source carries extra weight

In open source, a misleading security narrative is more dangerous than in a private product, because it gets copied.

If you frame client_id as "top secret", others will copy that posture and ship the same broken model with real problems intact.

I prefer to spell it out in the README:

  • client_id is expected to be visible
  • the real sensitive surface is token handling and flow protection
  • multi-tenant isolation is enforced through data structure and routing logic

That way, even a fork carries a less-wrong threat model forward.

Closing: stop asking "can I hide it"

The question I keep on a sticky note for OAuth design is:

"If this value gets seen, is the system still safe?"

If a single exposed value collapses the system, the problem is not secret management — it is brittle architecture.

For Gmail OAuth in a self-host Actor, client_id is not the protagonist. The real protagonist is a verifiable, revocable, isolated authorization system.

Related

Top comments (0)