Authentication for HTTPX

[!NOTE]
Version 1.0.0 will be released once httpx is considered as stable (release of 1.0.0).

However, current state can be considered as stable.

Provides authentication classes to be used with httpx authentication parameter.

Some of the supported authentication

Available authentication

• OAuth2
  • Authorization Code Flow
    • Okta
    • WakaTime
  • Authorization Code Flow with PKCE
    • Okta
  • Resource Owner Password Credentials flow
  • Client Credentials Flow
    • Okta
  • Implicit Flow
    • Microsoft Entra (Access Token)
    • Microsoft Entra (ID token)
    • Okta (Access Token)
    • Okta (ID token)
  • Managing token cache
  • Managing browser
• Amazon
• API key
  • In header
  • In query
• Basic
• Multiple authentication at once

OAuth 2

Most of OAuth2 flows are supported.

If the one you are looking for is not yet supported, feel free to ask for its implementation.

Authorization Code flow

Authorization Code Grant is implemented following rfc6749.

Use httpx_auth.OAuth2AuthorizationCode to configure this kind of authentication.

import httpx
from httpx_auth import OAuth2AuthorizationCode

with httpx.Client() as client:
    client.get('https://www.example.com', auth=OAuth2AuthorizationCode('https://www.authorization.url', 'https://www.token.url'))

Note:

• You can persist tokens thanks to the token cache.
• You can tweak web browser interaction thanks to the display settings.

Parameters

Any other parameter will be put as query parameter in the authorization URL and as body parameters in the token URL.

Usual extra parameters are:

Common providers

Most of OAuth2 Authorization Code Grant providers are supported.

If the one you are looking for is not yet supported, feel free to ask for its implementation.

Okta (OAuth2 Authorization Code)

Okta Authorization Code Grant providing access tokens is supported.

Use httpx_auth.OktaAuthorizationCode to configure this kind of authentication.

import httpx
from httpx_auth import OktaAuthorizationCode


okta = OktaAuthorizationCode(instance='testserver.okta-emea.com', client_id='54239d18-c68c-4c47-8bdd-ce71ea1d50cd')
with httpx.Client() as client:
    client.get('https://www.example.com', auth=okta)

Note:

• You can persist tokens thanks to the token cache.
• You can tweak web browser interaction thanks to the display settings.

Parameters

Any other parameter will be put as query parameter in the authorization URL.

Usual extra parameters are:

WakaTime (OAuth2 Authorization Code)

WakaTime Authorization Code Grant providing access tokens is supported.

Use httpx_auth.WakaTimeAuthorizationCode to configure this kind of authentication.

import httpx
from httpx_auth import WakaTimeAuthorizationCode


waka_time = WakaTimeAuthorizationCode(client_id="aPJQV0op6Pu3b66MWDi9b1wB", client_secret="waka_sec_0c5MB", scope="email")
with httpx.Client() as client:
    client.get('https://wakatime.com/api/v1/users/current', auth=waka_time)

Note:

• You can persist tokens thanks to the token cache.
• You can tweak web browser interaction thanks to the display settings.

Parameters

Any other parameter will be put as query parameter in the authorization URL.

Authorization Code Flow with Proof Key for Code Exchange

Proof Key for Code Exchange is implemented following rfc7636.

Use httpx_auth.OAuth2AuthorizationCodePKCE to configure this kind of authentication.

import httpx
from httpx_auth import OAuth2AuthorizationCodePKCE

with httpx.Client() as client:
    client.get('https://www.example.com', auth=OAuth2AuthorizationCodePKCE('https://www.authorization.url', 'https://www.token.url'))

Note:

• You can persist tokens thanks to the token cache.
• You can tweak web browser interaction thanks to the display settings.

Parameters

Any other parameter will be put as query parameter in the authorization URL and as body parameters in the token URL.

Usual extra parameters are:

Common providers

Most of OAuth2 Proof Key for Code Exchange providers are supported.

