Authlib: Python Authentication¶

Monolithic¶

Authlib is a monolithic library. While being monolithic, it keeps everything synchronized, from spec implementation to framework integrations, from client requests to service providers.

The benefits are obvious; it won’t break things. When specifications changed, implementation will change too. Let the developers of Authlib take the pain, users of Authlib should not suffer from it.

You don’t have to worry about monolithic, it doesn’t cost your memory. If you don’t import a module, it won’t be loaded. We don’t madly import everything into the root __init__.py.

Extendable¶

Authlib is designed as flexible as possible. Since it is built from low-level specification implementation to high-level framework integrations, if a high level can’t meet your needs, you can always create one for your purpose based on the low-level implementation.

Most of the cases, you don’t need to do so. Extendable has been taken into account from the start of the project. Take OAuth 2.0 server as an example, instead of a pre-configured server, Authlib takes advantage of register.

authorization_server.register_grant(AuthorizationCodeGrant)
authorization_server.register_endpoint(RevocationEndpoint)

If you find anything not that extendable, you can ask help on StackOverflow or open an issue on GitHub.

Credits¶

This project is inspired by:

• OAuthLib

• Flask-OAuthlib

• requests-oauthlib

• pyjwt

$ pip install Authlib¶

Installing Authlib is simple with pip:

$ pip install Authlib

It will also install the dependencies:

• cryptography

Using Authlib with requests:

$ pip install Authlib requests

Using Authlib with httpx:

$ pip install Authlib httpx

Using Authlib with Flask:

$ pip install Authlib Flask

Using Authlib with Django:

$ pip install Authlib Django

Using Authlib with Starlette:

$ pip install Authlib httpx Starlette

$ pip install Authlib requests

Get the Source Code¶

Authlib is actively developed on GitHub, where the code is always available.

You can either clone the public repository:

$ git clone git://github.com/lepture/authlib.git

Download the tarball:

$ curl -OL https://github.com/lepture/authlib/tarball/master

Or, download the zipball:

$ curl -OL https://github.com/lepture/authlib/zipball/master

Once you have a copy of the source, you can embed it in your Python package, or install it into your site-packages easily:

$ cd authlib
$ pip install .

Initialize OAuth 1.0 Client¶

There are three steps in OAuth 1 to obtain an access token:

1. fetch a temporary credential

2. visit the authorization page

3. exchange access token with the temporary credential

But first, we need to initialize an OAuth 1.0 client:

>>> client_id = 'Your Twitter client key'
>>> client_secret = 'Your Twitter client secret'
>>> # using requests client
>>> from authlib.integrations.requests_client import OAuth1Session
>>> client = OAuth1Session(client_id, client_secret)
>>> # using httpx client
>>> from authlib.integrations.httpx_client import AsyncOAuth1Client
>>> client = AsyncOAuth1Client(client_id, client_secret)

Fetch Temporary Credential¶

The first step is to fetch temporary credential, which will be used to generate authorization URL:

>>> request_token_url = 'https://api.twitter.com/oauth/request_token'
>>> request_token = client.fetch_request_token(request_token_url)
>>> print(request_token)
{'oauth_token': 'gA..H', 'oauth_token_secret': 'lp..X', 'oauth_callback_confirmed': 'true'}

Save this temporary credential for later use (if required).

You can assign a redirect_uri before fetching the request token, if you want to redirect back to another URL other than the one you registered:

>>> client.redirect_uri = 'https://your-domain.org/auth'
>>> client.fetch_request_token(request_token_url)

Redirect to Authorization Endpoint¶

The second step is to generate the authorization URL:

>>> authenticate_url = 'https://api.twitter.com/oauth/authenticate'
>>> client.create_authorization_url(authenticate_url, request_token['oauth_token'])
'https://api.twitter.com/oauth/authenticate?oauth_token=gA..H'

Actually, the second parameter request_token can be omitted, since session is re-used:

>>> client.create_authorization_url(authenticate_url)

Now visit the authorization url that create_authorization_url generated, and grant the authorization.

Fetch Access Token¶

When the authorization is granted, you will be redirected back to your registered callback URI. For instance:

https://example.com/twitter?oauth_token=gA..H&oauth_verifier=fcg..1Dq

If you assigned redirect_uri in Fetch Access Token, the authorize response would be something like:

https://your-domain.org/auth?oauth_token=gA..H&oauth_verifier=fcg..1Dq

Now fetch the access token with this response:

>>> resp_url = 'https://example.com/twitter?oauth_token=gA..H&oauth_verifier=fcg..1Dq'
>>> client.parse_authorization_response(resp_url)
>>> access_token_url = 'https://api.twitter.com/oauth/access_token'
>>> token = client.fetch_access_token(access_token_url)
>>> print(token)
{
    'oauth_token': '12345-st..E',
    'oauth_token_secret': 'o67..X',
    'user_id': '12345',
    'screen_name': 'lepture',
    'x_auth_expires': '0'
}
>>> save_access_token(token)

Save this token to access protected resources.

The above flow is not always what we will use in a real project. When we are redirected to authorization endpoint, our session is over. In this case, when the authorization server send us back to our server, we need to create another session:

>>> # restore your saved request token, which is a dict
>>> request_token = restore_request_token()
>>> oauth_token = request_token['oauth_token']
>>> oauth_token_secret = request_token['oauth_token_secret']
>>> from authlib.integrations.requests_client import OAuth1Session
>>> # if using httpx: from authlib.integrations.httpx_client import AsyncOAuth1Client
>>> client = OAuth1Session(
...     client_id, client_secret,
...     token=oauth_token,
...     token_secret=oauth_token_secret)
>>> # there is no need for `parse_authorization_response` if you can get `verifier`
>>> verifier = request.args.get('verifier')
>>> access_token_url = 'https://api.twitter.com/oauth/access_token'
>>> token = client.fetch_access_token(access_token_url, verifier)

Access Protected Resources¶

Now you can access the protected resources. If you re-use the session, you don’t need to do anything:

>>> account_url = 'https://api.twitter.com/1.1/account/verify_credentials.json'
>>> resp = client.get(account_url)
<Response [200]>
>>> resp.json()
{...}

The above is not the real flow, just like what we did in Fetch Access Token, we need to create another session ourselves:

>>> access_token = restore_access_token_from_database()
>>> oauth_token = access_token['oauth_token']
>>> oauth_token_secret = access_token['oauth_token_secret']
>>> # if using httpx: from authlib.integrations.httpx_client import AsyncOAuth1Client
>>> client = OAuth1Session(
...     client_id, client_secret,
...     token=oauth_token,
...     token_secret=oauth_token_secret)
>>> account_url = 'https://api.twitter.com/1.1/account/verify_credentials.json'
>>> resp = client.get(account_url)

Please note, there are duplicated steps in the documentation, read carefully and ignore the duplicated explains.

Using OAuth1Auth¶

It is also possible to access protected resources with OAuth1Auth object. Create an instance of OAuth1Auth with an access token:

# if using requests
from authlib.integrations.requests_client import OAuth1Auth

# if using httpx
from authlib.integrations.httpx_client import OAuth1Auth

auth = OAuth1Auth(
    client_id='..',
    client_secret=client_secret='..',
    token='oauth_token value',
    token_secret='oauth_token_secret value',
    ...
)

If using requests, pass this auth to access protected resources:

import requests

url = 'https://api.twitter.com/1.1/account/verify_credentials.json'
resp = requests.get(url, auth=auth)

If using httpx, pass this auth to access protected resources:

import httpx

url = 'https://api.twitter.com/1.1/account/verify_credentials.json'
resp = await httpx.get(url, auth=auth)

OAuth2Session for Authorization Code¶

There are two steps in OAuth 2 to obtain an access token with authorization code grant type. Initialize the session for reuse:

