Revisiting custom authentication.

[tomchristie]

Let's have a go at simplifying our custom authentication API.

We have an existing API using generators and an "auth_flow". (Fantastic at the time, tho now the codebase has matured, I think? can be simplified.)

I assume the following base API would be sufficient for almost all authentication use-cases...

class Auth:
    def authenticate_request(request: Request) -> Request:
        # Most authentication schemes only need to override this method.
        return request 

    def authenticate_response(response: Response) -> Request | None:
        # Challenge-response authentication schemes may override this method,
        # Allows a second request to optionally be made, once a server challenge is received.
        return None

It's feasible that there are might(???) be some exceptional cases where this might not be sufficient, but we have a "Transport API" that allows completely customising the entire request/response implementation. That'd be adequate for anyone needing to implement an oddball multi-stage authentication scheme.

Moderately involved, tho likely still suitable for a new contributor to deal with.

Checklist...

• Update the base Auth class as above.
• Update the BasicAuth, DigestAuth and NetRCAuth classes to use the new API.
• Update the auth handling in _client.py.
• Update the documentation.
• Update tests as required.

Simplicity ftw.

[tomchristie]

(Some potentially subtleties around dealing with async cases, let's talk those through as we get there.)

[da1910]

I don't know if we managed to get to the bottom of how we can support Channel Binding in Negotiate authentication. That's likely one of the edge cases where we do need more information.

This KB article explains how it works, somewhat but the gist is that you need to access information from the SSL connection and include it in the authentication flow.

There are plenty of enterprise apps that make use of Kerberos/Windows Authentication and it would be nice if we could support those with httpx, at the moment it's a blocker for adoption if you have to work with these services.

[KalleDK]

One of the shortfalls I keep stumpling in (it might just be me). Is the lack of access to the build_request from the client.

Timeout / Baseurl / Cookies / etc

What I use today (shortened and stuff omitted), but I have the hen / egg problem with the client part

class IPMIAuth(httpx.Auth):
    requires_response_body = True

    def __init__(self, basic_auth: str):
        self.basic_auth = basic_auth
        self.csrf_token: str | None = None
        self._client: httpx.Client | httpx.AsyncClient | None = None

    @property
    def client(self) -> httpx.Client | httpx.AsyncClient:
        if self._client is None:
            raise Exception("client not set")
        return self._client

    @client.setter
    def client(self, value: httpx.Client | httpx.AsyncClient):
        self._client = value

    def auth_flow(self, request: httpx.Request) -> Generator[httpx.Request, httpx.Response, None]:
        if self.csrf_token is None:
            response = yield self.client.build_request(
                "GET", "cgi/login.cgi", headers={"Authorization": f"Basic {self.basic_auth}"}
            )

            self.csrf_token = self._get_csrf_token(response)

        request.headers["CSRF_TOKEN"] = self.csrf_token

        yield request