If the one you are looking for is not yet supported, feel free to ask for its implementation.

Okta (OAuth2 Proof Key for Code Exchange)

Okta Proof Key for Code Exchange providing access tokens is supported.

Use httpx_auth.OktaAuthorizationCodePKCE to configure this kind of authentication.

import httpx
from httpx_auth import OktaAuthorizationCodePKCE


okta = OktaAuthorizationCodePKCE(instance='testserver.okta-emea.com', client_id='54239d18-c68c-4c47-8bdd-ce71ea1d50cd')
with httpx.Client() as client:
    client.get('https://www.example.com', auth=okta)

Note:

• You can persist tokens thanks to the token cache.
• You can tweak web browser interaction thanks to the display settings.

Parameters

Any other parameter will be put as query parameter in the authorization URL and as body parameters in the token URL.

Usual extra parameters are:

Resource Owner Password Credentials flow

Resource Owner Password Credentials Grant is implemented following rfc6749.

Use httpx_auth.OAuth2ResourceOwnerPasswordCredentials to configure this kind of authentication.

import httpx
from httpx_auth import OAuth2ResourceOwnerPasswordCredentials

with httpx.Client() as client:
    client.get('https://www.example.com', auth=OAuth2ResourceOwnerPasswordCredentials('https://www.token.url', 'user name', 'user password'))

Note:

• You can persist tokens thanks to the token cache.

Parameters

Any other parameter will be put as body parameter in the token URL.

Common providers

Most of OAuth2 Resource Owner Password Credentials providers are supported.

If the one you are looking for is not yet supported, feel free to ask for its implementation.

Okta (OAuth2 Resource Owner Password Credentials)

Okta Resource Owner Password Credentials providing access tokens is supported.

Use httpx_auth.OktaResourceOwnerPasswordCredentials to configure this kind of authentication.

import httpx
from httpx_auth import OktaResourceOwnerPasswordCredentials


okta = OktaResourceOwnerPasswordCredentials(instance='testserver.okta-emea.com', username='user name', password='user password', client_id='54239d18-c68c-4c47-8bdd-ce71ea1d50cd', client_secret="0c5MB")
with httpx.Client() as client:
    client.get('https://www.example.com', auth=okta)

Note:

• You can persist tokens thanks to the token cache.

Parameters

Any other parameter will be put as body parameters in the token URL.

Client Credentials flow

Client Credentials Grant is implemented following rfc6749.

Use httpx_auth.OAuth2ClientCredentials to configure this kind of authentication.

import httpx
from httpx_auth import OAuth2ClientCredentials

with httpx.Client() as client:
    client.get('https://www.example.com', auth=OAuth2ClientCredentials('https://www.token.url', client_id='id', client_secret='secret'))

Note:

• You can persist tokens thanks to the token cache.

Parameters

Any other parameter will be put as body parameter in the token URL.

Common providers

Most of OAuth2 Client Credentials Grant providers are supported.

If the one you are looking for is not yet supported, feel free to ask for its implementation.

Okta (OAuth2 Client Credentials)

Okta Client Credentials Grant providing access tokens is supported.

Use httpx_auth.OktaClientCredentials to configure this kind of authentication.

import httpx
from httpx_auth import OktaClientCredentials


okta = OktaClientCredentials(instance='testserver.okta-emea.com', client_id='54239d18-c68c-4c47-8bdd-ce71ea1d50cd', client_secret="secret", scope=["scope1", "scope2"])
with httpx.Client() as client:
    client.get('https://www.example.com', auth=okta)

Note:

• You can persist tokens thanks to the token cache.

Parameters

Any other parameter will be put as query parameter in the token URL.

Implicit flow

Implicit Grant is implemented following rfc6749.

Use httpx_auth.OAuth2Implicit to configure this kind of authentication.

import httpx
from httpx_auth import OAuth2Implicit

