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.

Flexible¶

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. Flexible 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 flexible, you can ask help on StackOverflow or open an issue on GitHub.

Specification¶

Authlib is a spec-compliant library which follows the latest specifications. We keep the generic tool functions in a specs module. When there is a auth-related specification, we add it into specs.

Currently, these specs are in the warehouse:

• done RFC5849: The OAuth 1.0 Protocol
• done RFC6749: The OAuth 2.0 Authorization Framework
• done RFC6750: The OAuth 2.0 Authorization Framework: Bearer Token Usage
• done RFC7009: OAuth 2.0 Token Revocation
• done RFC7515: JSON Web Signature
• beta RFC7516: JSON Web Encryption
• done RFC7517: JSON Web Key
• done RFC7518: JSON Web Algorithms
• done RFC7519: JSON Web Token
• done RFC7523: JWT Profile for OAuth 2.0 Client Authentication and Authorization Grants
• beta RFC7636: Proof Key for Code Exchange by OAuth Public Clients
• done RFC7662: OAuth 2.0 Token Introspection
• done OpenID Connect 1.0

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:

• requests
• cryptography

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 .

Roles in OAuth 1.0¶

There are usually three roles in an OAuth 1.0 flow. Let’s take Twitter as an example, you are building a mobile app to send tweets:

• Client: a client is a third-party application. In this case, it is your application.
• Resource Owner: the users on Twitter are the resource owners, since they own their tweets (resources).
• Server: authorization and resource server. In this case, it is twitter.

Credentials¶

During the OAuth 1.0 process, there are several credentials passed from server to client, and vice versa.

1. client credentials
2. temporary credentials
3. token credentials

OAuth 1.0 Flow¶

Let’s take your mobile Twitter app as an example. When a user wants to send a tweet through your application, he/she needs to authenticate at first. When the app is opened, and the login button is clicked:

1. Client uses its client credentials to make a request to server, asking the server for a temporary credential.
2. Server responds with a temporary credential if it verified your client credential.
3. Client saves temporary credential for later use, then open a view for resource owner to grant the access.
4. When access is granted, Server responds with a verifier to client.
5. Client uses this verifier and temporary credential to make a request to the server asking for token credentials.
6. Server responds with access token if it verified everything.

And then Client can send tweets with the token credentials.

Signature¶

In OAuth 1.0, every request client sending to server requires a signature. The signature is calculated from:

1. credentials (client, temporary, token)
2. timestamp & nonce
3. other HTTP information

OAuth 2.0 Roles¶

There are usually four roles in an OAuth 2.0 flow. Let’s take GitHub as an example, you are building an application to analyze one’s code on GitHub:

• Client: a client is a third-party application, in this case, it is your application.
• Resource Owner: the users and orgs on GitHub are the resource owners, since they own their source code (resources).
• Resource Server: The API servers of GitHub. Your client will make requests to the resource server to fetch source code. The server serves resources.
• Authorization Server: The server for client to obtain an access token.

OAuth 2.0 Flow¶

The above image is a simplified version of an OAuth 2.0 authorization. Let’s take GitHub as an example. A user wants to use your application to analyze his/her source code on GitHub.

It usually takes these steps:

1. Your application (client) prompts the user to log in.
2. The user clicks the login button, your application will redirect to GitHub’s authorize page (Authorization Server).
3. The user (he/she is a GitHub user, which means he/she is a Resource Owner) clicks the allow button to tell GitHub that he/she granted the access.
4. The Authorization Server issues an access token to your application. (This step can contain several sub-steps)
5. Your application uses the access token to fetch source code from GitHub’s Resource Server, analyze the source code and return the result to your application user.

But there are more details inside the flow. The most important thing in OAuth 2.0 is the authorization. A client obtains an access token from the authorization server with the grant of the resource owner.

Grant Types¶

Authorization server MAY supports several grant types during the authorization, step 1 and 2. A grant type defines a way of how the authorization server will verify the request and issue the token.

There are lots of built-in grant types in Authlib, including:

• AuthorizationCodeGrant
• ImplicitGrant
• ResourceOwnerPasswordCredentialsGrant
• ClientCredentialsGrant
• RefreshTokenGrant
• JWTBearerGrant

Take authorization_code as an example, in step 2, when the resource owner granted the access, Authorization Server will return a code to the client. The client can use this code to exchange an access token:

POST /token HTTP/1.1
Host: server.example.com
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA

Client Authentication Methods¶

In the above code, there is an Authorization header; it contains the information of the client. A client MUST provide its client information to obtain an access token. There are several ways to provide this data, for instance:

• none: The client is a public client which means it has no client_secret

  POST /token HTTP/1.1
  Host: server.example.com
  Content-Type: application/x-www-form-urlencoded
  
  grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA
  &client_id=s6BhdRkqt3
  

• client_secret_post: The client uses the HTTP POST parameters

  POST /token HTTP/1.1
  Host: server.example.com
  Content-Type: application/x-www-form-urlencoded
  
  grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA
  &client_id=s6BhdRkqt3&client_secret=gX1fBat3bV
  

• client_secret_basic: The client uses HTTP Basic Authorization

  POST /token HTTP/1.1
  Host: server.example.com
  Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
  Content-Type: application/x-www-form-urlencoded
  
  grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA
  

There are more client authentication methods defined by OAuth 2.0 extensions, including client_secret_jwt, private_key_jwt. They can be found in section Using JWTs for Client Authentication.

Token Scopes¶

Scope is a very important concept in OAuth 2.0. An access token is usually issued with limited scopes.

