Acquire token interactive using system browser

[abhidnya13]

Original goal:

• Adding state and pkce
• Can we use a custom browser
• Cleaning up the code and structure
• Reference docs

---

Latest Update:

The latest commit implements:

• state, nonce and PKCE protection are already implemented by recent refactoring. This PR is built on top of that, thus including these security behavior. This PR focus on the new acquire_token_interactive() API.
• Reference docs is available in staging environment, and will show up in production once this PR is merged.
• Telemetry with API ID (the new API ID is also updated into the internal Telemetry table
• We will work out a sample at a later time

[henrik-me]

[rayluo]

• Adding 2 implementation-level comments below, however those part of code structure would likely be adjusted anyway, when you carry out the authcode.py refactor which you brought up days ago. Do you have any idea to discuss in our upcoming meeting?
• And, what is your thought on this one?

[jiasli]

Such a brilliant solution to use port 0 to pick an unused port, such as

https://docs.python.org/3/library/socketserver.html#asynchronous-mixins

    # Port 0 means to select an arbitrary unused port
    HOST, PORT = "localhost", 0

This avoids the unnecessary complexity of dealing with port occupation on Windows (Azure/azure-cli#10955) and try-next-port logic (Azure/azure-cli#6593).

[rayluo]

Thank you for noticing this subtle implementation detail. The try-next-port logic was an easy way out, but it was not only just more "unnecessarily complex", it also has potential race condition error. The port-0 approach, on the contrary, wasn't obvious at the beginning. It took us some dedication to find it. This reminds me again C.A.R. Hoare's quote. :-)

[jiasli]

I read another article about this topic: https://gavv.github.io/articles/ephemeral-port-reuse/

Note that when some application uses bind to allocate an ephemeral port for a TCP socket, and then immediately calls listen, there is still a short period of time when the socket is in the non-listening state.

Thus, to prevent the probability of stealing a port of a random running application, take care not to accidentally enable SO_REUSEADDR when using ephemeral ports, both for UDP and TCP sockets.

Also https://stackoverflow.com/a/23303544/2199657

By default, the kernel will not reuse any in-use port for an ephemeral port, which may result in failures if you have 64K+ simultaneous ports in use.

You can explicitly reuse a port by using the SO_REUSEADDR socket option and explicitly binding to the same port. This only works if none of the ports are listening (you can't reuse a listening port), and if you connect each socket to a different remote address.

https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=174087

Problem #2 is that the ephemeral port number is chosen before the
fport/faddr gets set on the pcb; that is tcp_connect() calls in_pcbbind() to
select the ephemeral port number, then calls in_pcbconnect_setup() to
populate the fport/faddr. With SO_REUSEADDR, in_pcbbind() can select
an in-use local port. If the local port is used by a socket with a different
laddr/fport/faddr, all is good. However, if the local port selection
results in a
full conflict it will get rejected by the call to in_pcblookup_hash() inside
in_pcbconnect_setup(). This happens after the loop inside
in_pcbbind(), so the call to tcp_connect() fails with EADDRINUSE. Thus,
with SO_REUSEADDR, connect() can fail with EADDRINUSE long before
the ephemeral port space has been exhausted. The application could re-try
the call to connect() and likely succeed, as a new local port would be
selected.

Python's http.server.HTTPServer does set SO_REUSEADDR (Azure/azure-cli#10955 (comment)), so there is still a very small chance that race condition may happen between bind and listen.