with httpx.Client() as client:
    client.get('https://www.example.com', auth=OAuth2Implicit('https://www.authorization.url'))

Note:

• You can persist tokens thanks to the token cache.
• You can tweak web browser interaction thanks to the display settings.

Parameters

Any other parameter will be put as query parameter in the authorization URL.

Usual extra parameters are:

Common providers

Most of OAuth2 Implicit Grant providers are supported.

If the one you are looking for is not yet supported, feel free to ask for its implementation.

Microsoft - Azure Active Directory (OAuth2 Access Token)

Microsoft identity platform access tokens are supported.

Use httpx_auth.AzureActiveDirectoryImplicit to configure this kind of authentication.

import httpx
from httpx_auth import AzureActiveDirectoryImplicit


aad = AzureActiveDirectoryImplicit(tenant_id='45239d18-c68c-4c47-8bdd-ce71ea1d50cd', client_id='54239d18-c68c-4c47-8bdd-ce71ea1d50cd')
with httpx.Client() as client:
    client.get('https://www.example.com', auth=aad)

Note:

• You can persist tokens thanks to the token cache.
• You can tweak web browser interaction thanks to the display settings.

You can retrieve Microsoft Azure Active Directory application information thanks to the application list on Azure portal.

Parameters

Any other parameter will be put as query parameter in the authorization URL.

Usual extra parameters are:

Microsoft - Azure Active Directory (OpenID Connect ID token)

Microsoft identity platform ID tokens are supported.

Use httpx_auth.AzureActiveDirectoryImplicitIdToken to configure this kind of authentication.

import httpx
from httpx_auth import AzureActiveDirectoryImplicitIdToken


aad = AzureActiveDirectoryImplicitIdToken(tenant_id='45239d18-c68c-4c47-8bdd-ce71ea1d50cd', client_id='54239d18-c68c-4c47-8bdd-ce71ea1d50cd')
with httpx.Client() as client:
    client.get('https://www.example.com', auth=aad)

Note:

• You can persist tokens thanks to the token cache.
• You can tweak web browser interaction thanks to the display settings.

You can retrieve Microsoft Azure Active Directory application information thanks to the application list on Azure portal.

Parameters

Any other parameter will be put as query parameter in the authorization URL.

Usual extra parameters are:

Okta (OAuth2 Implicit Access Token)

Okta Implicit Grant providing access tokens is supported.

Use httpx_auth.OktaImplicit to configure this kind of authentication.

import httpx
from httpx_auth import OktaImplicit


okta = OktaImplicit(instance='testserver.okta-emea.com', client_id='54239d18-c68c-4c47-8bdd-ce71ea1d50cd')
with httpx.Client() as client:
    client.get('https://www.example.com', auth=okta)

Note:

• You can persist tokens thanks to the token cache.
• You can tweak web browser interaction thanks to the display settings.

Parameters

Any other parameter will be put as query parameter in the authorization URL.

Usual extra parameters are:

Okta (OpenID Connect Implicit ID token)

Okta Implicit Grant providing ID tokens is supported.

Use httpx_auth.OktaImplicitIdToken to configure this kind of authentication.

import httpx
from httpx_auth import OktaImplicitIdToken


okta = OktaImplicitIdToken(instance='testserver.okta-emea.com', client_id='54239d18-c68c-4c47-8bdd-ce71ea1d50cd')
with httpx.Client() as client:
    client.get('https://www.example.com', auth=okta)

Note:

• You can persist tokens thanks to the token cache.
• You can tweak web browser interaction thanks to the display settings.

Parameters

Any other parameter will be put as query parameter in the authorization URL.

Usual extra parameters are:

Managing token cache

To avoid asking for a new token every new request, a token cache is used.

Default cache is in memory, but it is also possible to use a physical cache.

You need to provide the location of your token cache file. It can be a full or relative path (str or pathlib.Path).

If the file already exists it will be used, if the file do not exist it will be created.

from httpx_auth import OAuth2, JsonTokenFileCache