For instance, your “source code analyzer” application MAY only have access to the public repositories of a GiHub user.

Endpoints¶

The above example only shows one endpoint, which is token endpoint. There are more endpoints in OAuth 2.0. For example:

• Token Revocation Endpoint
• Token Introspection Endpoint

OAuth1Session for requests¶

The OAuth1Session in Authlib is a subclass of requests.Session. It shares the same API with requests.Session and extends it with OAuth 1 protocol. This section is a guide on how to obtain an access token in OAuth 1 flow.

If you are not familiar with OAuth 1.0, it is better to Understand OAuth 1.0 now.

There are three steps in OAuth 1 to obtain an access token. Initialize the session for reuse:

>>> from authlib.client import OAuth1Session
>>> client_id = 'Your Twitter client key'
>>> client_secret = 'Your Twitter client secret'
>>> session = OAuth1Session(client_id, client_secret)

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

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

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

>>> session.create_authorization_url(authenticate_url)

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

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

>>> resp_url = 'https://example.com/twitter?oauth_token=gA..H&oauth_verifier=fcg..1Dq'
>>> session.parse_authorization_response(resp_url)
>>> access_token_url = 'https://api.twitter.com/oauth/access_token'
>>> token = session.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)

>>> # 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']
>>> session = 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 = session.fetch_access_token(access_token_url, verifier)

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

>>> access_token = restore_access_token_from_database()
>>> oauth_token = access_token['oauth_token']
>>> oauth_token_secret = access_token['oauth_token_secret']
>>> session = 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 = session.get(account_url)

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

import requests

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

AsyncOAuth1Client for aiohttp¶

The AsyncOAuth1Client is located in authlib.client.aiohttp. Authlib doesn’t embed aiohttp as a dependency, you need to install it yourself.

Here is an example on how you can initialize an instance of AsyncOAuth1Client for aiohttp:

import asyncio
from aiohttp import ClientSession
from authlib.client.aiohttp import AsyncOAuth1Client, OAuthRequest

REQUEST_TOKEN_URL = 'https://api.twitter.com/oauth/request_token'

async def main():
    # OAuthRequest is required to handle auth
    async with ClientSession(request_class=OAuthRequest) as session:
        client = AsyncOAuth1Client(session, 'client_id', 'client_secret', ...)
        token = await client.fetch_request_token(REQUEST_TOKEN_URL)
        print(token)

loop = asyncio.get_event_loop()
loop.run_until_complete(main())

The API is similar with OAuth1Session above. Using the client for the three steps authorization:

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

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

url = client.create_authorization_url(authenticate_url)
print(url)
'https://api.twitter.com/oauth/authenticate?oauth_token=gA..H'

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

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

# twitter redirected back to your website
resp_url = 'https://example.com/twitter?oauth_token=gA..H&oauth_verifier=fcg..1Dq'

# you may use the ``oauth_token`` in resp_url to
# get back your previous request token
request_token = {'oauth_token': 'gA..H', 'oauth_token_secret': '...'}

# assign request token to client
client.token = request_token

# resolve the ``oauth_verifier`` from resp_url
oauth_verifier = get_oauth_verifier_value(resp_url)

access_token_url = 'https://api.twitter.com/oauth/access_token'
token = await client.fetch_access_token(access_token_url, oauth_verifier)

# get back the access token if you have saved it in some place
access_token = {'oauth_token': '...', 'oauth_secret': '...'}

# assign it to client
client.token = access_token

account_url = 'https://api.twitter.com/1.1/account/verify_credentials.json'
async with client.get(account_url) as resp:
    data = await resp.json()

client = AsyncOAuth1Client(
    session, 'client_id', 'client_secret',
    token='...', token_secret='...',
    ...
)

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:

>>> from authlib.client import OAuth2Session
>>> client_id = 'Your GitHub client ID'
>>> client_secret = 'Your GitHub client secret'
>>> scope = 'user:email'  # we want to fetch user's email
>>> session = OAuth2Session(client_id, client_secret, scope=scope)

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

>>> authorize_url = 'https://github.com/login/oauth/authorize'
>>> uri, state = session.create_authorization_url(authorize_url)
>>> 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'
>>> access_token_url = 'https://github.com/login/oauth/access_token'
>>> token = session.fetch_access_token(access_token_url, authorization_response=authorization_response)
>>> print(token)
{
    'access_token': 'e..ad',
    'token_type': 'bearer',
    'scope': 'user:email'
}

>>> state = restore_previous_state()
>>> session = OAuth2Session(client_id, client_secret, state=state)
>>> session.fetch_access_token(access_token_url, authorization_response=authorization_response)

OAuth2Session for Implicit¶

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

