| Name | aiohttp-oauth2-client JSON |
| Version |
1.0.2
JSON |
| download |
| home_page | None |
| Summary | OAuth2 support for aiohttp client |
| upload_time | 2024-06-25 06:54:37 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | None |
| keywords |
oauth2
aiohttp
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# `aiohttp-oauth2-client`: OAuth2 support for `aiohttp` client
This package adds support for OAuth 2.0 authorization to the `ClientSession` class of
the [`aiohttp`](https://docs.aiohttp.org/en/stable/) library.
It handles retrieving access tokens and injects them in the Authorization header of HTTP requests as a Bearer token.
**Features**:
* Ease of use
* Supported OAuth2 grants:
* [Resource Owner Password Credentials](https://datatracker.ietf.org/doc/html/rfc6749#section-4.3)
* [Client Credentials](https://datatracker.ietf.org/doc/html/rfc6749#section-4.4)
* [Authorization Code (+ PKCE)](https://datatracker.ietf.org/doc/html/rfc6749#section-4.1)
* [Device Code (+ PKCE)](https://datatracker.ietf.org/doc/html/rfc8628)
* Automatic (lazy) refresh of tokens
* Extensible code architecture
## Installation
The pacakge is available on [PyPi](https://pypi.org/project/aiohttp-oauth2-client) and can be installed using `pip`:
```shell
pip install aiohttp-oauth2-client
```
## Usage
Begin by importing the relevant modules, like the OAuth2 client and grant. Also import `asyncio` for running async code:
```python
import asyncio
from aiohttp_oauth2_client.client import OAuth2Client
from aiohttp_oauth2_client.grant.device_code import DeviceCodeGrant
```
Then create an `OAuth2Grant` and `OAuth2Client` object and perform a HTTP request to a protected resource. We use the
Device Code grant in this example:
```python
async def main():
async with DeviceCodeGrant(
token_url=TOKEN_URL,
device_authorization_url=DEVICE_AUTHORIZATION_URL,
client_id=CLIENT_ID,
pkce=True
) as grant, OAuth2Client(grant) as client:
async with client.get(PROTECTED_ENDPOINT) as response:
assert response.ok
print(await response.text())
asyncio.run(main())
```
The client and grant objects can be used as async context managers. This ensures the proper setup and cleanup of
associated resources.
### Grant configuration
This section provides an overview of the configuration options for each grant type.
Extra parameters can be provided, which will then be used in the authorization process.
#### Authorization code grant
The authorization code grant uses a web browser login to request an authorization code, which is then used to request an
access token.
##### Parameters
| Parameter | Required | Description |
|---------------------|----------|-----------------------------|
| `token_url` | Yes | OAuth 2.0 Token URL |
| `authorization_url` | Yes | OAuth 2.0 Authorization URL |
| `client_id` | Yes | client identifier |
| `token` | No | OAuth 2.0 Token |
| `pkce` | No | use PKCE |
##### Example
```python
from aiohttp_oauth2_client.client import OAuth2Client
from aiohttp_oauth2_client.grant.authorization_code import AuthorizationCodeGrant
...
async with AuthorizationCodeGrant(
token_url="https://sso.example.com/oauth2/token",
authorization_url="https://sso.example.com/oauth2/auth",
client_id="public",
pkce=True
) as grant, OAuth2Client(grant) as client:
...
```
#### Client credentials grant
Use client credentials to obtain an access token.
##### Parameters
| Parameter | Required | Description |
|-----------------|----------|---------------------|
| `token_url` | Yes | OAuth 2.0 Token URL |
| `client_id` | Yes | client identifier |
| `client_secret` | Yes | client secret |
| `token` | No | OAuth 2.0 token |
##### Example
```python
from aiohttp_oauth2_client.client import OAuth2Client
from aiohttp_oauth2_client.grant.client_credentials import ClientCredentialsGrant
...
async with ClientCredentialsGrant(
token_url="https://sso.example.com/oauth2/token",
client_id="my-client",
client_secret="top-secret"
) as grant, OAuth2Client(grant) as client:
...
```
#### Device code grant
Obtain user authorization on devices with limited input capabilities or lack a suitable browser to handle an interactive
log in procedure.
The user is instructed to review the authorization request on a secondary device, which does have the requisite input
and browser capabilities to complete the user interaction.
##### Parameters
| Parameter | Required | Description |
|----------------------------|----------|------------------------------------|
| `token_url` | Yes | OAuth 2.0 Token URL |
| `device_authorization_url` | Yes | OAuth 2.0 Device Authorization URL |
| `client_id` | Yes | client identifier |
| `token` | No | OAuth 2.0 Token |
| `pkce` | No | use PKCE |
##### Example
```python
from aiohttp_oauth2_client.client import OAuth2Client
from aiohttp_oauth2_client.grant.device_code import DeviceCodeGrant
...
async with DeviceCodeGrant(
token_url="https://sso.example.com/oauth2/token",
device_authorization_url="https://sso.example.com/oauth2/auth/device",
client_id="public",
pkce=True
) as grant, OAuth2Client(grant) as client:
...
```
#### Resource owner password credentials grant
Use the username and password of the resource owner to obtain an access token.
##### Parameters
| Parameter | Required | Description |
|-------------|----------|--------------------------------|
| `token_url` | Yes | OAuth 2.0 Token URL |
| `username` | Yes | username of the resource owner |
| `password` | Yes | password of the resource owner |
| `token` | No | OAuth 2.0 Token |
##### Example
```python
from aiohttp_oauth2_client.client import OAuth2Client
from aiohttp_oauth2_client.grant.resource_owner_password_credentials import ResourceOwnerPasswordCredentialsGrant
...
async with ResourceOwnerPasswordCredentialsGrant(
token_url="https://sso.example.com/oauth2/token",
username="username",
password="password123",
client_id="public"
) as grant, OAuth2Client(grant) as client:
...
```
## Development
To start developing on this project, you should install all needed dependencies for running and testing the code:
```shell
pip install -e .[dev]
```
This will also install linting and formatting tools, which can be automatically executed when you commit using Git.
To set up pre-commit as a Git hook, run:
```shell
pre-commit install
```
You can also run the pre-commit checks manually with the following command:
```shell
pre-commit run --all-files
```
### Build the docs
This repository uses Sphinx to generate documentation for the Python package.
To build the documentation, first install the required dependencies via the extra `docs`:
```shell
pip install -e .[docs]
```
Then go to the documentation directory and build the docs:
```shell
cd docs/
make html
```
Raw data
{
"_id": null,
"home_page": null,
"name": "aiohttp-oauth2-client",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "oauth2, aiohttp",
"author": null,
"author_email": "Stijn Caerts <stijn.caerts@vito.be>",
"download_url": "https://files.pythonhosted.org/packages/df/ce/4c288248ff0dc0368fae87f7013650ed806f6acfb7309f01a532f4575058/aiohttp_oauth2_client-1.0.2.tar.gz",
"platform": null,
"description": "# `aiohttp-oauth2-client`: OAuth2 support for `aiohttp` client\n\nThis package adds support for OAuth 2.0 authorization to the `ClientSession` class of\nthe [`aiohttp`](https://docs.aiohttp.org/en/stable/) library.\nIt handles retrieving access tokens and injects them in the Authorization header of HTTP requests as a Bearer token.\n\n**Features**:\n\n* Ease of use\n* Supported OAuth2 grants:\n * [Resource Owner Password Credentials](https://datatracker.ietf.org/doc/html/rfc6749#section-4.3)\n * [Client Credentials](https://datatracker.ietf.org/doc/html/rfc6749#section-4.4)\n * [Authorization Code (+ PKCE)](https://datatracker.ietf.org/doc/html/rfc6749#section-4.1)\n * [Device Code (+ PKCE)](https://datatracker.ietf.org/doc/html/rfc8628)\n* Automatic (lazy) refresh of tokens\n* Extensible code architecture\n\n## Installation\n\nThe pacakge is available on [PyPi](https://pypi.org/project/aiohttp-oauth2-client) and can be installed using `pip`:\n\n```shell\npip install aiohttp-oauth2-client\n``` \n\n## Usage\n\nBegin by importing the relevant modules, like the OAuth2 client and grant. Also import `asyncio` for running async code:\n\n```python\nimport asyncio\nfrom aiohttp_oauth2_client.client import OAuth2Client\nfrom aiohttp_oauth2_client.grant.device_code import DeviceCodeGrant\n```\n\nThen create an `OAuth2Grant` and `OAuth2Client` object and perform a HTTP request to a protected resource. We use the\nDevice Code grant in this example:\n\n```python\nasync def main():\n async with DeviceCodeGrant(\n token_url=TOKEN_URL,\n device_authorization_url=DEVICE_AUTHORIZATION_URL,\n client_id=CLIENT_ID,\n pkce=True\n ) as grant, OAuth2Client(grant) as client:\n async with client.get(PROTECTED_ENDPOINT) as response:\n assert response.ok\n print(await response.text())\n\n\nasyncio.run(main())\n```\n\nThe client and grant objects can be used as async context managers. This ensures the proper setup and cleanup of\nassociated resources.\n\n### Grant configuration\n\nThis section provides an overview of the configuration options for each grant type.\nExtra parameters can be provided, which will then be used in the authorization process.\n\n#### Authorization code grant\n\nThe authorization code grant uses a web browser login to request an authorization code, which is then used to request an\naccess token.\n\n##### Parameters\n\n| Parameter | Required | Description |\n|---------------------|----------|-----------------------------|\n| `token_url` | Yes | OAuth 2.0 Token URL |\n| `authorization_url` | Yes | OAuth 2.0 Authorization URL | \n| `client_id` | Yes | client identifier |\n| `token` | No | OAuth 2.0 Token | \n| `pkce` | No | use PKCE | \n\n##### Example\n\n```python\nfrom aiohttp_oauth2_client.client import OAuth2Client\nfrom aiohttp_oauth2_client.grant.authorization_code import AuthorizationCodeGrant\n\n...\n\nasync with AuthorizationCodeGrant(\n token_url=\"https://sso.example.com/oauth2/token\",\n authorization_url=\"https://sso.example.com/oauth2/auth\",\n client_id=\"public\",\n pkce=True\n) as grant, OAuth2Client(grant) as client:\n ...\n```\n\n#### Client credentials grant\n\nUse client credentials to obtain an access token.\n\n##### Parameters\n\n| Parameter | Required | Description |\n|-----------------|----------|---------------------|\n| `token_url` | Yes | OAuth 2.0 Token URL | \n| `client_id` | Yes | client identifier |\n| `client_secret` | Yes | client secret |\n| `token` | No | OAuth 2.0 token |\n\n##### Example\n\n```python\nfrom aiohttp_oauth2_client.client import OAuth2Client\nfrom aiohttp_oauth2_client.grant.client_credentials import ClientCredentialsGrant\n\n...\n\nasync with ClientCredentialsGrant(\n token_url=\"https://sso.example.com/oauth2/token\",\n client_id=\"my-client\",\n client_secret=\"top-secret\"\n) as grant, OAuth2Client(grant) as client:\n ...\n```\n\n#### Device code grant\n\nObtain user authorization on devices with limited input capabilities or lack a suitable browser to handle an interactive\nlog in procedure.\nThe user is instructed to review the authorization request on a secondary device, which does have the requisite input\nand browser capabilities to complete the user interaction.\n\n##### Parameters\n\n| Parameter | Required | Description | \n|----------------------------|----------|------------------------------------|\n| `token_url` | Yes | OAuth 2.0 Token URL |\n| `device_authorization_url` | Yes | OAuth 2.0 Device Authorization URL |\n| `client_id` | Yes | client identifier |\n| `token` | No | OAuth 2.0 Token | \n| `pkce` | No | use PKCE |\n\n##### Example\n\n```python\nfrom aiohttp_oauth2_client.client import OAuth2Client\nfrom aiohttp_oauth2_client.grant.device_code import DeviceCodeGrant\n\n...\n\nasync with DeviceCodeGrant(\n token_url=\"https://sso.example.com/oauth2/token\",\n device_authorization_url=\"https://sso.example.com/oauth2/auth/device\",\n client_id=\"public\",\n pkce=True\n) as grant, OAuth2Client(grant) as client:\n ...\n```\n\n#### Resource owner password credentials grant\n\nUse the username and password of the resource owner to obtain an access token.\n\n##### Parameters\n\n| Parameter | Required | Description |\n|-------------|----------|--------------------------------|\n| `token_url` | Yes | OAuth 2.0 Token URL |\n| `username` | Yes | username of the resource owner |\n| `password` | Yes | password of the resource owner |\n| `token` | No | OAuth 2.0 Token |\n\n##### Example\n\n```python\nfrom aiohttp_oauth2_client.client import OAuth2Client\nfrom aiohttp_oauth2_client.grant.resource_owner_password_credentials import ResourceOwnerPasswordCredentialsGrant\n\n...\n\nasync with ResourceOwnerPasswordCredentialsGrant(\n token_url=\"https://sso.example.com/oauth2/token\",\n username=\"username\",\n password=\"password123\",\n client_id=\"public\"\n) as grant, OAuth2Client(grant) as client:\n ...\n```\n\n## Development\n\nTo start developing on this project, you should install all needed dependencies for running and testing the code:\n\n```shell\npip install -e .[dev]\n```\n\nThis will also install linting and formatting tools, which can be automatically executed when you commit using Git.\nTo set up pre-commit as a Git hook, run:\n\n```shell\npre-commit install\n```\n\nYou can also run the pre-commit checks manually with the following command:\n\n```shell\npre-commit run --all-files\n```\n\n### Build the docs\n\nThis repository uses Sphinx to generate documentation for the Python package.\nTo build the documentation, first install the required dependencies via the extra `docs`:\n\n```shell\npip install -e .[docs]\n```\n\nThen go to the documentation directory and build the docs:\n\n```shell\ncd docs/\nmake html\n```\n",
"bugtrack_url": null,
"license": null,
"summary": "OAuth2 support for aiohttp client",
"version": "1.0.2",
"project_urls": {
"Homepage": "https://github.com/VITObelgium/aiohttp-oauth2-client",
"Issues": "https://github.com/VITObelgium/aiohttp-oauth2-client/issues",
"Source": "https://github.com/VITObelgium/aiohttp-oauth2-client.git"
},
"split_keywords": [
"oauth2",
" aiohttp"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "420ec2500f07a6b8e79983ecda6acf43505c7f12cc53e6e940e8e46afc3f7a5a",
"md5": "fcba398ee48ca8ffa31270b1e716bcfd",
"sha256": "8137ae65d2b647308ac61a91c8e3ea4eec96f2f548aafaea1e6061df5554ae9e"
},
"downloads": -1,
"filename": "aiohttp_oauth2_client-1.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "fcba398ee48ca8ffa31270b1e716bcfd",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 19298,
"upload_time": "2024-06-25T06:54:36",
"upload_time_iso_8601": "2024-06-25T06:54:36.133775Z",
"url": "https://files.pythonhosted.org/packages/42/0e/c2500f07a6b8e79983ecda6acf43505c7f12cc53e6e940e8e46afc3f7a5a/aiohttp_oauth2_client-1.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "dfce4c288248ff0dc0368fae87f7013650ed806f6acfb7309f01a532f4575058",
"md5": "c6e486b6c9d723e719f7fef0aec615bf",
"sha256": "ccf2b40036ba85c18a857285b3f5bb5eb6c7edf09f6d6b0977d4c0ee9b7fe9c4"
},
"downloads": -1,
"filename": "aiohttp_oauth2_client-1.0.2.tar.gz",
"has_sig": false,
"md5_digest": "c6e486b6c9d723e719f7fef0aec615bf",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 15736,
"upload_time": "2024-06-25T06:54:37",
"upload_time_iso_8601": "2024-06-25T06:54:37.829176Z",
"url": "https://files.pythonhosted.org/packages/df/ce/4c288248ff0dc0368fae87f7013650ed806f6acfb7309f01a532f4575058/aiohttp_oauth2_client-1.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-06-25 06:54:37",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "VITObelgium",
"github_project": "aiohttp-oauth2-client",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "aiohttp-oauth2-client"
}
