webRequest.onAuthRequired listeners can provide authentication credentials.

chrome/test/data/extensions/api_test/webrequest/test_auth_required.html

Index: chrome/test/data/extensions/api_test/webrequest/test_auth_required.html
diff --git a/chrome/test/data/extensions/api_test/webrequest/test_auth_required.html b/chrome/test/data/extensions/api_test/webrequest/test_auth_required.html
new file mode 100644
index 0000000000000000000000000000000000000000..94ae1240ddf10882aaf5aaa01d8f4165120515d1
--- /dev/null
+++ b/chrome/test/data/extensions/api_test/webrequest/test_auth_required.html
@@ -0,0 +1,323 @@
+<script src="framework.js">

[battre, 2011/10/10 13:47:03]

as some tests are blocking, there is a certain chance that this will be flaky
(test_blocking.html has been disabled for that reason). http://crbug.com/91715

+</script>
+<script>
+function getURLAuthRequired() {
+  return getServerURL('auth-basic');
+}
+
+runTests([
+  // onAuthRequired is not a blocking function in this variant.
+  function authRequiredNonBlocking() {
+    expect(
+      [  // events
+        { label: "onBeforeRequest",
+          event: "onBeforeRequest",
+          details: {
+            url: getURLAuthRequired(),
+            frameUrl: getURLAuthRequired()
+          }
+        },
+        { label: "onBeforeSendHeaders",
+          event: "onBeforeSendHeaders",
+          details: {
+            url: getURLAuthRequired(),
+            // Note: no requestHeaders because we don't ask for them.
+          },
+        },
+        { label: "onSendHeaders",
+          event: "onSendHeaders",
+          details: {
+            url: getURLAuthRequired(),
+          }
+        },
+        { label: "onHeadersReceived",
+          event: "onHeadersReceived",
+          details: {
+            url: getURLAuthRequired(),
+            responseHeadersExist: true,
+            statusLine: "HTTP/1.0 401 Unauthorized"
+          }
+        },
+        { label: "onAuthRequired",
+          event: "onAuthRequired",
+          details: {
+            url: getURLAuthRequired(),
+            isProxy: false,
+            scheme: "basic",
+            realm: "testrealm",
+            challenger: {host: testServer, port: testServerPort},
+            responseHeadersExist: true,
+            statusLine: "HTTP/1.0 401 Unauthorized",
+          }
+        },
+        { label: "onResponseStarted",
+          event: "onResponseStarted",
+          details: {
+            url: getURLAuthRequired(),
+            fromCache: false,
+            statusCode: 401,
+            ip: "127.0.0.1",
+            responseHeadersExist: true,
+            statusLine: "HTTP/1.0 401 Unauthorized",
+          }
+        },
+        { label: "onCompleted",
+          event: "onCompleted",
+          details: {
+            url: getURLAuthRequired(),
+            fromCache: false,
+            statusCode: 401,
+            ip: "127.0.0.1",
+            responseHeadersExist: true,
+            statusLine: "HTTP/1.0 401 Unauthorized",
+          }
+        },
+      ],
+      [  // event order
+        ["onBeforeRequest", "onBeforeSendHeaders", "onSendHeaders",
+         "onHeadersReceived", "onAuthRequired", "onResponseStarted", 
+         "onCompleted"]
+      ],
+      {}, ["responseHeaders"]);
+    navigateAndWait(getURLAuthRequired());
+  },
+
+  // onAuthRequired is a blocking function but takes no action in this variant.
+  function authRequiredNoAction() {
+    expect(
+      [  // events
+        { label: "onBeforeRequest",
+          event: "onBeforeRequest",
+          details: {
+            url: getURLAuthRequired(),
+            frameUrl: getURLAuthRequired()
+          }
+        },
+        { label: "onBeforeSendHeaders",
+          event: "onBeforeSendHeaders",
+          details: {
+            url: getURLAuthRequired(),
+            // Note: no requestHeaders because we don't ask for them.
+          },
+        },
+        { label: "onSendHeaders",
+          event: "onSendHeaders",
+          details: {
+            url: getURLAuthRequired(),
+          }
+        },
+        { label: "onHeadersReceived",
+          event: "onHeadersReceived",
+          details: {
+            url: getURLAuthRequired(),
+            responseHeadersExist: true,
+            statusLine: "HTTP/1.0 401 Unauthorized"
+          }
+        },
+        { label: "onAuthRequired",
+          event: "onAuthRequired",
+          details: {
+            url: getURLAuthRequired(),
+            isProxy: false,
+            scheme: "basic",
+            realm: "testrealm",
+            challenger: {host: testServer, port: testServerPort},
+            responseHeadersExist: true,
+            statusLine: "HTTP/1.0 401 Unauthorized",
+          }
+        },
+        { label: "onResponseStarted",
+          event: "onResponseStarted",
+          details: {
+            url: getURLAuthRequired(),
+            fromCache: false,
+            statusCode: 401,
+            ip: "127.0.0.1",
+            responseHeadersExist: true,
+            statusLine: "HTTP/1.0 401 Unauthorized",
+          }
+        },
+        { label: "onCompleted",
+          event: "onCompleted",
+          details: {
+            url: getURLAuthRequired(),
+            fromCache: false,
+            statusCode: 401,
+            ip: "127.0.0.1",
+            responseHeadersExist: true,
+            statusLine: "HTTP/1.0 401 Unauthorized",
+          }
+        },
+      ],
+      [  // event order
+        ["onBeforeRequest", "onBeforeSendHeaders", "onSendHeaders",
+         "onHeadersReceived", "onAuthRequired", "onResponseStarted",
+         "onCompleted"]
+      ],
+      {}, ["responseHeaders"]);

[battre, 2011/10/10 13:47:03]

forgot "blocking"?

[cbentzel, 2011/10/10 13:59:54]

Oops! Thanks.

+    navigateAndWait(getURLAuthRequired());
+  },
+
+  // onAuthRequired is a blocking function that cancels the auth attempt.
+  function authRequiredCancelAuth() {
+    expect(
+      [  // events
+        { label: "onBeforeRequest",
+          event: "onBeforeRequest",
+          details: {
+            url: getURLAuthRequired(),
+            frameUrl: getURLAuthRequired()
+          },
+          retval: {}
+        },
+        { label: "onBeforeSendHeaders",
+          event: "onBeforeSendHeaders",
+          details: {
+            url: getURLAuthRequired(),
+            // Note: no requestHeaders because we don't ask for them.
+          },
+          retval: {}
+        },
+        { label: "onSendHeaders",
+          event: "onSendHeaders",
+          details: {
+            url: getURLAuthRequired(),
+          }
+        },
+        { label: "onHeadersReceived",
+          event: "onHeadersReceived",
+          details: {
+            url: getURLAuthRequired(),
+            responseHeadersExist: true,
+            statusLine: "HTTP/1.0 401 Unauthorized"
+          }
+        },
+        { label: "onAuthRequired",
+          event: "onAuthRequired",
+          details: {
+            url: getURLAuthRequired(),
+            isProxy: false,
+            scheme: "basic",
+            realm: "testrealm",
+            challenger: {host: testServer, port: testServerPort},
+            responseHeadersExist: true,
+            statusLine: "HTTP/1.0 401 Unauthorized",
+          },
+          retval: {cancel: true}

[battre, 2011/10/10 13:47:03]

in all other handlers, {cancel: true} leads to "onErrorOccurred". I am not sure
whether we want to stick to this alternate meaning of "cancel".

[cbentzel, 2011/10/10 13:59:54]

Good question. I mentioned overloading "cancel" on an email thread and
mpcomplete sounded OK with it, but I'm happy to change this. 

[battre, 2011/10/10 14:32:13]

I guess I am OK with either approach.

+        },
+        { label: "onResponseStarted",
+          event: "onResponseStarted",
+          details: {
+            url: getURLAuthRequired(),
+            fromCache: false,
+            statusCode: 401,
+            ip: "127.0.0.1",
+            responseHeadersExist: true,
+            statusLine: "HTTP/1.0 401 Unauthorized",
+          }
+        },
+        { label: "onCompleted",
+          event: "onCompleted",
+          details: {
+            url: getURLAuthRequired(),
+            fromCache: false,
+            statusCode: 401,
+            ip: "127.0.0.1",
+            responseHeadersExist: true,
+            statusLine: "HTTP/1.0 401 Unauthorized",
+          }
+        },
+      ],
+      [  // event order
+        ["onBeforeRequest", "onBeforeSendHeaders", "onSendHeaders",
+         "onHeadersReceived", "onAuthRequired", "onResponseStarted", 
+         "onCompleted"]
+      ],
+      {}, 
+      ["responseHeaders", "blocking"]);
+    navigateAndWait(getURLAuthRequired());
+  },
+
+  // onAuthRequired is a blocking function that sets authentication credentials.
+  // This needs to be done last, otherwise the authentication
+  // credentials will be cached and the other tests will fail.
+  function authRequiredSetAuth() {
+    expect(
+      [  // events
+        { label: "onBeforeRequest",
+          event: "onBeforeRequest",
+          details: {
+            url: getURLAuthRequired(),
+            frameUrl: getURLAuthRequired()
+          },
+          retval: {}
+        },
+        { label: "onBeforeSendHeaders",
+          event: "onBeforeSendHeaders",
+          details: {
+            url: getURLAuthRequired(),
+            // Note: no requestHeaders because we don't ask for them.
+          },
+          retval: {}
+        },
+        { label: "onSendHeaders",
+          event: "onSendHeaders",
+          details: {
+            url: getURLAuthRequired(),
+          }
+        },
+        { label: "onHeadersReceived",
+          event: "onHeadersReceived",
+          details: {
+            url: getURLAuthRequired(),
+            responseHeadersExist: true,
+            statusLine: "HTTP/1.0 401 Unauthorized"
+          }
+        },
+        { label: "onAuthRequired",
+          event: "onAuthRequired",
+          details: {
+            url: getURLAuthRequired(),
+            isProxy: false,
+            scheme: "basic",
+            realm: "testrealm",
+            challenger: {host: testServer, port: testServerPort},
+            responseHeadersExist: true,
+            statusLine: "HTTP/1.0 401 Unauthorized",
+          },
+          retval: {authCredentials: {username: "foo", password: "secret"}}

[battre, 2011/10/10 13:47:03]

we could add a test case where we specify the wrong credentials. Are we asked
again?

What was the conclusion about the question how often an extension may try to
submit credentials?

[cbentzel, 2011/10/10 13:59:54]

Yes, we're asked again. I'll add a test case. 
I don't think there was consensus on what should happen in that case.

One problem if we don't ask a second time is that the extension gets no signal
that the provided credentials are bad. We could potentially add an
onAuthFailed() handler to deal with this case, but that's actually a bit tricky
since the authDetails are not guaranteed to be the same each round.

[battre, 2011/10/10 14:32:13]

How about adding a counter "authorizationAttempt"? The extension author could
use this to stop trying to log in after a number of attempts that are
appropriate in his opinion.

The author could track this number himself but this way, it might be more
explicit that he is encouraged to think about the number of failures.

[cbentzel, 2011/10/10 14:38:06]

Arguably the extension author could maintain that count as well, using the
details as a dictionary into a map. I'm always hesitant to add additional
parameters to the API if not needed.

[battre, 2011/10/10 14:47:10]

Ok, but then we should highlight this problem in the API documentation.

[cbentzel, 2011/10/10 15:09:19]

SGTM. 

+        },
+        { label: "onResponseStarted",
+          event: "onResponseStarted",
+          details: {
+            url: getURLAuthRequired(),
+            fromCache: false,
+            statusCode: 200,
+            ip: "127.0.0.1",
+            responseHeadersExist: true,
+            statusLine: "HTTP/1.1 200 OK",
+          }
+        },
+        { label: "onCompleted",
+          event: "onCompleted",
+          details: {
+            url: getURLAuthRequired(),
+            fromCache: false,
+            statusCode: 200,
+            ip: "127.0.0.1",
+            responseHeadersExist: true,
+            statusLine: "HTTP/1.1 200 OK",
+          }
+        },
+      ],
+      [  // event order
+        ["onBeforeRequest", "onBeforeSendHeaders", "onSendHeaders",
+         "onHeadersReceived", "onAuthRequired", "onResponseStarted", 
+         "onCompleted"]
+      ],
+      {}, 
+      ["responseHeaders", "blocking"]);
+    navigateAndWait(getURLAuthRequired());
+  },
+]);
+</script>