>>> client_id = 'Your GitHub client ID'
>>> client_secret = 'Your GitHub client secret'
>>> scope = 'user:email'  # we want to fetch user's email
>>>
>>> # using requests implementation
>>> from authlib.integrations.requests_client import OAuth2Session
>>> client = OAuth2Session(client_id, client_secret, scope=scope)
>>>
>>> # using httpx implementation
>>> from authlib.integrations.httpx_client import AsyncOAuth2Client
>>> client = AsyncOAuth2Client(client_id, client_secret, scope=scope)

You can assign a redirect_uri in case you want to specify the callback url.

>>> authorization_endpoint = 'https://github.com/login/oauth/authorize'
>>> uri, state = client.create_authorization_url(authorization_endpoint)
>>> print(uri)
https://github.com/login/oauth/authorize?response_type=code&client_id=c..id&scope=user%3Aemail&state=d..t

https://example.com/github?code=42..e9&state=d..t

>>> authorization_response = 'https://example.com/github?code=42..e9&state=d..t'
>>> token_endpoint = 'https://github.com/login/oauth/access_token'
>>> token = client.fetch_token(token_endpoint, authorization_response=authorization_response)
>>> print(token)
{
    'access_token': 'e..ad',
    'token_type': 'bearer',
    'scope': 'user:email'
}

>>> state = restore_previous_state()
>>>
>>> # using requests
>>> from authlib.integrations.requests_client import OAuth2Session
>>> client = OAuth2Session(client_id, client_secret, state=state)
>>>
>>> # using httpx
>>> from authlib.integrations.httpx_client import AsyncOAuth2Client
>>> client = AsyncOAuth2Client(client_id, client_secret, state=state)
>>>
>>> await client.fetch_token(token_endpoint, authorization_response=authorization_response)

>>> client = OAuth2Session(..., code_challenge_method='S256')
>>> code_verifier = generate_token(48)
>>> uri, state = client.create_authorization_url(authorization_endpoint, code_verifier=code_verifier)
>>> # ...
>>> token = client.fetch_token(..., code_verifier=code_verifier)

OAuth2Session for Implicit¶

OAuth2Session supports implicit grant type. It can fetch the access token with the response_type of token:

>>> uri, state = client.create_authorization_url(authorization_endpoint, response_type='token')
>>> print(uri)
https://some-service.com/oauth/authorize?response_type=token&client_id=be..4d&...

Visit this link, and grant the authorization, the OAuth authorization server will redirect back to your redirect_uri, the response url would be something like:

https://example.com/cb#access_token=2..WpA&state=xyz&token_type=bearer&expires_in=3600

Fetch access token from the fragment with .fetch_token method:

>>> token = client.fetch_token(authorization_response=authorization_response)
>>> # if you don't specify access token endpoint, it will fetch from fragment.
>>> print(token)
{'access_token': '2..WpA', 'token_type': 'bearer', 'expires_in': 3600}

OAuth2Session for Password¶

The password grant type is supported since Version 0.5. Use username and password to fetch the access token:

>>> token = client.fetch_token(token_endpoint, username='a-name', password='a-password')

OAuth2Session for Client Credentials¶

The client_credentials grant type is supported since Version 0.5. If no code or no user info provided, it would be a client_credentials request. But it is suggested that you specify a grant_type for it:

>>> token = client.fetch_token(token_endpoint)
>>> # or with grant_type
>>> token = client.fetch_token(token_endpoint, grant_type='client_credentials')

Client Authentication¶

When fetching access token, the authorization server will require a client authentication, Authlib provides three default methods defined by RFC7591:

• client_secret_basic

• client_secret_post

• none

The default value is client_secret_basic. You can change the auth method with token_endpoint_auth_method:

>>> client = OAuth2Session(token_endpoint_auth_method='client_secret_post')

If the authorization server requires other means of authentication, you can construct an auth for your own need, and pass it to fetch_token:

>>> auth = YourAuth(...)
>>> token = client.fetch_token(token_endpoint, auth=auth, ...)

It is also possible to extend the client authentication method with .register_client_auth_method. Besides the default three authentication methods, there are more provided by Authlib. e.g.

• client_secret_jwt

• private_key_jwt

These two methods are defined by RFC7523 and OpenID Connect. Find more in Using JWTs Client Assertion in OAuth2Session.

There are still cases that developers need to define a custom client authentication method. Take issue#158 as an example, the provider requires us put client_id and client_secret on URL when sending POST request:

POST /oauth/token?grant_type=code&code=...&client_id=...&client_secret=...

Let’s call this weird authentication method client_secret_uri, and this is how we can get our OAuth 2.0 client authenticated:

from authlib.common.urls import add_params_to_uri

def auth_client_secret_uri(client, method, uri, headers, body):
    uri = add_params_to_uri(uri, [
        ('client_id', client.client_id),
        ('client_secret', client.client_secret),
    ])
    uri = uri + '&' + body
    body = ''
    return uri, headers, body

client = OAuth2Session(
    'client_id', 'client_secret',
    token_endpoint_auth_method='client_secret_uri',
    ...
)
client.register_client_auth_method(('client_secret_uri', auth_client_secret_uri))

With client_secret_uri registered, OAuth 2.0 client will authenticate with the signed URI. It is also possible to assign the function to token_endpoint_auth_method directly:

client = OAuth2Session(
    'client_id', 'client_secret',
    token_endpoint_auth_method=auth_client_secret_uri,
)

Access Protected Resources¶

Now you can access the protected resources. If you re-use the session, you don’t need to do anything:

>>> account_url = 'https://api.github.com/user'
>>> resp = client.get(account_url)
<Response [200]>
>>> resp.json()
{...}

The above is not the real flow, just like what we did in Fetch Token, we need to create another session ourselves:

>>> token = restore_previous_token_from_database()
>>> # token is a dict which must contain ``access_token``, ``token_type``
>>> client = OAuth2Session(client_id, client_secret, token=token)
>>> account_url = 'https://api.github.com/user'
>>> resp = client.get(account_url)

Refresh & Auto Update Token¶

It is possible that your previously saved token is expired when accessing protected resources. In this case, we can refresh the token manually, or even better, Authlib will refresh the token automatically and update the token for us.

>>> openid_configuration = requests.get("https://example.org/.well-known/openid-configuration").json()
>>> session = OAuth2Session(…, token_endpoint=openid_configuration["token_endpoint"])

>>> token = restore_previous_token_from_database()
>>> new_token = client.refresh_token(token_endpoint, refresh_token=token.refresh_token)

def update_token(token, refresh_token=None, access_token=None):
    if refresh_token:
        item = OAuth2Token.find(name=name, refresh_token=refresh_token)
    elif access_token:
        item = OAuth2Token.find(name=name, access_token=access_token)
    else:
        return

    # update old token
    item.access_token = token['access_token']
    item.refresh_token = token.get('refresh_token')
    item.expires_at = token['expires_at']
    item.save()

client = OAuth2Session(client_id, client_secret, update_token=update_token)

token = restore_previous_token_from_database()
client.token = token

# if the token is expired, this GET request will update token
client.get('https://openidconnect.googleapis.com/v1/userinfo')

Revoke and Introspect Token¶

If the provider support token revocation and introspection, you can revoke and introspect the token with:

token_endpoint = 'https://example.com/oauth/token'

token = get_your_previous_saved_token()
client.revoke_token(token_endpoint, token=token)
client.introspect_token(token_endpoint, token=token)

You can find the available parameters in API docs:

• requests_client.OAuth2Session.revoke_token()

• requests_client.OAuth2Session.introspect_token()

• httpx_client.AsyncOAuth2Client.revoke_token()

• httpx_client.AsyncOAuth2Client.introspect_token()

Compliance Fix for non Standard¶

There are services that claimed they are providing OAuth API, but with a little differences. Some services even return with the wrong Content Type. Compliance hooks are provided to solve those problems:

• access_token_response: invoked before token parsing.

