aiohttp-oauth2-client


Nameaiohttp-oauth2-client JSON
Version 1.0.2 PyPI version JSON
download
home_pageNone
SummaryOAuth2 support for aiohttp client
upload_time2024-06-25 06:54:37
maintainerNone
docs_urlNone
authorNone
requires_python>=3.8
licenseNone
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"
}
        
Elapsed time: 0.29601s