Repository navigation
fix(openapi): declare authentication via securitySchemes instead of ignored header parameters - #716
Open
yingzhehu-TT wants to merge 3 commits into
Conversation
|
Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA). View this failed invocation of the CLA check for more information. For the most up to date status, view the checks section at the bottom of the pull request. |
Contributor
Author
|
@googlebot I signed it! |
yingzhehu-TT
force-pushed
the
fix/openapi-security-schemes
branch
from
August 12, 2026 08:20
b03de9c to
3dd8837
Compare
yingzhehu-TT
force-pushed
the
fix/openapi-security-schemes
branch
from
September 3, 2026 18:25
3dd8837 to
ff597f3
Compare
9 of 11 tasks
yingzhehu-TT
force-pushed
the
fix/openapi-security-schemes
branch
from
October 8, 2026 09:33
ff597f3 to
19558c8
Compare
8 of 17 tasks
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #668
Summary
components.securitySchemesand adocument-level
securityrequirement in every REST service definition:shopping, common and lodging.
authorization,x_api_key,content_typeandacceptheaderparameter definitions and every
$refto them.Motivation
#668 reports that
Authorizationis declared as a header parameter, whichOpenAPI 3.1 requires implementations to ignore. The same clause covers two more
parameters the issue does not mention:
So tooling that follows the specification never sees the OAuth bearer
requirement, and no REST definition declares
components.securitySchemes.X-API-Keyis not in the ignore list — generated code does keep it — but #668asks for "securitySchemes that specify all supported types", so it moves too.
Since this PR was first opened,
common/rest.openapi.jsonandlodging/rest.openapi.jsonhave been added onmainwith the same four headerparameters; both are covered here.
Design decisions
The schemes mirror the mechanisms the spec lists. The overview's
Authentication Mechanisms section names API Keys, OAuth 2.0, mTLS and HTTP
Message Signatures, and the cart, checkout and lodging booking REST bindings
state that "Authentication is optional and depends on business requirements".
Every mechanism OpenAPI can express is declared, as alternatives:
securityalternative{}X-API-Keyapi_key—apiKey, headerX-API-KeyAuthorization: Beareroauth2_bearer—http,bearermutual_tls—mutualTLSKeeping
{}matters: every replaced parameter wasrequired: false, soomitting it would tighten the contract.
http/bearerrather thanoauth2with flows. An OAuth Flow Objectrequires concrete
tokenUrl/authorizationUrlvalues, and UCP has none togive: platforms locate the authorization server at runtime through RFC 9728
protected-resource metadata and RFC 8414 server metadata, and it may sit on a
different origin.
http/bearerstates exactly what is true on the wire —Authorization: Bearer <access_token>— without fabricating endpoints. Theheader macro handles
oauth2too, so switching later would not affect the docs.The order-event webhook keeps its own requirement.
orderEventis abusiness-to-platform call, where a bearer token from the business's own
authorization server makes no sense, and OpenAPI 3.1 does not say whether
document-level
securityapplies to webhooks. So it declaressecurity: [{}, {"api_key": []}]explicitly — the same optionalX-API-Keyithad as a parameter.
Signature headers stay as parameters.
Signature,Signature-InputandContent-Digestare not in the ignore list, and OpenAPI 3.1 has nosecurity-scheme type for HTTP Message Signatures.
Corrections to the previous description
Several statements in the earlier description were wrong:
main.py::method_fieldsexplicitly skipsin: headerparameters ("Filter out headers (transport-specific)"), soremoving them changes no generated table."
method_fieldsdoes skip them,but
header_fieldsrenders exactly those parameters, so this change wouldhave dropped four rows from every REST binding's header table. That is now
handled by fix(docs): list headers declared through security and content maps #914, which this PR depends on.
securityrequirement applies to webhook operationstoo, so the webhook's authentication contract is preserved rather than
dropped." OpenAPI 3.1 does not specify that, and if it did apply, the webhook
would have gained an optional bearer alternative. The webhook now declares its
own requirement, above.
common/rest.openapi.json. It has the same four parameters, but itsdescriptions differ from shopping's.
signatures.mdstates that platforms SHOULD sign requests and MAYuse alternative mechanisms (API keys, OAuth, mTLS) instead." Its text is
"Platforms SHOULD sign all requests when using HTTP Message Signatures.
Alternative authentication mechanisms (API keys, OAuth, mTLS) may be used
instead." — a lowercase "may", and a SHOULD conditional on using signatures.
The basis for
{}is now the REST bindings' own wording, above.drops the authentication contract." Only the ignored parameters are dropped;
X-API-Keyis not ignored and survives in generated code.Scope
source/services/shopping/rest.openapi.json,common/rest.openapi.jsonandlodging/rest.openapi.json, one commit each, with identicalsecuritySchemesand document-level
securityin all three. Incommon, this includes thePOST /askoperation added since the first revision.permalink.openapi.jsonandhandlers/tokenization/openapi.jsondeclare noauthentication headers and are untouched. #897's
food/rest.openapi.jsonis noton
mainyet, so it is not changed here.Validation
openapi-spec-validator, withinfo.versioninjected ashooks.py::_set_schema_versiondoes at build time: shopping, common andlodging are all VALID OpenAPI 3.1.
ucp-schema lint source/— 145 files checked, all passed. No$refto aremoved parameter remains anywhere under
source/.scripts/validate_examples.py --schema-base source/schemas/— 398 passed,0 failed, 53 skipped.
appears twice; all six list
Authorization,X-API-KeyandAccept, and allbut
get_orderlistContent-Type, since a GET has no request body. Thosefour rows now take their descriptions from the schemes and media types, and
Content-Type/Acceptmove to the end of the table.mkdocs build --strictexits 0 underDOCS_MODE=specandroot.assertion against an independently built target document, so nothing other
than the intended removals and additions could change.
🤖 Generated with Claude Code