OAuth2.token_cache = JsonTokenFileCache('path/to/my_token_cache.json')

Managing the web browser

Authentication response pages

You can configure the browser display settings thanks to httpx_auth.OAuth2.display as in the following:

from httpx_auth import OAuth2, DisplaySettings

OAuth2.display = DisplaySettings()

The following parameters can be provided to DisplaySettings:

Text-mode web browser

This project uses webbrowser.open() to open a web browser to support authentication flows like OAuth's Authorization Code grant. When running graphically, webbrowser.open() does not block. But when run in text mode, webbrowser.open() blocks until the opened browser is closed, which leads to a deadlock when httpx-auth cannot serve the auth response pages to the webbrowser. To work around this, you can specify a BROWSER environment variable that contains a %s and ends with a &, and the webbrowser module will open the text-mode browser in a subprocess and allow httpx-auth to serve the auth response pages to the browser without deadlocking.

BROWSER="/usr/bin/links %s &"

For more information, please see the implementation of webbrowser.get().

AWS Signature v4

Amazon Web Service Signature version 4 is implemented following Amazon S3 documentation and request-aws4auth 1.2.3 (with some changes, see below).

Use httpx_auth.AWS4Auth to configure this kind of authentication.

import httpx
from httpx_auth import AWS4Auth

aws = AWS4Auth(access_id="my-access-id", secret_key="my-secret-key", region="eu-west-1", service="s3")
with httpx.Client() as client:
    client.get('http://s3-eu-west-1.amazonaws.com', auth=aws)

Note that the following changes were made compared to requests-aws4auth:

• Each request now has its own signing key and x-amz-date. Meaning you can use the same auth instance for more than one request.
• session_token was renamed into security_token for consistency with the underlying name at Amazon.
• include_hdrs parameter was renamed into include_headers. When using this parameter:
  • Provided values will not be stripped, WYSIWYG.
  • If multiple values are provided for a same header, the computation will be based on the value order you provided and value separated by , . Instead of ordered values separated by comma for requests-aws4auth.