• refresh_token_response: invoked before refresh token parsing.

• protected_request: invoked before making a request.

For instance, Stackoverflow MUST add a site parameter in query string to protect users’ resources. And stackoverflow’s response is not in JSON. Let’s fix it:

from authlib.common.urls import add_params_to_uri, url_decode

def _non_compliant_param_name(url, headers, data):
    params = {'site': 'stackoverflow'}
    url = add_params_to_uri(url, params)
    return url, headers, body

def _fix_token_response(resp):
    data = dict(url_decode(resp.text))
    data['token_type'] = 'Bearer'
    data['expires_in'] = int(data['expires'])
    resp.json = lambda: data
    return resp

session.register_compliance_hook(
    'protected_request', _non_compliant_param_name)
session.register_compliance_hook(
    'access_token_response', _fix_token_response)

If you find a non standard OAuth 2 services, and you can’t fix it. Please report it in GitHub issues.

OAuth 2 OpenID Connect¶

For services that support OpenID Connect, if a scope of openid is provided, the authorization server will return a value of id_token in response:

>>> client_id = 'Your Google client ID'
>>> client_secret = 'Your Google client secret'
>>> scope = 'openid email profile'
>>> # using requests
>>> client = OAuth2Session(client_id, client_secret, scope=scope)
>>> # using httpx
>>> client = AsyncOAuth2Client(client_id, client_secret, scope=scope)

The remote server may require other parameters for OpenID Connect requests, for instance, it may require a nonce parameter, in this case, you need to generate it yourself, and pass it to create_authorization_url:

>>> from authlib.common.security import generate_token
>>> # remember to save this nonce for verification
>>> nonce = generate_token()
>>> client.create_authorization_url(url, redirect_uri='xxx', nonce=nonce, ...)

At the last step of client.fetch_token, the return value contains a id_token:

>>> resp = session.fetch_token(...)
>>> print(resp['id_token'])

This id_token is a JWT text, it can not be used unless it is parsed. Authlib has provided tools for parsing and validating OpenID Connect id_token:

>>> from authlib.oidc.core import CodeIDToken
>>> from authlib.jose import jwt
>>> # GET keys from https://www.googleapis.com/oauth2/v3/certs
>>> claims = jwt.decode(resp['id_token'], keys, claims_cls=CodeIDToken)
>>> claims.validate()

Get deep inside with JsonWebToken and CodeIDToken. Learn how to validate JWT claims at JSON Web Token (JWT).

AssertionSession¶

AssertionSession is a Requests Session for Assertion Framework of OAuth 2.0 Authorization Grants. It is also know as service account. A configured AssertionSession with handle token authorization automatically, which means you can just use it.

Take Google Service Account as an example, with the information in your service account JSON configure file:

import json
from authlib.integrations.requests_client import AssertionSession

with open('MyProject-1234.json') as f:
    conf = json.load(f)

token_uri = conf['token_uri']
header = {'alg': 'RS256'}
key_id = conf.get('private_key_id')
if key_id:
    header['kid'] = key_id

# Google puts scope in payload
claims = {'scope': scope}

session = AssertionSession(
    token_endpoint=token_uri,
    issuer=conf['client_email'],
    audience=token_uri,
    claims=claims,
    subject=None,
    key=conf['private_key'],
    header=header,
)
session.get(...)
session.post(...)

There is a ready to use GoogleServiceAccount in loginpass. You can also read these posts:

• Access Google Analytics API.

• Using Authlib with gspread.

Requests OAuth 1.0¶

There are three steps in OAuth 1 Session to obtain an access token:

1. fetch a temporary credential

2. visit the authorization page

3. exchange access token with the temporary credential

It shares a common API design with OAuth for HTTPX.

auth = OAuth1Auth(
    client_id='YOUR-CLIENT-ID',
    client_secret='YOUR-CLIENT-SECRET',
    token='oauth_token',
    token_secret='oauth_token_secret',
)
requests.get(url, auth=auth)

Requests OAuth 2.0¶

In OAuth 2 Session, there are many grant types, including:

1. Authorization Code Flow

2. Implicit Flow

3. Password Flow

4. Client Credentials Flow

And also, Authlib supports non Standard OAuth 2.0 providers via Compliance Fix.

Follow the common guide of OAuth 2 Session to find out how to use requests integration of OAuth 2.0 flow.

from authlib.integrations.requests_client import OAuth2Session
from authlib.oauth2.rfc7523 import ClientSecretJWT

token_endpoint = 'https://example.com/oauth/token'
session = OAuth2Session(
    'your-client-id', 'your-client-secret',
    token_endpoint_auth_method=ClientSecretJWT(token_endpoint),
)
session.fetch_token(token_endpoint)

from authlib.integrations.requests_client import OAuth2Session
from authlib.oauth2.rfc7523 import PrivateKeyJWT

with open('your-private-key.pem', 'rb') as f:
    private_key = f.read()

token_endpoint = 'https://example.com/oauth/token'
session = OAuth2Session(
    'your-client-id', private_key,
    token_endpoint_auth_method=PrivateKeyJWT(token_endpoint),
)
session.fetch_token(token_endpoint)

token = {'token_type': 'bearer', 'access_token': '....', ...}
auth = OAuth2Auth(token)
requests.get(url, auth=auth)

Requests OpenID Connect¶

OpenID Connect is built on OAuth 2.0. It is pretty simple to communicate with an OpenID Connect provider via Authlib. With Authlib built-in OAuth 2.0 system and JsonWebToken (JWT), parsing OpenID Connect id_token could be very easy.

Understand how it works with OAuth 2 OpenID Connect.

Requests Service Account¶

The Assertion Framework of OAuth 2.0 Authorization Grants is also known as service account. With the implementation of AssertionSession, we can easily integrate with a “assertion” service.

Checking out an example of Google Service Account with AssertionSession.

Close Session Hint¶

Developers SHOULD close a Requests Session when the jobs are done. You can call .close() manually, or use a with context to automatically close the session:

session = OAuth2Session(client_id, client_secret)
session.get(url)
session.close()

with OAuth2Session(client_id, client_secret) as session:
    session.get(url)

Self-Signed Certificate¶

Self-signed certificate mutual-TLS method internet standard is defined in RFC8705 Section 2.2 .

For specifics development purposes only, you may need to disable SSL verification.

You can force all requests to disable SSL verification by setting your environment variable CURL_CA_BUNDLE="".

This solutions works because Python requests (and most of the packages) overwrites the default value for ssl verifications from environment variables CURL_CA_BUNDLE and REQUESTS_CA_BUNDLE.

This hack will only work with CURL_CA_BUNDLE, as you can see in requests/sessions.py

verify = (os.environ.get('REQUESTS_CA_BUNDLE')
or os.environ.get('CURL_CA_BUNDLE'))

Please remember to set the env variable only in you development environment.

HTTPX OAuth 1.0¶

There are three steps in OAuth 1 to obtain an access token:

1. fetch a temporary credential

2. visit the authorization page

3. exchange access token with the temporary credential

It shares a common API design with OAuth for Requests.

Read the common guide of OAuth 1 Session to understand the whole OAuth 1.0 flow.

HTTPX OAuth 2.0¶

In OAuth 2 Session, there are many grant types, including:

1. Authorization Code Flow

2. Implicit Flow

3. Password Flow

4. Client Credentials Flow

And also, Authlib supports non Standard OAuth 2.0 providers via Compliance Fix.

Read the common guide of OAuth 2 Session to understand the whole OAuth 2.0 flow.

from authlib.integrations.httpx_client import AsyncOAuth2Client
from authlib.oauth2.rfc7523 import ClientSecretJWT

client = AsyncOAuth2Client(
    'your-client-id', 'your-client-secret',
    token_endpoint_auth_method='client_secret_jwt'
)
token_endpoint = 'https://example.com/oauth/token'
client.register_client_auth_method(ClientSecretJWT(token_endpoint))
client.fetch_token(token_endpoint)

