From 981665acccc03c4be2e52c90610e1498f6014a1b Mon Sep 17 00:00:00 2001 From: faph Date: Sun, 16 Oct 2022 13:54:06 +0100 Subject: [PATCH] Add documentation section on client authentication (#6998) ## What do these changes do? Adds a dedicated section on client authentication using the `auth` argument for HTTP Basic Auth. Also explains how to configure other authentication flows including periodic renewal of credentials. ## Are there changes in behavior for the user? No. Just makes it easier for developers to access authentication `aiohttp` features. Avoids users asking questions like this: https://github.com/aio-libs/aiohttp/discussions/6908 ## Related issue number Issue #6915 ## Checklist - [x] I think the code is well written - [x] Unit tests for the changes exist - [x] Documentation reflects the changes - [x] If you provide code modification, please add yourself to `CONTRIBUTORS.txt` * The format is <Name> <Surname>. * Please keep alphabetical order, the file is sorted by names. - [x] Add a new news fragment into the `CHANGES` folder * name it `.` for example (588.bugfix) * if you don't have an `issue_id` change it to the pr id after creating the pr * ensure type is one of the following: * `.feature`: Signifying a new feature. * `.bugfix`: Signifying a bug fix. * `.doc`: Signifying a documentation improvement. * `.removal`: Signifying a deprecation or removal of public API. * `.misc`: A ticket has been closed, but it is not of interest to users. * Make sure to use full sentences with correct case and punctuation, for example: "Fix issue with non-ascii contents in doctest text files." Co-authored-by: Sam Bull --- CHANGES/6998.doc | 1 + docs/client_advanced.rst | 39 +++++++++++++++++++++++++++++++++++---- 2 files changed, 36 insertions(+), 4 deletions(-) create mode 100644 CHANGES/6998.doc diff --git a/CHANGES/6998.doc b/CHANGES/6998.doc new file mode 100644 index 00000000000..36d0a1260b2 --- /dev/null +++ b/CHANGES/6998.doc @@ -0,0 +1 @@ +Added documentation on client authentication and updating headers. -- by :user:`faph` diff --git a/docs/client_advanced.rst b/docs/client_advanced.rst index 02cda31e3f5..5cb71a959d1 100644 --- a/docs/client_advanced.rst +++ b/docs/client_advanced.rst @@ -52,19 +52,50 @@ directly as shown above, but it is more convenient to use special keyword await session.post(url, json={'example': 'text'}) -For *text/plain* :: +For ``text/plain``:: await session.post(url, data='Привет, Мир!') +Authentication +-------------- + +Instead of setting the ``Authorization`` header directly, +:class:`ClientSession` and individual request methods provide an ``auth`` +argument. An instance of :class:`BasicAuth` can be passed in like this:: + + auth = BasicAuth(login="...", password="...") + async with ClientSession(auth=auth) as session: + ... + +For other authentication flows, the ``Authorization`` header can be set +directly:: + + headers = {"Authorization": "Bearer eyJh...0M30"} + async with ClientSession(headers=headers) as session: + ... + +The authentication header for a session may be updated as and when required. +For example:: + + session.headers["Authorization"] = "Bearer eyJh...1OH0" + +Note that a *copy* of the headers dictionary is set as an attribute when +creating a :class:`ClientSession` instance (as a :class:`multidict.CIMultiDict` +object). Updating the original dictionary does not have any effect. + +In cases where the authentication header value expires periodically, an +:mod:`asyncio` task may be used to update the session's default headers in the +background. + .. note:: - ``Authorization`` header will be removed if you get redirected - to a different host or protocol, except the case when ``HTTP -> HTTPS`` + The ``Authorization`` header will be removed if you get redirected + to a different host or protocol, except the case when HTTP → HTTPS redirect is performed on the same host. .. versionchanged:: 4.0 - Started keeping the ``Authorization`` header during ``HTTP -> HTTPS`` + Started keeping the ``Authorization`` header during HTTP → HTTPS redirects when the host remains the same. Custom Cookies