>>> uri, state = session.create_authorization_url(authorize_url, 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 authoirzation 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 OAuth2Session.fetch_access_token():

>>> token = session.fetch_access_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 = session.fetch_access_token(token_url, 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 = session.fetch_access_token(token_url)
>>> # or with grant_type
>>> token = session.fetch_access_token(token_url, grant_type='client_credentials')

Client Authentication¶

When fetching access token, the authorization server will require a client authentication, Authlib has provided a OAuth2ClientAuth which supports 3 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:

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

If the authorization server requires other means of authentication, you can construct an auth of requests, and pass it to fetch_access_token:

>>> auth = YourAuth(...)
>>> token = session.fetch_access_token(token_url, 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 for Client Authentication.

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 = session.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:

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

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, linkedin is using a oauth2_access_token parameter in query string to protect users’ resources, let’s fix it:

from authlib.common.urls import add_params_to_uri

def _non_compliant_param_name(url, headers, data):
    access_token = session.token.get('access_token')
    token = [('oauth2_access_token', access_token)]
    url = add_params_to_uri(url, token)
    return url, headers, data

session.register_compliance_hook(
    'protected_request', _non_compliant_param_name)

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:

>>> from authlib.client import OAuth2Session
>>> client_id = 'Your Google client ID'
>>> client_secret = 'Your Google client secret'
>>> scope = 'openid email profile'
>>> session = OAuth2Session(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 thise 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()
>>> session.create_authorization_url(url, redirect_uri='xxx', nonce=nonce, ...)

At the last step of session.fetch_access_token, the return value contains a id_token:

>>> resp = session.fetch_access_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 JWT 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.client import AssertionSession

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

token_url = 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(
    grant_type=cls.JWT_BEARER_GRANT_TYPE,
    token_url=token_url,
    issuer=conf['client_email'],
    audience=token_url,
    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.

Configuration¶

To register a remote application on OAuth registry, using the register() method:

oauth.register(
    name='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,
)

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

oauth.twitter.get('account/verify_credentials.json')

The second parameter in register method is configuration. Every key value pair can be omit. They can be configured in your Flask App configuration. Config key is formatted with {name}_{key} in uppercase, e.g.

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

The remote app that OAuth.register() configured, is a subclass of OAuthClient. You can read more on OAuthClient. There are hooks for OAuthClient, and flask integration has registered them all for you.

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}_REFRESH_TOKEN_URL: Refresh Token endpoint for OAuth 2 (if any)
• {name}_REFRESH_TOKEN_PARAMS: Extra parameters for Refresh 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

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

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

Database¶

We need to fetch_token from database for later requests. Here is an example on database schema design:

class OAuth1Token(db.Model)
    user_id = Column(Integer, nullable=False)
    name = Column(String(20), nullable=False)

    oauth_token = Column(String(48), nullable=False)
    oauth_token_secret = Column(String(48))

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

class OAuth2Token(db.Model):
    user_id = Column(Integer, nullable=False)
    name = Column(String(20), nullable=False)

    token_type = Column(String(20))
    access_token = Column(String(48), nullable=False)
    refresh_token = Column(String(48))
    expires_at = Column(Integer, default=0)

    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,
        )

To send requests on behalf of the user, you need to save user’s access token into database after authorize_access_token. Then use the access token with fetch_token from database.

OAuth 1 Request Token¶

OAuth 1 requires a temporary request token for exchanging access token. There should be a place to store these temporary information. If a cache system is available, the ONLY thing you need to do is pass the cache instance into OAuth registry. A cache interface MUST have methods:

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

Pass the cache instance into OAuth registry:

from authlib.flask.client import OAuth

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

If cache system is not available, you can define methods for retrieving and saving request token:

def save_request_token(token):
    save_request_token_to_someplace(current_user, token)

def fetch_request_token():
    return get_request_token_from_someplace(current_user)

# register the two methods
oauth.register('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,
    # NOTICE HERE
    save_request_token=save_request_token,
    fetch_request_token=fetch_request_token,
)

Flask OAuth Clients Routes¶

Let’s take Twitter as an example, we need to define routes for login and authorization:

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()
    # this is a pseudo method, you need to implement it yourself
    OAuth1Token.save(current_user, token)
    return redirect(url_for('twitter_profile'))

@app.route('/profile')
def twitter_profile():
    resp = oauth.twitter.get('account/verify_credentials.json')
    profile = resp.json()
    return render_template('profile.html', profile=profile)

There will be an issue with /profile since you our registry don’t know current user’s Twitter access token. We need to design a fetch_token, and grant it to the registry:

def fetch_twitter_token():
    item = OAuth1Token.query.filter_by(
        name='twitter', user_id=current_user.id
    ).first()
    return item.to_token()

# we can registry this ``fetch_token`` with oauth.register
oauth.register(
    '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,
    # NOTICE HERE
    fetch_token=fetch_twitter_token,
)

Since the OAuth registry can contain many services, it would be good enough to share some common methods instead of defining them one by one. Here are some hints:

from flask import url_for, render_template

@app.route('/login/<name>')
def login(name):
    client = oauth.create_client(name)
    redirect_uri = url_for('authorize', name=name, _external=True)
    return client.authorize_redirect(redirect_uri)

@app.route('/authorize/<name>')
def authorize(name):
    client = oauth.create_client(name)
    token = client.authorize_access_token()
    if name in OAUTH1_SERVICES:
        # this is a pseudo method, you need to implement it yourself
        OAuth1Token.save(current_user, token)
    else:
        # this is a pseudo method, you need to implement it yourself
        OAuth2Token.save(current_user, token)
    return redirect(url_for('profile', name=name))

@app.route('/profile/<name>')
def profile(name):
    client = oauth.create_client(name)
    resp = oauth.twitter.get(get_profile_url(name))
    profile = resp.json()
    return render_template('profile.html', profile=profile)

We can share a fetch_token method at OAuth registry level when initialization. Define a common fetch_token:

def fetch_token(name):
    if name in OAUTH1_SERVICES:
        item = OAuth1Token.query.filter_by(
            name=name, user_id=current_user.id
        ).first()
    else:
        item = OAuth2Token.query.filter_by(
            name=name, user_id=current_user.id
        ).first()
    if item:
        return item.to_token()

# pass ``fetch_token``
oauth = OAuth(app, fetch_token=fetch_token)

# or init app later
oauth = OAuth(fetch_token=fetch_token)
oauth.init_app(app)

# or init everything later
oauth = OAuth()
oauth.init_app(app, fetch_token=fetch_token)

With this common fetch_token in OAuth, you don’t need to design the method for each services one by one.

Auto Refresh Token¶

In OAuth 2, there is a concept of refresh_token, Authlib can auto refresh access token when it is expired. If the services you are using don’t issue any refresh_token at all, you don’t need to do anything.

Just like fetch_token, we can define a update_token method for each remote app or sharing it in OAuth registry:

def update_token(name, token):
    item = OAuth2Token.query.filter_by(
        name=name, user_id=current_user.id
    ).first()
    if not item:
        item = OAuth2Token(name=name, user_id=current_user.id)
    item.token_type = token.get('token_type', 'bearer')
    item.access_token = token.get('access_token')
    item.refresh_token = token.get('refresh_token')
    item.expires_at = token.get('expires_at')
    db.session.add(item)
    db.session.commit()
    return item

# pass ``update_token``
oauth = OAuth(app, update_token=update_token)

# or init app later
oauth = OAuth(update_token=update_token)
oauth.init_app(app)

# or init everything later
oauth = OAuth()
oauth.init_app(app, update_token=update_token)

Code Challenge¶

Adding code_challenge provided by RFC7636: Proof Key for Code Exchange by OAuth Public Clients is simple. You register your remote app with a code_challenge_method:

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=None,
    code_challenge_method='S256',
)

Note, the only supported code_challenge_method is S256.

Compliance Fix¶

The RemoteApp is a subclass of OAuthClient, they share the same logic for compliance fix. Construct a method to fix requests session:

def slack_compliance_fix(session):
    def _fix(resp):
        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)

When OAuth.register() a remote app, pass it in the parameters:

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

Find all the available compliance hooks at Compliance Fix for non Standard.

Loginpass¶

There are many built-in integrations served by loginpass, checkout the flask_example in loginpass project. Here is an example of GitHub:

from flask import Flask
from authlib.flask.client import OAuth
from loginpass import create_flask_blueprint, GitHub

app = Flask(__name__)
oauth = OAuth(app)

def handle_authorize(remote, token, user_info):
    if token:
        save_token(remote.name, token)
    if user_info:
        save_user(user_info)
        return user_page
    raise some_error

github_bp = create_flask_blueprint(GitHub, oauth, handle_authorize)
app.register_blueprint(github_bp, url_prefix='/github')
# Now, there are: ``/github/login`` and ``/github/auth``

The source code of loginpass is very simple, they are just preconfigured services integrations.

Configuration¶

To register a remote application on OAuth registry, using the register() method:

oauth.register(
    '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,
)

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

oauth.twitter.get('account/verify_credentials.json')

The second parameter in register method is configuration. Every key value pair can be omit. 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
    }
}

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

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