from authlib.integrations.httpx_client import AsyncOAuth2Client
from authlib.oauth2.rfc7523 import PrivateKeyJWT

with open('your-private-key.pem', 'rb') as f:
    private_key = f.read()

client = AsyncOAuth2Client(
    'your-client-id', private_key,
    token_endpoint_auth_method='private_key_jwt',
)
token_endpoint = 'https://example.com/oauth/token'
client.register_client_auth_method(PrivateKeyJWT(token_endpoint))
client.fetch_token(token_endpoint)

Async OAuth 1.0¶

The async version of AsyncOAuth1Client works the same as OAuth 1 Session, except that we need to add await when required:

# fetching request token
request_token = await client.fetch_request_token(request_token_url)

# fetching access token
access_token = await client.fetch_access_token(access_token_url)

# normal requests
await client.get(...)
await client.post(...)
await client.put(...)
await client.delete(...)

Async OAuth 2.0¶

The async version of AsyncOAuth2Client works the same as OAuth 2 Session, except that we need to add await when required:

# fetching access token
token = await client.fetch_token(token_endpoint, ...)

# normal requests
await client.get(...)
await client.post(...)
await client.put(...)
await client.delete(...)

async def update_token(token, refresh_token=None, access_token=None):
    if refresh_token:
        item = await OAuth2Token.find(name=name, refresh_token=refresh_token)
    elif access_token:
        item = await OAuth2Token.find(name=name, access_token=access_token)
    else:
        return

    # update old token
    item.access_token = token['access_token']
    item.refresh_token = token.get('refresh_token')
    item.expires_at = token['expires_at']
    await item.save()

Async Service Account¶

AsyncAssertionClient is the async version for Assertion Framework of OAuth 2.0 Authorization Grants. It is also know as service account. A configured AsyncAssertionClient will handle token authorization automatically, which means you can just use it.

Take Google Service Account as an example, with the information in your service account JSON configure file:

import json
from authlib.integrations.httpx_client import AsyncAssertionClient

with open('MyProject-1234.json') as f:
    conf = json.load(f)

token_uri = conf['token_uri']
header = {'alg': 'RS256'}
key_id = conf.get('private_key_id')
if key_id:
    header['kid'] = key_id

# Google puts scope in payload
claims = {'scope': scope}

async def main():
    client = AsyncAssertionClient(
        token_endpoint=token_uri,
        issuer=conf['client_email'],
        audience=token_uri,
        claims=claims,
        subject=None,
        key=conf['private_key'],
        header=header,
    )
    resp = await client.get(...)
    resp = await client.post(...)

Close Client Hint¶

Developers SHOULD close a HTTPX Session when the jobs are done. You can call .close() manually, or use a with context to automatically close the session:

client = OAuth2Client(client_id, client_secret)
client.get(url)
client.close()

with OAuth2Client(client_id, client_secret) as client:
    client.get(url)

For async OAuth Client, use await client.close():

client = AsyncOAuth2Client(client_id, client_secret)
await client.get(url)
await client.close()

async with AsyncOAuth2Client(client_id, client_secret) as client:
    await client.get(url)

Our Web OAuth Clients will close every session automatically, no need to worry.

Log In with OAuth 1.0¶

For instance, Twitter is an OAuth 1.0 service, you want your users to log in your website with Twitter.

The first step is register a remote application on the OAuth registry via oauth.register method:

oauth.register(
    name='twitter',
    client_id='{{ your-twitter-consumer-key }}',
    client_secret='{{ your-twitter-consumer-secret }}',
    request_token_url='https://api.twitter.com/oauth/request_token',
    request_token_params=None,
    access_token_url='https://api.twitter.com/oauth/access_token',
    access_token_params=None,
    authorize_url='https://api.twitter.com/oauth/authenticate',
    authorize_params=None,
    api_base_url='https://api.twitter.com/1.1/',
    client_kwargs=None,
)

The first parameter in register method is the name of the remote application. You can access the remote application with:

twitter = oauth.create_client('twitter')
# or simply with
twitter = oauth.twitter

The configuration of those parameters can be loaded from the framework configuration. Each framework has its own config system, read the framework specified documentation later.

For instance, if client_id and client_secret can be loaded via configuration, we can simply register the remote app with:

oauth.register(
    name='twitter',
    request_token_url='https://api.twitter.com/oauth/request_token',
    access_token_url='https://api.twitter.com/oauth/access_token',
    authorize_url='https://api.twitter.com/oauth/authenticate',
    api_base_url='https://api.twitter.com/1.1/',
)

The client_kwargs is a dict configuration to pass extra parameters to OAuth 1 Session. If you are using RSA-SHA1 signature method:

client_kwargs = {
    'signature_method': 'RSA-SHA1',
    'signature_type': 'HEADER',
    'rsa_key': 'Your-RSA-Key'
}

def login(request):
    twitter = oauth.create_client('twitter')
    redirect_uri = 'https://example.com/authorize'
    return twitter.authorize_redirect(request, redirect_uri)

def authorize(request):
    twitter = oauth.create_client('twitter')
    token = twitter.authorize_access_token(request)
    resp = twitter.get('account/verify_credentials.json')
    resp.raise_for_status()
    profile = resp.json()
    # do something with the token and profile
    return '...'

Using OAuth 2.0 to Log In¶

For instance, GitHub is an OAuth 2.0 service, you want your users to log in your website with GitHub.

The first step is register a remote application on the OAuth registry via oauth.register method:

oauth.register(
    name='github',
    client_id='{{ your-github-client-id }}',
    client_secret='{{ your-github-client-secret }}',
    access_token_url='https://github.com/login/oauth/access_token',
    access_token_params=None,
    authorize_url='https://github.com/login/oauth/authorize',
    authorize_params=None,
    api_base_url='https://api.github.com/',
    client_kwargs={'scope': 'user:email'},
)

The first parameter in register method is the name of the remote application. You can access the remote application with:

github = oauth.create_client('github')
# or simply with
github = oauth.github

The configuration of those parameters can be loaded from the framework configuration. Each framework has its own config system, read the framework specified documentation later.

The client_kwargs is a dict configuration to pass extra parameters to OAuth 2 Session, you can pass extra parameters like:

client_kwargs = {
    'scope': 'profile',
    'token_endpoint_auth_method': 'client_secret_basic',
    'token_placement': 'header',
}

There are several token_endpoint_auth_method, get a deep inside the Client Authentication Methods.

def login(request):
    github = oauth.create_client('github')
    redirect_uri = 'https://example.com/authorize'
    return github.authorize_redirect(request, redirect_uri)

def authorize(request):
    token = oauth.github.authorize_access_token(request)
    resp = oauth.github.get('user', token=token)
    resp.raise_for_status()
    profile = resp.json()
    # do something with the token and profile
    return '...'

from authlib.oauth2.rfc7523 import ClientSecretJWT

oauth.register(
    'name',
    ...
    client_auth_methods=[
        ClientSecretJWT(token_endpoint),  # client_secret_jwt
    ]
)

oauth.register(
    'name',
    ...
    token_endpoint_auth_method=ClientSecretJWT(token_endpoint),
)

Accessing OAuth Resources¶

There are also chances that you need to access your user’s 3rd party OAuth provider resources. For instance, you want to display the logged in user’s twitter time line and GitHub repositories. You will use access token to fetch the resources:

def get_twitter_tweets(request):
    token = OAuth1Token.find(
        name='twitter',
        user=request.user
    )
    # API URL: https://api.twitter.com/1.1/statuses/user_timeline.json
    resp = oauth.twitter.get('statuses/user_timeline.json', token=token.to_token())
    resp.raise_for_status()
    return resp.json()

