Turn Off Debugging By Publisher, By Bidder

[SyntaxNode]

This issue now incorporates the requirements from #510, combing proposals from @hhhjort and @bretg.

Description

PBS has a debug feature that publishers can enable to get extra details in their response from Prebid Server, including the resolved stored request and requests/responses to/from bidding servers (url, status code, body, headers).

It's possible for malicious users to submit a request to Prebid Server with the intent of pulling back stored requests for another publisher or for retrieving secret tokens or ids from requests to bidding servers. We'd like to point out that Prebid.js has no possibility of hiding this information since all data is proxied through the user's browser. It's only with Prebid Server that we can consider enhanced protections for hosts and publishers.

For example, the host specific values for the new Recontent #1622 adapter might want to be secured.

Proposal

Build new options in Prebid Server to allow publishers to disable debugging for their requests using account level settings and to allow hosts to disable debugging of specific bidders. However, disabling the debug information has a very real side effect of making it hard to track down problems. Hosts may run a separate debug instance on their servers or local machines with the debug restrictions removed, or this proposal also includes an authorization header token which will bypass any debug disabled settings. It's my intention for authorization tokens to be used by the host to debug issues on behalf of their publishers.

Publisher Controls

Add a new account level setting debug-allow which defaults to true. I don't expect further fine grain controls added to this feature at the account level, so the setting is a single boolean value. When false, no debugging information at all is sent back to the publisher and a warning is emitted in the response:

Account JSON For PBS-Go:

{
  "debug_allow": true
}

Response:

{
  "ext": {
    "warnings":  {
      "general": [{code: 10002, message: "debug turned off for account"}]
    }
  }
}

Warning codes in PBS-Go begin with 10000 and the next available value is 10002. The code allows publishers to look for specific type of warnings without relying on string compare.

Bidder Controls

Add a new bidder level settings debug.allow which defaults to true. I can imagine fine grain controls added in the future to possibly restrict just specific kinds of the debug information such as the url, body, or headers. Therefore, I'm proposing a debug object for forward compatibility. When false, no debugging information for this specific bidder is sent back to the publisher, except for a warning in the response:

Bidder YAML:

debug:
  allow: true

Response:

{
  "ext": {
    "warnings":  {
      "{biddername}": [{code: 10003, message: "debug turned off for bidder"}]
    }
  }
}

Override Tokens

Add a new host level setting for a debug override token string. The caller will provide the token to PBS using an HTTP header x-pbs-debug-override. When PBS finds an exact case-sensitive match to the header token, it will override any account level and bidder level debug setting and send back the full debug response to the caller without warnings. This is intended for use by the host to perform end to end debugging regardless of account or bidder debug permissions.

Prebid Server YAML:

debug:
  override_token: "N%'$6aremcMGK7hN"

[bretg]

Is the use-case here that there's a key of some sort that validates the request to the bidder? Is that key on the URL?

We need to be able to debug. I cannot imagine wanting to work with a bidder for whom I can't turn on debugging to see what we send them and what they return. So many bidders are already difficult to work with, but being blind to their endpoint requests will make them impossible to work with.

But security is important, so perhaps there's a compromise.

Another option is to have an admin-level override to being able to get debug info. i.e. if an authorized administrator sends an HTTP header like "x-pbs-debug-override: AUTH_STRING", maybe that's the best of both worlds -- normal users can't see the sensitive data, but the poor buggers whose job it is to sift through absurdly complicated issues can get what they need.

[SyntaxNode]

We really like the compromise of an auth token. I'll update the proposal to include it. With that in mind, I'd like to keep this simple and have just a single "debug.allow" instead of breaking it down to url, body, etc... I'll keep the debug flags in it's own object such that we could add that on in the future if need be. Happy to keep it simple for now.

[bretg]

Discussed in PBS committee

• @SyntaxNode to post more detail about the auth token
• add account and bidder config to turn on a "private-debug" flag

[bretg]

After this is merged, we'll need to update the 'troubleshooting' page on docs.prebid.org to note that setting the header may be necessary depending on the PBS host company. This can be done with a number of Chrome extensions like Requestly.

[SyntaxNode]

Implemented in PBS-Go 0.163.0.

[bretg]

done with PBS-Java 1.77