Sessions Middleware¶

In OAuth 1, Django client will save the request token in sessions. In this case, you 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.

Database Design¶

Authlib Django client has no built-in database model. You need to design the Token model by yourself. This is designed by intention.

Here are some hints on how to design your schema:

class OAuth1Token(models.Model):
    name = models.CharField(max_length=40)
    oauth_token = models.CharField(max_length=200)
    oauth_token_secret = models.CharField(max_length=200)
    # ...

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

class OAuth2Token(models.Model):
    name = models.CharField(max_length=40)
    token_type = models.CharField(max_length=20)
    access_token = models.CharField(max_length=200)
    refresh_token = models.CharField(max_length=200)
    # oauth 2 expires time
    expires_at = models.DateTimeField()
    # ...

    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,
        )

Implement the Server¶

There are two views to be completed, no matter it is OAuth 1 or OAuth 2:

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

def authorize(request):
    token = oauth.twitter.authorize_access_token(request)
    # save_token_to_db(token)
    return '...'

def fetch_resource(request):
    token = get_user_token_from_db(request.user)
    # remember to assign user's token to the client
    resp = oauth.twitter.get('account/verify_credentials.json', token=token)
    profile = resp.json()
    # ...

When using the oauth client to make HTTP requests, developers will always need to get the token and pass the token into the requests. Here is an improved way to handle this issue with fetch_token feature:

def fetch_twitter_token(request):
    item = OAuth1Token.objects.get(
        name='twitter',
        user=request.user
    )
    return item.to_token()

# we can registry this ``fetch_token`` with oauth.register
oauth.register(
    '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,
    # NOTICE HERE
    fetch_token=fetch_twitter_token,
)

Developers can also pass the fetch_token to OAuth registry so that they don’t have to pass a fetch_token for each remote app. In this case, the fetch_token will accept two parameters:

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

    item = model.objects.get(
        name=name,
        user=request.user
    )
    return item.to_token()

oauth = OAuth(fetch_token=fetch_token)

Now, developers don’t have to pass a token in the HTTP requests, instead, they can pass the request:

def fetch_resource(request):
    resp = oauth.twitter.get('account/verify_credentials.json', request=request)
    profile = resp.json()
    # ...

Code Challenge¶

Adding code_challenge provided by RFC7636: Proof Key for Code Exchange by OAuth Public Clients is simple. You register your remote app with a code_challenge_method:

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=None,
    code_challenge_method='S256',
)

Note, the only supportted code_challenge_method is S256.

Compliance Fix¶

The RemoteApp is a subclass of OAuthClient, they share the same logic for compliance fix. Construct a method to fix requests session:

def slack_compliance_fix(session):
    def _fix(resp):
        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)

When OAuth.register() a remote app, pass it in the parameters:

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

Find all the available compliance hooks at Compliance Fix for non Standard.