def get_github_repositories(request):
    token = OAuth2Token.find(
        name='github',
        user=request.user
    )
    # API URL: https://api.github.com/user/repos
    resp = oauth.github.get('user/repos', token=token.to_token())
    resp.raise_for_status()
    return resp.json()

In this case, we need a place to store the access token in order to use it later. Usually we will save the token into database. In the previous Routes for Authorization authorize part, we can save the token into database.

class OAuth1Token(Model):
    name = String(length=40)
    oauth_token = String(length=200)
    oauth_token_secret = String(length=200)
    user = ForeignKey(User)

    def to_token(self):
        return dict(
            oauth_token=self.access_token,
            oauth_token_secret=self.alt_token,
        )

class OAuth2Token(Model):
    name = String(length=40)
    token_type = String(length=40)
    access_token = String(length=200)
    refresh_token = String(length=200)
    expires_at = PositiveIntegerField()
    user = ForeignKey(User)

    def to_token(self):
        return dict(
            access_token=self.access_token,
            token_type=self.token_type,
            refresh_token=self.refresh_token,
            expires_at=self.expires_at,
        )

token = OAuth1Token.find(name='twitter', user=request.user)
oauth.twitter.get(url, token=token)
oauth.twitter.post(url, token=token)
oauth.twitter.put(url, token=token)
oauth.twitter.delete(url, token=token)

token = OAuth2Token.find(name='github', user=request.user)
oauth.github.get(url, token=token)
oauth.github.post(url, token=token)
oauth.github.put(url, token=token)
oauth.github.delete(url, token=token)

def fetch_twitter_token(request):
    token = OAuth1Token.find(
        name='twitter',
        user=request.user
    )
    return token.to_token()

def fetch_github_token(request):
    token = OAuth2Token.find(
        name='github',
        user=request.user
    )
    return token.to_token()

# we can registry this ``fetch_token`` with oauth.register
oauth.register(
    'twitter',
    # ...
    fetch_token=fetch_twitter_token,
)
oauth.register(
    'github',
    # ...
    fetch_token=fetch_github_token,
)

def fetch_token(name, request):
    if name in OAUTH1_SERVICES:
        model = OAuth1Token
    else:
        model = OAuth2Token

    token = model.find(
        name=name,
        user=request.user
    )
    return token.to_token()

# initialize OAuth registry with this fetch_token function
oauth = OAuth(fetch_token=fetch_token)

def get_twitter_tweets(request):
    resp = oauth.twitter.get('statuses/user_timeline.json', request=request)
    resp.raise_for_status()
    return resp.json()

OAuth 2.0 Enhancement¶

OAuth 1.0 is a protocol, while OAuth 2.0 is a framework. There are so many features in OAuth 2.0 than OAuth 1.0. This section is designed for OAuth 2.0 specially.

def update_token(name, token, refresh_token=None, access_token=None):
    if refresh_token:
        item = OAuth2Token.find(name=name, refresh_token=refresh_token)
    elif access_token:
        item = OAuth2Token.find(name=name, access_token=access_token)
    else:
        return

    # update old token
    item.access_token = token['access_token']
    item.refresh_token = token.get('refresh_token')
    item.expires_at = token['expires_at']
    item.save()

oauth = OAuth(update_token=update_token)

oauth.register(
    'example',
    client_id='Example Client ID',
    client_secret='Example Client Secret',
    access_token_url='https://example.com/oauth/access_token',
    authorize_url='https://example.com/oauth/authorize',
    api_base_url='https://api.example.com/',
    client_kwargs={'code_challenge_method': 'S256'},
)

def slack_compliance_fix(session):
    def _fix(resp):
        resp.raise_for_status()
        token = resp.json()
        # slack returns no token_type
        token['token_type'] = 'Bearer'
        resp._content = to_unicode(json.dumps(token)).encode('utf-8')
        return resp
    session.register_compliance_hook('access_token_response', _fix)

oauth.register(
    'slack',
    client_id='...',
    client_secret='...',
    ...,
    compliance_fix=slack_compliance_fix,
    ...
)

OpenID Connect & UserInfo¶

When logging in with OpenID Connect, “access_token” is not what developers want. Instead, what developers want is user info, Authlib wrap it with UserInfo.

There are two ways to fetch userinfo from 3rd party providers. If the provider supports OpenID Connect, we can get the user info from the returned id_token.

oauth.register(
    'google',
    client_id='...',
    client_secret='...',
    userinfo_endpoint='https://openidconnect.googleapis.com/v1/userinfo',
)

def authorize(request):
    token = oauth.google.authorize_access_token(request)
    user = oauth.google.userinfo(request)
    return '...'

oauth.register(
    'google',
    client_id='...',
    client_secret='...',
    server_metadata_url='https://accounts.google.com/.well-known/openid-configuration',
    client_kwargs={'scope': 'openid email profile'},
)

* authorize_url
* access_token_url
* jwks_uri

oauth.register(
    'google',
    client_id='...',
    client_secret='...',
    access_token_url='https://example.com/oauth/access_token',
    authorize_url='https://example.com/oauth/authorize',
    jwks={"keys": [...]}
)

Configuration¶

Authlib Flask OAuth registry can load the configuration from Flask app.config automatically. Every key value pair in .register can be omitted. They can be configured in your Flask App configuration. Config keys are formatted as {name}_{key} in uppercase, e.g.

If you register your remote app as oauth.register('example', ...), the config keys would look like:

Here is a full list of the configuration keys:

• {name}_CLIENT_ID: Client key of OAuth 1, or Client ID of OAuth 2

• {name}_CLIENT_SECRET: Client secret of OAuth 2, or Client Secret of OAuth 2

• {name}_REQUEST_TOKEN_URL: Request Token endpoint for OAuth 1

• {name}_REQUEST_TOKEN_PARAMS: Extra parameters for Request Token endpoint

• {name}_ACCESS_TOKEN_URL: Access Token endpoint for OAuth 1 and OAuth 2

• {name}_ACCESS_TOKEN_PARAMS: Extra parameters for Access Token endpoint

• {name}_AUTHORIZE_URL: Endpoint for user authorization of OAuth 1 ro OAuth 2

• {name}_AUTHORIZE_PARAMS: Extra parameters for Authorization Endpoint.

• {name}_API_BASE_URL: A base URL endpoint to make requests simple

• {name}_CLIENT_KWARGS: Extra keyword arguments for OAuth1Session or OAuth2Session

We suggest that you keep ONLY {name}_CLIENT_ID and {name}_CLIENT_SECRET in your Flask application configuration.

Using Cache for Temporary Credential¶

By default, Flask OAuth registry will use Flask session to store OAuth 1.0 temporary credential (request token). However in this way, there are chances your temporary credential will be exposed.

Our OAuth registry provides a simple way to store temporary credentials in a cache system. When initializing OAuth, you can pass an cache instance:

oauth = OAuth(app, cache=cache)

# or initialize lazily
oauth = OAuth()
oauth.init_app(app, cache=cache)

A cache instance MUST have methods:

• .get(key)

• .set(key, value, expires=None)

Routes for Authorization¶

Unlike the examples in Web OAuth Clients, Flask does not pass a request into routes. In this case, the routes for authorization should look like:

from flask import url_for, render_template

@app.route('/login')
def login():
    redirect_uri = url_for('authorize', _external=True)
    return oauth.twitter.authorize_redirect(redirect_uri)

@app.route('/authorize')
def authorize():
    token = oauth.twitter.authorize_access_token()
    resp = oauth.twitter.get('account/verify_credentials.json')
    resp.raise_for_status()
    profile = resp.json()
    # do something with the token and profile
    return redirect('/')

Accessing OAuth Resources¶

There is no request in accessing OAuth resources either. Just like above, we don’t need to pass request parameter, everything is handled by Authlib automatically:

from flask import render_template

@app.route('/github')
def show_github_profile():
    resp = oauth.github.get('user')
    resp.raise_for_status()
    profile = resp.json()
    return render_template('github.html', profile=profile)

