AJDA-3380: fix the Google OIDC tab after the usability test

[Iamfle4ka]

Why

Michal (design) spent 40 minutes following the Google tab of /data-apps/authentication/ and hit a snag at nearly every step; the recording is the input for this PR. One of the snags turned out to be a wrong claim on our side: the page said an External app in Testing lets in only its listed test users. Google exempts apps that request only openid, email and profile from that rule ("users do not need to be in the trusted user list, they will not see a warning message", support.google.com/cloud/answer/15549945), and that is exactly what the Keboola proxy requests (oauth2-proxy's default OIDC scope; keboola-as-code sets none). So an External app lets in anyone with a Google account, Testing or not, and Internal is what restricts sign-in to the organization. Michal's test showed that, and so did the run below.

Part of AJDA-3380 (Apps docs review for the 1 Oct GA).

What changes

src/content/docs/data-apps/authentication.mdx only.

• Google tab rewritten around what the reader actually sees: Google Auth Platform with direct links to Overview, Branding, Audience and Clients; both states of the consent screen (a project showing Get started versus one already configured); the Test users / Publish app instruction replaced by the Internal versus External rule above; the exact redirect-URI field with a filled-in example; the error headline Google shows (Access blocked: This app's request is invalid) and where Request details is; the encrypted KBC::ProjectSecureGKMS:: value behind the eye icon on the secret field; "You now have" checkpoints after each block.
• Shared steps: Step 1 starts from an existing app, however it was built, and only then says how to create one; the App URL screenshot is the one that shows the Overview tab; the admin-rights prerequisite is stated up front, including that Kai and kbagent cannot do this part (MCP authentication_type is no-auth | basic-auth | default; CLI --auth is password | public); Step 3 covers a running app (Redeploy App) versus a stopped one (Start App), says to test each account in a fresh private window, and gives /_proxy/sign_out for ending a session between tests.
• Entra, Okta and Auth0 tabs: checkpoint lines, plus the corrections from the documentation pass described below.

Verification

• npm run build clean, judged by its exit code; node scripts/audit-phase2.mjs shows nothing on this page.
• fact-checker (repo agent, Opus): no CRITICAL, no MAJOR; 28 claims confirmed against Google's help pages, oauth2-proxy and keboola-as-code sources, the MCP server, and the repo's screenshots. Its seven minor findings are folded into commit 2.

Live run, 22 Sep

The tab was followed end to end against real infrastructure: a new Google Cloud project keboola-docs-test in the ext.keboola.com organization, OAuth client docs-test-google-2026-09-22, and a throwaway Streamlit app in project 264.

Test	Setup	Expected	Result
1	Internal audience, account inside the organization	signs in	signed in, app rendered
2	External audience, status Testing, zero test users	signs in anyway	signed in, no warning, no consent friction
3	Internal audience, account outside the organization	refused	not run, and not planned: it needs a second Google account, and the remaining time before the freeze goes to the other three providers

Test 2 is what this PR rests on. The sign-in URL the proxy generates carries scope=openid+email+profile in the address bar, so Google's own exemption rule covers it and we are no longer arguing from the source code alone.

Seven things the run corrected in the text (commit 3): authorized domains are added from the redirect URI automatically, so Branding is optional; the "Get started" branch has to key off the content area, because Branding / Audience / Clients sit in the left menu either way; the Audience page shows publishing status, user cap and test users only for External; the secret field is masked after saving and the encrypted value hides behind the eye icon; the deploy wizard asks three things; the consent screen also appears on first sign-in for an Internal app; /_proxy/sign_out added.

One thing stayed unverified here: the Request details label on Google's error page and the redirect_uri_mismatch wording come from Michal's test, since the typo was never re-created during this run.

One edge the page leaves out on purpose: if an app ever gets an allowed-roles list, oauth2-proxy adds the groups scope and Google's exemption stops applying. The UI has no such field for OIDC providers today.

Documentation pass on the other three tabs, 23 Sep

Entra, Okta and Auth0 have never been run against a live tenant. Each was checked against the vendor's current public documentation instead, and each check found something.

Okta, and this one is critical. On an Integrator Free Plan org the default authorization server ships without an access policy, so every token request fails until you add one. A reader on the most common free org type would have followed our instructions exactly and hit a failure with nothing in our troubleshooting list matching it. Three more from the same check: the menu parenthetical was backwards, since Applications and Resources is the Identity Engine label and Applications → Applications the Classic one; the wizard may ask which experience to use; and /login/signout is not an endpoint Okta documents anywhere, so the logout guidance now uses the end_session_endpoint from discovery, and step 4 no longer tells readers to delete the sign-out redirect URI that the logout flow needs.

Entra. The assignment flow stopped one click short of Assign, so nothing was saved. Worse, testing the restriction while signed in as a Global Administrator gives a false pass, because the requirement does not apply to them, and that is exactly the account a reader is likely to be using. The role sentence named a floor where Microsoft documents alternatives. The claim I most expected to be stale, P1 or P2 for group assignment, is still what Microsoft documents in three places and is unchanged.

Auth0. A post-logout redirect has to be registered under Allowed Logout URLs or Auth0 refuses it, which we never mentioned. And "copy the issuer from discovery" broke for custom-domain tenants, who have two domains and would have copied the wrong one. Discovery is now the primary instruction; the trailing slash was confirmed against two real discovery documents rather than prose.

Live runs of all three are planned before the freeze, once tenants exist. Two things only a live run can settle: Okta's two error strings, which Okta does not publish anywhere, and whether either redirect-URI field arrives prefilled.

For the Apps team, not this PR

• A copy button for the callback URL inside the OIDC form would have saved Michal his typo.
• Revealing the secret shows the encrypted KBC::… string, which reads as if the secret had been replaced. Hiding it entirely would be better.
• The Auth0 preset placeholder has no trailing slash while Auth0's issuer does.

🤖 Generated with Claude Code

[vercel]

Someone is attempting to deploy a commit to the Keboola Engineering Team on Vercel.

A member of the Team first needs to authorize it.

[Iamfle4ka]

Superseded by #1139, which now carries every commit from this branch.

Verified rather than assumed: this branch's tip 21ecda74 is an ancestor of #1139's head de406ab7, checked with git merge-base --is-ancestor. The live-run evidence and the vendor-documentation check that lived in this description have been carried into #1139's, so the reviewer sees what the claims rest on.

Branch AJDA-3380-oidc-google-tab is left in place; nothing here is lost.