OAuth 1 Flow¶

Configure an OAuth 1 client with OAuthClient:

client = OAuthClient(
    client_id='Twitter Consumer Key',
    client_secret='Twitter Consumer Secret',
    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/',
)

There are other options that you could pass to the class. Please read the API documentation.

def save_request_token(token):
    session['token'] = token

# The first ``redirect_uri`` parameter is optional.
url, state = client.generate_authorize_redirect(
    save_request_token=save_request_token)

def get_request_token():
    return session.pop('token', None)

redirect_uri = session.pop('redirect_uri', None)
params = parse_response_url_qs()
token = client.fetch_access_token(
    redirect_uri, get_request_token=get_request_token, **params)
save_token_to_db(token)

OAuth 2 Flow¶

The flow of OAuth 2 is similar with OAuth 1, and much simpler:

client = OAuthClient(
    client_id='GitHub Client ID',
    client_secret='GitHub Client Secret',
    api_base_url='https://api.github.com/',
    access_token_url='https://github.com/login/oauth/access_token',
    authorize_url='https://github.com/login/oauth/authorize',
    client_kwargs={'scope': 'user:email'},
)

redirect_uri = 'https://example.com/auth'
url, state = client.generate_authorize_redirect(redirect_uri)
# save state for getting access token
session['state'] = state

redirect_uri = session.pop('redirect_uri', None)
params = parse_response_url_qs()
# you need to verify state here
assert params['state'] == session.pop('state')
token = client.fetch_access_token(redirect_uri, **params)
save_token_to_db(token)

Compliance Fix¶

Since many OAuth 2 providers are not following standard strictly, we need to fix them. It has been introduced in Compliance Fix for non Standard.

For OAuthClient, we can register our hooks one by one, with OAuth2Session.register_compliance_hook():

client.session.register_compliance_hook('protected_request', func)

However, there is a shortcut attribute for it. You need to construct a method which takes session as the parameter:

def compliance_fix(session):

    def fix_protected_request(url, headers, data):
        # do something
        return url, headers, data

    def fix_access_token_response(response):
        # patch response
        return response

    session.register_compliance_hook(
        'protected_request', fix_protected_request)
    session.register_compliance_hook(
        'access_token_response', fix_access_token_response)
    # register other hooks

Later, when you initialized OAuthClient, pass it to the client parameters:

client = OAuthClient(
    client_id='...',
    client_secret='...',
    ...,
    compliance_fix=compliance_fix,
    ...
)

It will automatically patch the requests session for OAuth 2.

Sessions and Client¶