In this case, our fetch_token could look like:

from your_project import current_user

def fetch_token(name):
    if name in OAUTH1_SERVICES:
        model = OAuth1Token
    else:
        model = OAuth2Token

    token = model.find(
        name=name,
        user=current_user,
    )
    return token.to_token()

# initialize OAuth registry with this fetch_token function
oauth = OAuth(fetch_token=fetch_token)

You don’t have to pass token, you don’t have to pass request. That is the fantasy of Flask.

Auto Update Token via Signal¶

Instead of define a update_token method and passing it into OAuth registry, it is also possible to use signal to listen for token updating.

Before using signal, make sure you have installed blinker library:

$ pip install blinker

Connect the token_update signal:

from authlib.integrations.flask_client import token_update

@token_update.connect_via(app)
def on_token_update(sender, name, token, refresh_token=None, access_token=None):
    if refresh_token:
        item = OAuth2Token.find(name=name, refresh_token=refresh_token)
    elif access_token:
        item = OAuth2Token.find(name=name, access_token=access_token)
    else:
        return

    # update old token
    item.access_token = token['access_token']
    item.refresh_token = token.get('refresh_token')
    item.expires_at = token['expires_at']
    item.save()

Flask OpenID Connect Client¶

An OpenID Connect client is no different than a normal OAuth 2.0 client. When register with openid scope, the built-in Flask OAuth client will handle everything automatically:

oauth.register(
    'google',
    ...
    server_metadata_url='https://accounts.google.com/.well-known/openid-configuration',
    client_kwargs={'scope': 'openid profile email'}
)

When we get the returned token:

token = oauth.google.authorize_access_token()

There should be a id_token in the response. Authlib has called .parse_id_token automatically, we can get userinfo in the token:

userinfo = token['userinfo']

Examples¶

Here are some example projects for you to learn Flask OAuth client integrations:

1. OAuth 1.0: Flask Twitter Login.

2. OAuth 2.0 & OpenID Connect: Flask Google Login.

Configuration¶

Authlib Django OAuth registry can load the configuration from your Django application settings automatically. Every key value pair can be omitted. They can be configured from your Django settings:

AUTHLIB_OAUTH_CLIENTS = {
    'twitter': {
        'client_id': 'Twitter Consumer Key',
        'client_secret': 'Twitter Consumer Secret',
        'request_token_url': 'https://api.twitter.com/oauth/request_token',
        'request_token_params': None,
        'access_token_url': 'https://api.twitter.com/oauth/access_token',
        'access_token_params': None,
        'refresh_token_url': None,
        'authorize_url': 'https://api.twitter.com/oauth/authenticate',
        'api_base_url': 'https://api.twitter.com/1.1/',
        'client_kwargs': None
    }
}

There are differences between OAuth 1.0 and OAuth 2.0, please check the parameters in .register in Web OAuth Clients.

Saving Temporary Credential¶

In OAuth 1.0, we need to use a temporary credential to exchange access token, this temporary credential was created before redirecting to the provider (Twitter), we need to save this temporary credential somewhere in order to use it later.

In OAuth 1, Django client will save the request token in sessions. In this case, you just need to configure Session Middleware in Django:

MIDDLEWARE = [
    'django.contrib.sessions.middleware.SessionMiddleware'
]

Follow the official Django documentation to set a proper session. Either a database backend or a cache backend would work well.

Routes for Authorization¶

Just like the example in Web OAuth Clients, everything is the same. But there is a hint to create redirect_uri with request in Django:

def login(request):
    # build a full authorize callback uri
    redirect_uri = request.build_absolute_uri('/authorize')
    return oauth.twitter.authorize_redirect(request, redirect_uri)

Auto Update Token via Signal¶

Instead of defining an update_token method and passing it into OAuth registry, it is also possible to use signals to listen for token updates:

from django.dispatch import receiver
from authlib.integrations.django_client import token_update

@receiver(token_update)
def on_token_update(sender, name, token, refresh_token=None, access_token=None, **kwargs):
    if refresh_token:
        item = OAuth2Token.find(name=name, refresh_token=refresh_token)
    elif access_token:
        item = OAuth2Token.find(name=name, access_token=access_token)
    else:
        return

    # update old token
    item.access_token = token['access_token']
    item.refresh_token = token.get('refresh_token')
    item.expires_at = token['expires_at']
    item.save()

Django OpenID Connect Client¶

An OpenID Connect client is no different than a normal OAuth 2.0 client. When registered with the openid scope, the built-in Django OAuth client will handle everything automatically:

oauth.register(
    'google',
    ...
    server_metadata_url='https://accounts.google.com/.well-known/openid-configuration',
    client_kwargs={'scope': 'openid profile email'}
)

When we get the returned token:

token = oauth.google.authorize_access_token(request)

There should be a id_token in the response. Authlib has called .parse_id_token automatically, we can get userinfo in the token:

userinfo = token['userinfo']

Find Django Google login example at https://github.com/authlib/demo-oauth-client/tree/master/django-google-login

Configuration¶

Starlette can load configuration from environment; Authlib implementation for Starlette client can use this configuration. Here is an example of how to do it:

from starlette.config import Config

config = Config('.env')
oauth = OAuth(config)

Authlib will load client_id and client_secret from the configuration, take google as an example:

oauth.register(name='google', ...)

It will load GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET from the environment.

Register Remote Apps¶

oauth.register is the same as Web OAuth Clients:

oauth.register(
    'google',
    client_id='...',
    client_secret='...',
    ...
)

However, unlike Flask/Django, Starlette OAuth registry is using HTTPX AsyncOAuth1Client and AsyncOAuth2Client as the OAuth backends. While Flask and Django are using the Requests version of OAuth1Session and OAuth2Session.

Enable Session for OAuth 1.0¶

With OAuth 1.0, we need to use a temporary credential to exchange for an access token. This temporary credential is created before redirecting to the provider (Twitter), and needs to be saved somewhere in order to use it later.

With OAuth 1, the Starlette client will save the request token in sessions. To enable this, we need to add the SessionMiddleware middleware to the application, which requires the installation of the itsdangerous package:

from starlette.applications import Starlette
from starlette.middleware.sessions import SessionMiddleware

app = Starlette()
app.add_middleware(SessionMiddleware, secret_key="some-random-string")

However, using the SessionMiddleware will store the temporary credential as a secure cookie which will expose your request token to the client.

Routes for Authorization¶

Just like the examples in Web OAuth Clients, but Starlette is async, the routes for authorization should look like:

@app.route('/login/google')
async def login_via_google(request):
    google = oauth.create_client('google')
    redirect_uri = request.url_for('authorize_google')
    return await google.authorize_redirect(request, redirect_uri)

@app.route('/auth/google')
async def authorize_google(request):
    google = oauth.create_client('google')
    token = await google.authorize_access_token(request)
    # do something with the token and userinfo
    return '...'

Starlette OpenID Connect¶

An OpenID Connect client is no different than a normal OAuth 2.0 client, just add openid scope when .register. The built-in Starlette OAuth client will handle everything automatically:

oauth.register(
    'google',
    ...
    server_metadata_url='https://accounts.google.com/.well-known/openid-configuration',
    client_kwargs={'scope': 'openid profile email'}
)

When we get the returned token:

token = await oauth.google.authorize_access_token()

There should be a id_token in the response. Authlib has called .parse_id_token automatically, we can get userinfo in the token:

userinfo = token['userinfo']

Examples¶

We have Starlette demos at https://github.com/authlib/demo-oauth-client

1. OAuth 1.0: Starlette Twitter login

2. OAuth 2.0: Starlette Google login

FastAPI OAuth 1.0 Client¶

We have a blog post about how to create Twitter login in FastAPI:

https://blog.authlib.org/2020/fastapi-twitter-login