• amz_date attribute has been removed.
• It is not possible to provide a date. It will default to now.
• It is not possible to provide an AWSSigningKey instance, use explicit parameters instead.
• It is not possible to provide raise_invalid_date parameter anymore as the date will always be valid.
• host is not considered as a specific Amazon service anymore (no test specific code).
• Canonical query string computation is entirely based on AWS documentation (and consider undocumented fragment (# and following characters) as part of the query string).
• Canonical uri computation is entirely based on AWS documentation.
• Canonical headers computation is entirely based on AWS documentation.

Parameters

Dynamically retrieving credentials using boto3

While httpx-auth does not want to include support for botocore, the following authentication class should allow you to automatically retrieve up-to-date credentials.

import httpx
from botocore.session import Session
from httpx_auth import AWS4Auth

class AWS4BotoAuth(AWS4Auth):
    def __init__(self, region: str, service: str = "s3", **kwargs):
        self.refreshable_credentials = Session().get_credentials()
        AWS4Auth.__init__(self, access_id=kwargs.pop("access_id", "_"), secret_key=kwargs.pop("secret_key", "_"), region=region, service=service, **kwargs)

    def auth_flow(self, request):
        self.refresh_credentials()
        yield super().auth_flow(request)

    def refresh_credentials(self):
        credentials = self.refreshable_credentials.get_frozen_credentials()
        self.access_id = credentials.access_key
        self.secret_key = credentials.secret_key
        self.security_token = credentials.token


aws = AWS4BotoAuth(region="eu-west-1")
with httpx.Client() as client:
    client.get('http://s3-eu-west-1.amazonaws.com', auth=aws)

API key in header

You can send an API key inside the header of your request using httpx_auth.HeaderApiKey.

import httpx
from httpx_auth import HeaderApiKey

with httpx.Client() as client:
    client.get('https://www.example.com', auth=HeaderApiKey('my_api_key'))

Parameters

API key in query

You can send an API key inside the query parameters of your request using httpx_auth.QueryApiKey.

import httpx
from httpx_auth import QueryApiKey

with httpx.Client() as client:
    client.get('https://www.example.com', auth=QueryApiKey('my_api_key'))

Parameters

Basic

You can use basic authentication using httpx_auth.Basic.

The only advantage of using this class instead of httpx native support of basic authentication, is to be able to use it in multiple authentication.

import httpx
from httpx_auth import Basic

with httpx.Client() as client:
    client.get('https://www.example.com', auth=Basic('username', 'password'))

Parameters

Multiple authentication at once

You can also use a combination of authentication using +or & as in the following sample:

import httpx
from httpx_auth import HeaderApiKey, OAuth2Implicit

api_key = HeaderApiKey('my_api_key')
oauth2 = OAuth2Implicit('https://www.example.com')
with httpx.Client() as client:
    client.get('https://www.example.com', auth=api_key + oauth2)

This is supported on every authentication class exposed by httpx_auth, but you can also enable it on your own authentication classes by using httpx_auth.SupportMultiAuth as in the following sample:

from httpx_auth import SupportMultiAuth
# TODO Import your own auth here
from my_package import MyAuth

class MyMultiAuth(MyAuth, SupportMultiAuth):
    pass

Available pytest fixtures

Testing the code using httpx_auth authentication classes can be achieved using provided pytest fixtures.

token_cache_mock

from httpx_auth.testing import token_cache_mock, token_mock

def test_something(token_cache_mock):
    # perform code using authentication
    pass

Use this fixture to mock authentication success for any of the following classes:

• OAuth2AuthorizationCodePKCE
• OktaAuthorizationCodePKCE
• OAuth2Implicit
• OktaImplicit
• OktaImplicitIdToken
• AzureActiveDirectoryImplicit
• AzureActiveDirectoryImplicitIdToken
• OAuth2AuthorizationCode
• OktaAuthorizationCode
• WakaTimeAuthorizationCode
• OAuth2ClientCredentials
• OktaClientCredentials
• OAuth2ResourceOwnerPasswordCredentials
• OktaResourceOwnerPasswordCredentials

By default, an access token with value 2YotnFZFEjr1zCsicMWpAA is generated.

You can however return your custom token by providing your own token_mock fixture as in the following sample:

import pytest

from httpx_auth.testing import token_cache_mock


@pytest.fixture
def token_mock() -> str:
    return "MyCustomTokenValue"


def test_something(token_cache_mock):
    # perform code using authentication
    pass

You can even return a more complex token by using the create_token function.

Note that pyjwt is a required dependency in this case as it is used to generate the token returned by the authentication.

import pytest
from httpx_auth.testing import token_cache_mock, create_token


@pytest.fixture
def token_mock() -> str:
    expiry = None  # TODO Compute your expiry
    return create_token(expiry)


def test_something(token_cache_mock):
    # perform code using authentication
    pass

Advanced testing

token_cache

This pytest fixture will return the token cache and ensure it is reset at the end of the test case.

from httpx_auth.testing import token_cache

def test_something(token_cache):
    # perform code using authentication
    pass

browser_mock

This pytest fixture will allow to mock the behavior of a web browser.

With this pytest fixture you will be allowed to fine tune your authentication related failures handling.

pyjwt is a required dependency if you use create_token helper function.

import datetime

from httpx_auth.testing import browser_mock, BrowserMock, create_token

def test_something(browser_mock: BrowserMock):
    token_expiry = datetime.datetime.now(datetime.timezone.utc) + datetime.timedelta(hours=1)
    token = create_token(token_expiry)
    tab = browser_mock.add_response(
        opened_url="http://url_opened_by_browser?state=1234",
        reply_url=f"http://localhost:5000#access_token={token}&state=1234",
    )

    # perform code using authentication

    tab.assert_success()