class authlib.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.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.client.OAuth2Session(client_id=None, client_secret=None, token_endpoint_auth_method=None, refresh_token_url=None, refresh_token_params=None, scope=None, redirect_uri=None, token=None, token_placement='header', state=None, token_updater=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. token_endpoint_auth_method – Client auth method for token endpoint. refresh_token_url – Refresh Token endpoint for auto refresh token. refresh_token_params – Extra parameters for refresh token endpoint. scope – Scope that you needed to access user resources. 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”. state – State string used to prevent CSRF. This will be given when creating the authorization url and must be supplied when parsing the authorization response. token_updater – A function for you to update token. It accept a OAuth2Token as parameter.

create_authorization_url(url, state=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. kwargs – Extra parameters to include.
Returns:	authorization_url, state

fetch_access_token(url=None, **kwargs)¶

Alias for fetch_token.

fetch_token(url=None, code=None, authorization_response=None, body='', auth=None, username=None, password=None, method='POST', headers=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). code – Authorization code (if any) authorization_response – Authorization response URL, the callback URL of the request back to you. We can extract authorization code from it. 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. username – Username of the resource owner for password grant. password – Password of the resource owner for password grant. 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.

Returns:

A OAuth2Token object (a dict too).

refresh_token(url=None, 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(func)¶

Extend client authenticate for token endpoint.

Parameters:	func – a function 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_response: invoked before refresh token parsing.
• protected_request: invoked before making a request.
• revoke_token_request: invoked before revoking a token.

revoke_token(url, token, 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:

A OAuth2Token object (a dict too).

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

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

refresh_token()¶

Using Assertions as Authorization Grants to refresh token as described in Section 4.1.

request(method, url, data=None, headers=None, withhold_token=False, auth=None, **kwargs)¶

Send request with auto refresh token feature.

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

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

class authlib.client.OAuthClient(client_id=None, client_secret=None, request_token_url=None, request_token_params=None, access_token_url=None, access_token_params=None, refresh_token_url=None, refresh_token_params=None, authorize_url=None, authorize_params=None, api_base_url=None, client_kwargs=None, server_metadata_url=None, compliance_fix=None, **kwargs)¶

A mixed OAuth client for OAuth 1 and OAuth 2.

Parameters:

client_id – Client key of OAuth 1, or Client ID of OAuth 2 client_secret – Client secret of OAuth 2, or Client Secret of OAuth 2 request_token_url – Request Token endpoint for OAuth 1 request_token_params – Extra parameters for Request Token endpoint access_token_url – Access Token endpoint for OAuth 1 and OAuth 2 access_token_params – Extra parameters for Access Token endpoint refresh_token_url – Refresh Token endpoint for OAuth 2 (if any) refresh_token_params – Extra parameters for Refresh Token endpoint authorize_url – Endpoint for user authorization of OAuth 1 ro OAuth 2 authorize_params – Extra parameters for Authorization Endpoint api_base_url – The base API endpoint to make requests simple client_kwargs – Extra keyword arguments for session server_metadata_url – Discover server metadata from this URL kwargs – Extra keyword arguments

Create an instance of OAuthClient. If request_token_url is configured, it would be an OAuth 1 instance, otherwise it is OAuth 2 instance:

oauth1_client = OAuthClient(
    client_id='Twitter Consumer Key',
    client_secret='Twitter Consumer Secret',
    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/',
)

oauth2_client = OAuthClient(
    client_id='GitHub Client ID',
    client_secret='GitHub Client Secret',
    api_base_url='https://api.github.com/',
    access_token_url='https://github.com/login/oauth/access_token',
    authorize_url='https://github.com/login/oauth/authorize',
    client_kwargs={'scope': 'user:email'},
)

generate_authorize_redirect(redirect_uri=None, save_request_token=None, **kwargs)¶

Generate the authorization url and state for HTTP redirect.

Parameters:	redirect_uri – Callback or redirect URI for authorization. save_request_token – A function to save request token. kwargs – Extra parameters to include.
Returns:	(url, state)

fetch_access_token(redirect_uri=None, request_token=None, **params)¶

Fetch access token in one step.

Parameters:	redirect_uri – Callback or Redirect URI that is used in previous authorize_redirect(). request_token – A previous request token for OAuth 1. params – Extra parameters to fetch access token.
Returns:	A token dict.

get(url, **kwargs)¶

Invoke GET http request.

If api_base_url configured, shortcut is available:

client.get('users/lepture')

post(url, **kwargs)¶

Invoke POST http request.

If api_base_url configured, shortcut is available:

client.post('timeline', json={'text': 'Hi'})

patch(url, **kwargs)¶

Invoke PATCH http request.

If api_base_url configured, shortcut is available:

client.patch('profile', json={'name': 'Hsiaoming Yang'})

put(url, **kwargs)¶

Invoke PUT http request.

If api_base_url configured, shortcut is available:

client.put('profile', json={'name': 'Hsiaoming Yang'})

delete(url, **kwargs)¶

Invoke DELETE http request.

If api_base_url configured, shortcut is available:

client.delete('posts/123')

Flask Registry and RemoteApp¶

class authlib.flask.client.OAuth(app=None, cache=None, fetch_token=None, update_token=None)¶

Registry for oauth clients.

Parameters:	app – the app instance of Flask

Create an instance with Flask:

oauth = OAuth(app, cache=cache)

You can also pass the instance of Flask later:

oauth = OAuth()
oauth.init_app(app, cache=cache)

Parameters:	app – Flask application instance cache – A cache instance that has .get .set and .delete methods fetch_token – a shared function to get current user’s token update_token – a share function to update current user’s token

init_app(app, cache=None, fetch_token=None, update_token=None)¶

Init app with Flask instance.

register(name, overwrite=False, **kwargs)¶

Registers a new remote application.

Parameters:	name – Name of the remote application. overwrite – Overwrite existing config with Flask config. kwargs – Parameters for RemoteApp.

Find parameters from OAuthClient. When a remote app is registered, it can be accessed with named attribute:

oauth.register('twitter', client_id='', ...)
oauth.twitter.get('timeline')

class authlib.flask.client.RemoteApp(name, fetch_token=None, update_token=None, fetch_request_token=None, save_request_token=None, **kwargs)¶

Flask integrated RemoteApp of OAuthClient. It has built-in hooks for OAuthClient. The only required configuration is token model.

authorize_access_token(**kwargs)¶

Authorize access token.

authorize_redirect(redirect_uri=None, **kwargs)¶

Create a HTTP Redirect for Authorization Endpoint.

Parameters:	redirect_uri – Callback or redirect URI for authorization. kwargs – Extra parameters to include.
Returns:	A HTTP redirect response.

save_authorize_state(redirect_uri=None, state=None)¶

Save redirect_uri and state into session during authorize step.

Django Registry and RemoteApp¶

class authlib.django.client.OAuth(fetch_token=None)¶

Registry for oauth clients.

Create an instance for registry:

oauth = OAuth()

register(name, overwrite=False, **kwargs)¶

Registers a new remote application.

Parameters:	name – Name of the remote application. overwrite – Overwrite existing config with django settings. kwargs – Parameters for RemoteApp.

Find parameters from OAuthClient. When a remote app is registered, it can be accessed with named attribute:

oauth.register('twitter', client_id='', ...)
oauth.twitter.get('timeline')

class authlib.django.client.RemoteApp(name, fetch_token=None, **kwargs)¶

Django integrated RemoteApp of OAuthClient. It has built-in hooks for OAuthClient.

authorize_access_token(request, **kwargs)¶

Fetch access token in one step.

Parameters:	request – HTTP request instance from Django view.
Returns:	A token dict.

authorize_redirect(request, redirect_uri=None, **kwargs)¶

Create a HTTP Redirect for Authorization Endpoint.

Parameters:	request – HTTP request instance from Django view. redirect_uri – Callback or redirect URI for authorization. kwargs – Extra parameters to include.
Returns:	A HTTP redirect response.

save_authorize_state(request, redirect_uri=None, state=None)¶

Save redirect_uri and state into session during authorize step.

Compact Serialize and Deserialize¶

Generate a JWS compact serialization would be easy with JWS.serialize_compact(), build a JWS instance with JWA:

from authlib.jose import JWS
from authlib.jose import JWS_ALGORITHMS

jws = JWS(algorithms=JWS_ALGORITHMS)
# alg is a required parameter name
protected = {'alg': 'HS256'}
payload = b'example'
secret = b'secret'
jws.serialize_compact(protected, payload, secret)

There are other alg that you could use. Here is a full list of available algorithms:

1. HS256, HS384, HS512
2. RS256, RS384, RS512
3. ES256, ES384, ES512
4. PS256, PS384, PS512

For example, a JWS with RS256 requires a private PEM key to sign the JWS:

jws = JWS(algorithms=JWS_ALGORITHMS)
protected = {'alg': 'RS256'}
payload = b'example'
with open('private.pem', 'rb') as f:
    secret = f.read()
jws.serialize_compact(protected, payload, secret)

To deserialize a JWS Compact Serialization, use JWS.deserialize_compact():

# if it is a RS256, we use public RSA key
with open('public.pem', 'rb') as f:
    key = f.read()
data = jws.deserialize_compact(s, key)
jws_header = data['header']
payload = data['payload']

A key can be dynamically loaded, if you don’t know which key to be used:

def load_key(header, payload):
    kid = header['kid']
    return get_key_by_kid(kid)

jws.deserialize_compact(s, load_key)

The result of the deserialize_compact is a dict, which contains header and payload. The value of the header is a JWSHeader.

Using JWK for keys? Find how to use JWK with JSON Web Key (JWK).

JSON Serialize and Deserialize¶

JWS.serialize_json() is used to generate a JWS JSON Serialization, JWS.deserialize_json() is used to extract a JWS JSON Serialization. The usage is the same as “Compact Serialize and Deserialize”, the only difference is the “header”:

# Flattened JSON serialization header syntax
header = {'protected': {'alg': 'HS256'}, 'header': {'cty': 'JWT'}}
key = b'secret'
payload = b'example'
jws.serialize_json(header, payload, key)

# General JSON serialization header syntax
header = [{'protected': {'alg': 'HS256'}, 'header': {'cty': 'JWT'}}]
jws.serialize_json(header, payload, key)

For general JSON Serialization, there may be many signatures, each signature can use its own key, in this case the dynamical key would be useful:

def load_private_key(header, payload):
    kid = header['kid']
    return get_private_key(kid)

header = [
    {'protected': {'alg': 'HS256'}, 'header': {'kid': 'foo'}},
    {'protected': {'alg': 'RS256'}, 'header': {'kid': 'bar'}},
]
data = jws.serialize_json(header, payload, load_private_key)
# data is a dict

def load_public_key(header, payload):
    kid = header['kid']
    return get_public_key(kid)

jws.deserialize_json(data, load_public_key)

Actually, there is a JWS.serialize() and JWS.deserialize(), which can automatically serialize and deserialize Compact and JSON Serializations.

The result of the deserialize_json is a dict, which contains header and payload. The value of the header is a JWSHeader.

Using JWK for keys? Find how to use JWK with JSON Web Key (JWK).

private_headers = ['h1', 'h2']
jws = JWS(algorithms=JWS_ALGORITHMS, private_headers=private_headers)

Compact Serialize and Deserialize¶

Generate a JWE compact serialization would be easy with JWE.serialize_compact(), build a JWE instance with JWA:

from authlib.jose import JWE
from authlib.jose import JWE_ALGORITHMS

jws = JWS(algorithms=JWS_ALGORITHMS)
protected = {'alg': 'RSA-OAEP', 'enc': 'A256GCM'}
payload = b'hello'
with open('rsa_public.pem', 'rb') as f:
    key = f.read()

s = jws.serialize_compact(protected, payload, key)

There are two required algorithms in protected header: alg and enc.

The available alg list:

1. RSA1_5, RSA-OAEP, RSA-OAEP-256
2. A128KW, A192KW, A256KW
3. A128GCMKW, A192GCMKW, A256GCMKW

The available enc list:

1. A128CBC-HS256, A192CBC-HS384, A256CBC-HS512
2. A128GCM, A192GCM, A256GCM

More alg and enc will be added in the future.

It is also available to compress the payload with zip header:

protected = {'alg': 'RSA-OAEP', 'enc': 'A256GCM', 'zip': 'DEF'}
s = jws.serialize_compact(protected, payload, key)

To deserialize a JWE Compact Serialization, use JWE.deserialize_compact():

with open('rsa_private.pem', 'rb') as f:
    key = f.read()

data = jwe.deserialize_compact(s, key)
jwe_header = data['header']
payload = data['payload']

The result of the deserialize_compact is a dict, which contains header and payload.

Using JWK for keys? Find how to use JWK with JSON Web Key (JWK).

JWT Payload Claims Validation¶

JWT.decode() accepts 3 claims-related parameters: claims_cls, claims_option and claims_params. The default claims_cls is JWTClaims. The decode method returns:

>>> JWTClaims(payload, header, options=claims_options, params=claims_params)

Claims validation is actually handled by JWTClaims.validate(), which validates payload claims with claims_option and claims_params. For standard JWTClaims, claims_params value is not used, but it is used in IDToken.

Here is an example of claims_option:

{
    "iss": {
        "essential": True,
        "values": ["https://example.com", "https://example.org"]
    },
    "sub": {
        "essential": True
        "value": "248289761001"
    },
    "jti": {
        "validate": validate_jti
    }
}

It is a dict configuration, the option key is the name of a claim.

• essential: this value is REQUIRED.
• values: claim value can be any one in the values list.
• value: claim value MUST be the same value.
• validate: a function to validate the claim value.

Resource Owner¶

Resource Owner is the user who is using your service. A resource owner can log in your website with username/email and password, or other methods.

A resource owner MUST implement get_user_id() method:

class User(db.Model):
    id = db.Column(db.Integer, primary_key=True)

    def get_user_id(self):
        return self.id

Client¶

A client is an application making protected resource requests on behalf of the resource owner and with its authorization. It contains at least three information:

• Client Identifier, usually called client_id
• Client Password, usually called client_secret
• Client RSA Public Key (if RSA-SHA1 signature method supported)

Authlib has provided a mixin for SQLAlchemy, define the client with this mixin:

from authlib.flask.oauth1.sqla import OAuth1ClientMixin

class Client(db.Model, OAuth1ClientMixin):
    id = db.Column(db.Integer, primary_key=True)
    user_id = db.Column(
        db.Integer, db.ForeignKey('user.id', ondelete='CASCADE')
    )
    user = db.relationship('User')

A client is registered by a user (developer) on your website. Get a deep inside with ClientMixin API reference.

Temporary Credentials¶

A temporary credential is used to exchange a token credential. It is also known as “request token and secret”. Since it is temporary, it is better to save them into cache instead of database. A cache instance should has these methods:

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

A cache can be a memcache, redis or something else. If cache is not available, there is also a SQLAlchemy mixin:

from authlib.flask.oauth1.sqla import OAuth1TemporaryCredentialMixin

class TemporaryCredential(db.Model, OAuth1TemporaryCredentialMixin):
    id = db.Column(db.Integer, primary_key=True)
    user_id = db.Column(
        db.Integer, db.ForeignKey('user.id', ondelete='CASCADE')
    )
    user = db.relationship('User')

To make a Temporary Credentials model yourself, get more information with ClientMixin API reference.

Token Credentials¶

A token credential is used to access resource owners’ resources. Unlike OAuth 2, the token credential will not expire in OAuth 1. This token credentials are supposed to be saved into a persist database rather than a cache.

Here is a SQLAlchemy mixin for easy integration:

from authlib.flask.oauth1.sqla import OAuth1TokenCredentialMixin

class TokenCredential(db.Model, OAuth1TokenCredentialMixin):
    id = db.Column(db.Integer, primary_key=True)
    user_id = db.Column(
        db.Integer, db.ForeignKey('user.id', ondelete='CASCADE')
    )
    user = db.relationship('User')

def set_user_id(self, user_id):
    self.user_id = user_id

If SQLAlchemy is not what you want, read the API reference of TokenCredentialMixin and implement the missing methods.

Timestamp and Nonce¶

The nonce value MUST be unique across all requests with the same timestamp, client credentials, and token combinations. Authlib Flask integration has a built-in validation with cache.

If cache is not available, there is also a SQLAlchemy mixin:

from authlib.flask.oauth1.sqla import OAuth1TokenCredentialMixin

class TimestampNonce(db.Model, OAuth1TokenCredentialMixin)
    id = db.Column(db.Integer, primary_key=True)

Define A Server¶

Authlib provides a ready to use AuthorizationServer which has built-in tools to handle requests and responses:

from authlib.flask.oauth1 import AuthorizationServer
from authlib.flask.oauth1.sqla import create_query_client_func

query_client = create_query_client_func(db.session, Client)
server = AuthorizationServer(app, query_client=query_client)

It can also be initialized lazily with init_app:

server = AuthorizationServer()
server.init_app(app, query_client=query_client)

It is strongly suggested that you use a cache. In this way, you don’t have to re-implement a lot of the missing methods.

There are other configurations. It works well without any changes. Here is a list of them:

These configurations are used to create the token_generator function. But you can pass the token_generator when initializing the AuthorizationServer:

def token_generator():
    return {
        'oauth_token': random_string(20),
        'oauth_token_secret': random_string(46)
    }

server = AuthorizationServer(
    app,
    query_client=query_client,
    token_generator=token_generator
)

Server Hooks¶

There are missing hooks that should be register_hook to AuthorizationServer. There are helper functions for registering hooks. If cache is available, you can take the advantage with:

from authlib.flask.oauth1.cache import (
    register_nonce_hooks,
    register_temporary_credential_hooks
)
from authlib.flask.oauth1.sqla import register_token_credential_hooks

register_nonce_hooks(server, cache)
register_temporary_credential_hooks(server, cache)
register_token_credential_hooks(server, db.session, TokenCredential)

If cache is not available, here are the helpers for SQLAlchemy:

from authlib.flask.oauth1.sqla import (
    register_nonce_hooks,
    register_temporary_credential_hooks,
    register_token_credential_hooks
)

register_nonce_hooks(server, db.session, TimestampNonce)
register_temporary_credential_hooks(server, db.session, TemporaryCredential)
register_token_credential_hooks(server, db.session, TokenCredential)

Server Implementation¶

It is ready to create the endpoints for authorization and issuing tokens. Let’s start with the temporary credentials endpoint, which is used for clients to fetch a temporary credential:

@app.route('/initiate', methods=['POST'])
def initiate_temporary_credential():
    return server.create_temporary_credential_response()

The endpoint for resource owner authorization. OAuth 1 Client will redirect user to this authorization page, so that resource owner can grant or deny this request:

@app.route('/authorize', methods=['GET', 'POST'])
def authorize():
    # make sure that user is logged in for yourself
    if request.method == 'GET':
        try:
            req = server.check_authorization_request()
            return render_template('authorize.html', req=req)
        except OAuth1Error as error:
            return render_template('error.html', error=error)

    granted = request.form.get('granted')
    if granted:
        grant_user = current_user
    else:
        grant_user = None

    try:
        return server.create_authorization_response(grant_user)
    except OAuth1Error as error:
        return render_template('error.html', error=error)