FastAPI OAuth 2.0 Client¶

We have a blog post about how to create Google login in FastAPI:

https://blog.authlib.org/2020/fastapi-google-login

Requests OAuth Sessions¶

class authlib.integrations.requests_client.OAuth1Session(client_id, client_secret=None, token=None, token_secret=None, redirect_uri=None, rsa_key=None, verifier=None, signature_method='HMAC-SHA1', signature_type='HEADER', force_include_body=False, **kwargs)¶

create_authorization_url(url, request_token=None, **kwargs)¶

Create an authorization URL by appending request_token and optional kwargs to url.

This is the second step in the OAuth 1 workflow. The user should be redirected to this authorization URL, grant access to you, and then be redirected back to you. The redirection back can either be specified during client registration or by supplying a callback URI per request.

Parameters

• url – The authorization endpoint URL.

• request_token – The previously obtained request token.

• kwargs – Optional parameters to append to the URL.

Returns

The authorization URL with new parameters embedded.

fetch_access_token(url, verifier=None, **kwargs)¶

Method for fetching an access token from the token endpoint.

This is the final step in the OAuth 1 workflow. An access token is obtained using all previously obtained credentials, including the verifier from the authorization step.

Parameters

• url – Access Token endpoint.

• verifier – A verifier string to prove authorization was granted.

• kwargs – Extra parameters to include for fetching access token.

Returns

A token dict.

fetch_request_token(url, realm=None, **kwargs)¶

Method for fetching an access token from the token endpoint.

This is the first step in the OAuth 1 workflow. A request token is obtained by making a signed post request to url. The token is then parsed from the application/x-www-form-urlencoded response and ready to be used to construct an authorization url.

Parameters

• url – Request Token endpoint.

• realm – A string/list/tuple of realm for Authorization header.

• kwargs – Extra parameters to include for fetching token.

Returns

A Request Token dict.

Note, realm can also be configured when session created:

session = OAuth1Session(client_id, client_secret, ..., realm='')

parse_authorization_response(url)¶

Extract parameters from the post authorization redirect response URL.

Parameters

url – The full URL that resulted from the user being redirected back from the OAuth provider to you, the client.

Returns

A dict of parameters extracted from the URL.

class authlib.integrations.requests_client.OAuth1Auth(client_id, client_secret=None, token=None, token_secret=None, redirect_uri=None, rsa_key=None, verifier=None, signature_method='HMAC-SHA1', signature_type='HEADER', realm=None, force_include_body=False)¶

Signs the request using OAuth 1 (RFC5849)

class authlib.integrations.requests_client.OAuth2Session(client_id=None, client_secret=None, token_endpoint_auth_method=None, revocation_endpoint_auth_method=None, scope=None, state=None, redirect_uri=None, token=None, token_placement='header', update_token=None, **kwargs)¶

Construct a new OAuth 2 client requests session.

Parameters

• client_id – Client ID, which you get from client registration.

• client_secret – Client Secret, which you get from registration.

• authorization_endpoint – URL of the authorization server’s authorization endpoint.

• token_endpoint – URL of the authorization server’s token endpoint.

• token_endpoint_auth_method – client authentication method for token endpoint.

• revocation_endpoint – URL of the authorization server’s OAuth 2.0 revocation endpoint.

• revocation_endpoint_auth_method – client authentication method for revocation endpoint.

• scope – Scope that you needed to access user resources.

• state – Shared secret to prevent CSRF attack.

• redirect_uri – Redirect URI you registered as callback.

• token – A dict of token attributes such as access_token, token_type and expires_at.

• token_placement – The place to put token in HTTP request. Available values: “header”, “body”, “uri”.

• update_token – A function for you to update token. It accept a OAuth2Token as parameter.

create_authorization_url(url, state=None, code_verifier=None, **kwargs)¶

Generate an authorization URL and state.

Parameters

• url – Authorization endpoint url, must be HTTPS.

• state – An optional state string for CSRF protection. If not given it will be generated for you.

• code_verifier – An optional code_verifier for code challenge.

• kwargs – Extra parameters to include.

Returns

authorization_url, state

fetch_token(url=None, body='', method='POST', headers=None, auth=None, grant_type=None, state=None, **kwargs)¶

Generic method for fetching an access token from the token endpoint.

Parameters

• url – Access Token endpoint URL, if not configured, authorization_response is used to extract token from its fragment (implicit way).

• body – Optional application/x-www-form-urlencoded body to add the include in the token request. Prefer kwargs over body.

• method – The HTTP method used to make the request. Defaults to POST, but may also be GET. Other methods should be added as needed.

• headers – Dict to default request headers with.

• auth – An auth tuple or method as accepted by requests.

• grant_type – Use specified grant_type to fetch token

Returns

A OAuth2Token object (a dict too).

introspect_token(url, token=None, token_type_hint=None, body=None, auth=None, headers=None, **kwargs)¶

Implementation of OAuth 2.0 Token Introspection defined via RFC7662.

Parameters

• url – Introspection Endpoint, must be HTTPS.

• token – The token to be introspected.

• token_type_hint – The type of the token that to be revoked. It can be “access_token” or “refresh_token”.

• body – Optional application/x-www-form-urlencoded body to add the include in the token request. Prefer kwargs over body.

• auth – An auth tuple or method as accepted by requests.

• headers – Dict to default request headers with.

Returns

Introspection Response

refresh_token(url, refresh_token=None, body='', auth=None, headers=None, **kwargs)¶

Fetch a new access token using a refresh token.

Parameters

• url – Refresh Token endpoint, must be HTTPS.

• refresh_token – The refresh_token to use.

• body – Optional application/x-www-form-urlencoded body to add the include in the token request. Prefer kwargs over body.

• auth – An auth tuple or method as accepted by requests.

• headers – Dict to default request headers with.

Returns

A OAuth2Token object (a dict too).

register_client_auth_method(auth)¶

Extend client authenticate for token endpoint.

Parameters

auth – an instance to sign the request

register_compliance_hook(hook_type, hook)¶

Register a hook for request/response tweaking.

Available hooks are:

• access_token_response: invoked before token parsing.

• refresh_token_request: invoked before refreshing token.

• refresh_token_response: invoked before refresh token parsing.

• protected_request: invoked before making a request.

• revoke_token_request: invoked before revoking a token.

• introspect_token_request: invoked before introspecting a token.

revoke_token(url, token=None, token_type_hint=None, body=None, auth=None, headers=None, **kwargs)¶

Revoke token method defined via RFC7009.

Parameters

• url – Revoke Token endpoint, must be HTTPS.

• token – The token to be revoked.

• token_type_hint – The type of the token that to be revoked. It can be “access_token” or “refresh_token”.

• body – Optional application/x-www-form-urlencoded body to add the include in the token request. Prefer kwargs over body.

• auth – An auth tuple or method as accepted by requests.

• headers – Dict to default request headers with.

Returns

Revocation Response

class authlib.integrations.requests_client.OAuth2Auth(token, token_placement='header', client=None)¶

Sign requests for OAuth 2.0, currently only bearer token is supported.

class authlib.integrations.requests_client.AssertionSession(token_endpoint, issuer, subject, audience=None, grant_type=None, claims=None, token_placement='header', scope=None, **kwargs)¶

Constructs a new Assertion Framework for OAuth 2.0 Authorization Grants per RFC7521.

HTTPX OAuth Clients¶

class authlib.integrations.httpx_client.OAuth1Auth(client_id, client_secret=None, token=None, token_secret=None, redirect_uri=None, rsa_key=None, verifier=None, signature_method='HMAC-SHA1', signature_type='HEADER', realm=None, force_include_body=False)¶

Signs the httpx request using OAuth 1 (RFC5849)

auth_flow(request: httpx.Request) → Generator[httpx.Request, httpx.Response, None]¶

Execute the authentication flow.

To dispatch a request, yield it:

