This is the documentation of the development version, check the Stable Version documentation.

Starlette OAuth Client

This documentation covers OAuth 1.0, OAuth 2.0 and OpenID Connect Client support for Starlette. Because all the frameworks integrations share the same API, it is best to read Web OAuth Clients at first.

The difference between Starlette and Flask/Django integrations is Starlette is async. We will use await for the functions we need to call. But first, let’s create an OAuth instance:

from authlib.integrations.starlette_client import OAuth

oauth = OAuth()

The common use case for OAuth is authentication, e.g. let your users log in with Twitter, GitHub, Google etc.

Register Remote Apps

oauth.register is the same as Web OAuth Clients, please read that documentation at first.

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

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.

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.

Using FastAPI

Developers may not use starlette directly. For instance, FastAPI is based on starlette, we can also use the starlette integration in FastAPI.

Since Authlib starlette requires using request instance, we need to expose that request to Authlib. According to the documentation on Using the Request Directly:

from starlette.requests import Request

@app.get("/login")
def login_via_google(request: Request):
    redirect_uri = 'https://example.com/auth'
    return await oauth.google.authorize_redirect(request, redirect_uri)

@app.get("/auth")
def auth_via_google(request: Request):
    token = await oauth.google.authorize_access_token(request)
    user = await oauth.google.parse_id_token(request, token)
    return dict(user)

Find out our demo on how to use starlette integration at https://github.com/authlib/demo-oauth-client