Potential spec mismatch: `BasicOAuthProvider` sends `service` & `scope` as headers instead of query params

[meixnerlu]

I’m trying to confirm whether BasicOAuthProvider in vscode-docker-registries is implementing the Docker V2 token spec correctly:

• The getSession() method issues the token request like this:

httpRequest(this.oAuthEndpoint, {
  method: 'GET',
  headers: {
    Authorization: 'Basic …',
    grant_type: 'password',
    service: this.oAuthService,
    scope: '…'
  }
});

• The Docker Registry V2 spec and Docker's official docs mandate that clients request tokens using query parameters:

GET https://auth.example.com/token?service=registry.example.com&scope=repository:foo/bar:pull

---

Points of uncertainty:

1. Spec compliance:
   Is using service and scope in headers acceptable under the spec? Official docs emphasize using query parameters—and there's no mention of passing them via headers .

2. Backward compatibility:
   While many registries (Docker Hub, ACR, Artifactory) appear lenient and accept headers, is this intentional or just undocumented behavior?

3. Risk of regressions:
   If header-based parameters are unsupported in stricter setups, moving to query-based parameters could break existing workflows—or fix them depending on the registry.

---

Request for clarification:

• Is the current implementation a known, intentional choice for compatibility?
• Or is it an oversight that should be corrected for spec compliance?

---

Context / Use-case:
I hit authentication failures with a custom token server that only reads query params. The CLI (docker pull) worked fine, but VS Code failed, which led to this discovery.
I verified with logging that the VS Code Container Tools extension using this package sends the service and scopes in the headers and that the docker cli does not.

---

Happy to help with implementing a fix!

[bwateratmsft]

This is most likely an oversight, but obviously we want to test to be sure the alternative works. There seems to be an awful lot of variability in terms of actual adherence to the Registry V2 spec, especially as it pertains to auth...

Perhaps it would work to send service and scope as both headers and query params?

[meixnerlu]

Sounds like a good compromise. Should I draft a PR for this?

[bwateratmsft]

Sure!