` yield request `

The client will .send() the response back into the flow generator. You can access it like so:

` response = yield request `

A return (or reaching the end of the generator) will result in the client returning the last response obtained from the server.

You can dispatch as many requests as is necessary.

class authlib.integrations.httpx_client.OAuth1Client(client_id, client_secret=None, token=None, token_secret=None, redirect_uri=None, rsa_key=None, verifier=None, signature_method='HMAC-SHA1', signature_type='HEADER', force_include_body=False, **kwargs)¶

create_authorization_url(url, request_token=None, **kwargs)¶

Create an authorization URL by appending request_token and optional kwargs to url.

This is the second step in the OAuth 1 workflow. The user should be redirected to this authorization URL, grant access to you, and then be redirected back to you. The redirection back can either be specified during client registration or by supplying a callback URI per request.

Parameters

• url – The authorization endpoint URL.

• request_token – The previously obtained request token.

• kwargs – Optional parameters to append to the URL.

Returns

The authorization URL with new parameters embedded.

fetch_access_token(url, verifier=None, **kwargs)¶

Method for fetching an access token from the token endpoint.

This is the final step in the OAuth 1 workflow. An access token is obtained using all previously obtained credentials, including the verifier from the authorization step.

Parameters

• url – Access Token endpoint.

• verifier – A verifier string to prove authorization was granted.

• kwargs – Extra parameters to include for fetching access token.

Returns

A token dict.

fetch_request_token(url, realm=None, **kwargs)¶

Method for fetching an access token from the token endpoint.

This is the first step in the OAuth 1 workflow. A request token is obtained by making a signed post request to url. The token is then parsed from the application/x-www-form-urlencoded response and ready to be used to construct an authorization url.

Parameters

• url – Request Token endpoint.

• realm – A string/list/tuple of realm for Authorization header.

• kwargs – Extra parameters to include for fetching token.

Returns

A Request Token dict.

Note, realm can also be configured when session created:

session = OAuth1Session(client_id, client_secret, ..., realm='')

parse_authorization_response(url)¶

Extract parameters from the post authorization redirect response URL.

Parameters

url – The full URL that resulted from the user being redirected back from the OAuth provider to you, the client.

Returns

A dict of parameters extracted from the URL.

class authlib.integrations.httpx_client.AsyncOAuth1Client(client_id, client_secret=None, token=None, token_secret=None, redirect_uri=None, rsa_key=None, verifier=None, signature_method='HMAC-SHA1', signature_type='HEADER', force_include_body=False, **kwargs)¶

create_authorization_url(url, request_token=None, **kwargs)¶

Create an authorization URL by appending request_token and optional kwargs to url.

This is the second step in the OAuth 1 workflow. The user should be redirected to this authorization URL, grant access to you, and then be redirected back to you. The redirection back can either be specified during client registration or by supplying a callback URI per request.

Parameters

• url – The authorization endpoint URL.

• request_token – The previously obtained request token.

• kwargs – Optional parameters to append to the URL.

Returns

The authorization URL with new parameters embedded.

async fetch_access_token(url, verifier=None, **kwargs)¶

Method for fetching an access token from the token endpoint.

This is the final step in the OAuth 1 workflow. An access token is obtained using all previously obtained credentials, including the verifier from the authorization step.

Parameters

• url – Access Token endpoint.

• verifier – A verifier string to prove authorization was granted.

• kwargs – Extra parameters to include for fetching access token.

Returns

A token dict.

fetch_request_token(url, realm=None, **kwargs)¶

Method for fetching an access token from the token endpoint.

This is the first step in the OAuth 1 workflow. A request token is obtained by making a signed post request to url. The token is then parsed from the application/x-www-form-urlencoded response and ready to be used to construct an authorization url.

Parameters

• url – Request Token endpoint.

• realm – A string/list/tuple of realm for Authorization header.

• kwargs – Extra parameters to include for fetching token.

Returns

A Request Token dict.

Note, realm can also be configured when session created:

session = OAuth1Session(client_id, client_secret, ..., realm='')

parse_authorization_response(url)¶

Extract parameters from the post authorization redirect response URL.

Parameters

url – The full URL that resulted from the user being redirected back from the OAuth provider to you, the client.

Returns

A dict of parameters extracted from the URL.

class authlib.integrations.httpx_client.OAuth2Auth(token, token_placement='header', client=None)¶

Sign requests for OAuth 2.0, currently only bearer token is supported.

class authlib.integrations.httpx_client.OAuth2Client(client_id=None, client_secret=None, token_endpoint_auth_method=None, revocation_endpoint_auth_method=None, scope=None, redirect_uri=None, token=None, token_placement='header', update_token=None, **kwargs)¶

create_authorization_url(url, state=None, code_verifier=None, **kwargs)¶

Generate an authorization URL and state.

Parameters

• url – Authorization endpoint url, must be HTTPS.

• state – An optional state string for CSRF protection. If not given it will be generated for you.

• code_verifier – An optional code_verifier for code challenge.

• kwargs – Extra parameters to include.

Returns

authorization_url, state

fetch_token(url=None, body='', method='POST', headers=None, auth=None, grant_type=None, state=None, **kwargs)¶

Generic method for fetching an access token from the token endpoint.

Parameters

• url – Access Token endpoint URL, if not configured, authorization_response is used to extract token from its fragment (implicit way).

• body – Optional application/x-www-form-urlencoded body to add the include in the token request. Prefer kwargs over body.

• method – The HTTP method used to make the request. Defaults to POST, but may also be GET. Other methods should be added as needed.

• headers – Dict to default request headers with.

• auth – An auth tuple or method as accepted by requests.

• grant_type – Use specified grant_type to fetch token

Returns

A OAuth2Token object (a dict too).

introspect_token(url, token=None, token_type_hint=None, body=None, auth=None, headers=None, **kwargs)¶

Implementation of OAuth 2.0 Token Introspection defined via RFC7662.

Parameters

• url – Introspection Endpoint, must be HTTPS.

• token – The token to be introspected.

• token_type_hint – The type of the token that to be revoked. It can be “access_token” or “refresh_token”.

• body – Optional application/x-www-form-urlencoded body to add the include in the token request. Prefer kwargs over body.

• auth – An auth tuple or method as accepted by requests.

• headers – Dict to default request headers with.

Returns

Introspection Response

refresh_token(url, refresh_token=None, body='', auth=None, headers=None, **kwargs)¶

Fetch a new access token using a refresh token.

Parameters

• url – Refresh Token endpoint, must be HTTPS.

• refresh_token – The refresh_token to use.

• body – Optional application/x-www-form-urlencoded body to add the include in the token request. Prefer kwargs over body.

• auth – An auth tuple or method as accepted by requests.

• headers – Dict to default request headers with.

Returns

A OAuth2Token object (a dict too).

register_client_auth_method(auth)¶

Extend client authenticate for token endpoint.

Parameters

auth – an instance to sign the request

register_compliance_hook(hook_type, hook)¶

Register a hook for request/response tweaking.

Available hooks are:

• access_token_response: invoked before token parsing.

• refresh_token_request: invoked before refreshing token.

• refresh_token_response: invoked before refresh token parsing.

• protected_request: invoked before making a request.

• revoke_token_request: invoked before revoking a token.

• introspect_token_request: invoked before introspecting a token.

revoke_token(url, token=None, token_type_hint=None, body=None, auth=None, headers=None, **kwargs)¶

Revoke token method defined via RFC7009.

Parameters

• url – Revoke Token endpoint, must be HTTPS.

• token – The token to be revoked.

• token_type_hint – The type of the token that to be revoked. It can be “access_token” or “refresh_token”.

• body – Optional application/x-www-form-urlencoded body to add the include in the token request. Prefer kwargs over body.

• auth – An auth tuple or method as accepted by requests.

• headers – Dict to default request headers with.

Returns

Revocation Response