本指南围绕 Authlib 官方文档 docs/oauth2/client/http/index.rst 及其配套的 requests 集成指南、httpx 集成指南 与 API 参考 展开，系统讲解 Authlib 提供的三类 OAuth 2.0 HTTP 客户端：requests_client.OAuth2Session、httpx_client.AsyncOAuth2Client以及断言（Assertion/Service Account）客户端，覆盖授权码、隐式、密码、客户端凭证四种授权流程，以及 PKCE、客户端认证、Token 自动刷新、撤销、内省、非标准服务兼容（Compliance Fix）与 OpenID Connect 集成等实战能力。读完本文，你将能够在自己的 Python 项目中直接落地一套可复用的 OAuth 2.0 客户端接入方案。

一、认识 Authlib 的 OAuth 2.0 HTTP 客户端

Authlib 为 Python 生态中最流行的两个 HTTP 库提供了 OAuth 2.0 客户端实现，它们共享同一套 API 设计：

requests_client.OAuth2Session与httpx_client.AsyncOAuth2Client的核心方法完全一致，均继承自协议层基类OAuth2Client（见 authlib/oauth2/client.py），因此本文的多数示例可无缝切换使用。API 参考文档 docs/oauth2/client/http/api.rst 中列出的公开方法为：

• register_client_auth_method：注册自定义客户端认证方法
• create_authorization_url：构造授权端点 URL
• fetch_token：向 Token 端点换取访问令牌
• refresh_token：刷新访问令牌
• revoke_token：撤销令牌（RFC 7009）
• introspect_token：内省令牌（RFC 7662）
• register_compliance_hook：注册兼容性钩子

以下各节将逐一讲解这些方法的实战用法与底层原理。

二、授权码流程（Authorization Code）完整实操

授权码流程分两步：先将用户重定向到授权服务器，再用回调中的code换取令牌。以 GitHub 为例：

client_id = 'Your GitHub client ID' client_secret = 'Your GitHub client secret' scope = 'user:email' # 我们想要获取用户的邮箱 # 使用 requests 实现 from authlib.integrations.requests_client import OAuth2Session client = OAuth2Session(client_id, client_secret, scope=scope) # 使用 httpx2 实现（异步） from authlib.integrations.httpx_client import AsyncOAuth2Client client = AsyncOAuth2Client(client_id, client_secret, scope=scope)

如需指定回调地址，可通过redirect_uri参数指定。从 authlib/oauth2/client.py 的create_authorization_url源码可以看到，redirect_uri和scope未显式传入时会被自动填充到授权请求中。

2.1 重定向到授权端点

与 OAuth 1 不同，OAuth 2 没有 request token 环节。第一步是把用户带到远程授权服务器：

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

create_authorization_url返回(uri, state)元组。真实项目中，你必须保存state以备后续校验（CSRF 防护）。从源码看，未显式传入state时，Authlib 会调用generate_token()自动生成一个随机 state。

2.2 用回调 code 换取令牌

授权服务器完成授权后，会带着code和state参数重定向回你的站点：

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

调用.fetch_token换取访问令牌，该方法会自动校验state以防止 CSRF 攻击：

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' # }

拿到令牌后即可访问用户受保护资源。测试 tests/clients/test_requests/test_oauth2_session.py 中的test_mis_match_state验证了state不匹配时会抛出MismatchingStateException。

重要：由于真实流程中浏览器会跳转到另一个网站，同一个 session 无法被复用。回调阶段需要重新创建 session，并传入之前保存的state：

state = restore_previous_state() # 使用 requests from authlib.integrations.requests_client import OAuth2Session client = OAuth2Session(client_id, client_secret, state=state) # 使用 httpx2（异步） 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)

Authlib 内置的 Flask/Django 集成已封装好这套流程，可参考 docs/oauth2/client/web/index.rst 中对应框架章节。

2.3 grant_type 的自动推导

fetch_token内部会根据传入参数自动猜测grant_type（见 authlib/oauth2/client.py 的_guess_grant_type）：

• 参数中含code→authorization_code
• 参数中同时含username和password→password
• 其余情况 →client_credentials

也可以通过grant_type参数显式指定。此外，fetch_token支持method="GET"等非常规 Token 请求方式，测试 test_fetch_token_get 验证了 GET 方式下参数会拼入 URL。

2.4 为授权码流程添加 PKCE（RFC 7636）

Authlib 客户端可以自动处理 PKCE，只需在create_authorization_url和fetch_token中传入code_verifier：

from authlib.common.security import generate_token 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)

从 authlib/oauth2/client.py 的源码可以看到，当code_verifier存在、response_type == "code"且code_challenge_method == "S256"时，客户端会自动计算code_challenge并附加到授权 URL。S256挑战值的算法在 authlib/oauth2/rfc7636/challenge.py 中实现：BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))，并校验code_verifier必须符合[a-zA-Z0-9\-._~]{43,128}的 RFC 规范。测试 test_code_challenge 验证了授权 URL 中会携带code_challenge与code_challenge_method=S256参数。

三、其余三种授权流程

3.1 隐式流程（Implicit）

OAuth2Session支持隐式授权，只需将response_type设为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&...

用户授权后，授权服务器会重定向到你的redirect_uri，响应 URL 形如：

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

使用.fetch_token从 URL fragment 中解析访问令牌（注意此时无需传入 token endpoint）：

token = client.fetch_token(authorization_response=authorization_response) print(token) # {'access_token': '2..WpA', 'token_type': 'bearer', 'expires_in': 3600}

其底层实现是 authlib/oauth2/client.py：当authorization_response含#时直接走token_from_fragment分支，调用parse_implicit_response解析 fragment 参数。

注意：GitHub 不支持token响应类型，请使用其他支持的服务测试。

3.2 密码流程（Password）

密码授权自 Version 0.5 起支持，直接传入username和password换取令牌：

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

3.3 客户端凭证流程（Client Credentials）

若不传code也没有用户信息，fetch_token会默认发起client_credentials请求，但建议显式指定grant_type：

token = client.fetch_token(token_endpoint) # 或显式指定 token = client.fetch_token(token_endpoint, grant_type='client_credentials')

对应测试见 test_client_credentials_type，其中验证了请求体包含grant_type=client_credentials且自动携带已配置的scope。

四、客户端认证（Client Authentication）

在 Token 端点换取令牌时，授权服务器通常要求客户端认证。Authlib 依据 RFC 7591 提供三种默认认证方法：

默认值为client_secret_basic。从 authlib/oauth2/client.py 的源码可以看到：当未指定token_endpoint_auth_method时，若有client_secret则默认client_secret_basic，否则默认none（公开客户端）；revocation_endpoint_auth_method遵循同样的推断逻辑。通过token_endpoint_auth_method可切换认证方法：

client = OAuth2Session(token_endpoint_auth_method='client_secret_post')

如果授权服务器需要其他认证手段，可以自行构造auth对象并传给fetch_token：

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

4.1 扩展客户端认证方法

除了三种默认方法，还可以通过.register_client_auth_method扩展。Authlib 额外提供了两种由 RFC 7523 与 OpenID Connect 定义的 JWT 认证方法：

• client_secret_jwt：用client_secret构造 JWT 认证（默认算法 HS256）
• private_key_jwt：用私钥构造 JWT 认证（默认算法 RS256）

requests 版本用法（完整示例见 docs/oauth2/client/http/requests.rst）：

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)

httpx 异步版本用法（见 docs/oauth2/client/http/httpx.rst）：

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)

ClientSecretJWT/PrivateKeyJWT的实现在 authlib/oauth2/rfc7523/auth.py，二者都会在请求体中追加client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer与client_assertion参数。JWT 载荷按照 RFC 7523 构造：iss和sub均为client_id，aud为 Token 端点 URL，并自动生成唯一jti防重放（见 authlib/oauth2/rfc7523/assertion.py）。

4.2 自定义认证方法：client_secret_uri实战

有些非标准服务要求把client_id和client_secret拼在 URL 上发送 POST 请求（对应 GitHub issue #158 的场景）：

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

自定义一个名为client_secret_uri的认证方法即可解决：

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

注册后，客户端将以带签名的 URI 完成认证。也可以直接把函数赋给token_endpoint_auth_method：

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

其内部原理见 authlib/oauth2/client.py：register_client_auth_method接受(名称, 函数)元组或带name属性的实例，存入_auth_methods字典；client_auth()在fetch_token、refresh_token、revoke_token、introspect_token时按名称查找并构造ClientAuth，最终调用认证函数改写(uri, headers, body)。

五、访问受保护资源

拿到令牌后即可请求受保护资源。如果复用同一个 session，无需任何额外操作：

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

但真实流程中（如前面授权码章节所述）需要新建 session 并载入之前保存的令牌：

token = restore_previous_token_from_database() # token 是一个必须包含 access_token、token_type 的字典 client = OAuth2Session(client_id, client_secret, token=token) account_url = 'https://api.github.com/user' resp = client.get(account_url)

令牌放置位置（token_placement）：Bearer 令牌默认放在请求头Authorization: Bearer <token>中，也可通过token_placement参数改为body或uri（见 authlib/oauth2/auth.py 与 authlib/oauth2/rfc6750/parameters.py）。测试 test_add_token_to_header/body/uri 逐一验证了三种放置方式。

单独使用 OAuth2Auth：如果令牌已到手，也可以在 requests 中直接使用OAuth2Auth完成请求签名——但它不会自动刷新令牌：

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

OAuth2Auth的实现在 authlib/integrations/requests_client/oauth2_session.py，它内部把令牌转成OAuth2Token并按token_type签名请求；遇到不支持的token_type会抛出UnsupportedTokenTypeError。

六、刷新与自动更新令牌

令牌过期后，可以手动刷新；更佳方案是让 Authlib 在请求资源时自动刷新并更新令牌。

6.1 自动刷新（需配置 token_endpoint）

如果创建OAuth2Session时传入了token_endpoint参数，Authlib 会在令牌过期时自动刷新：

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

默认在令牌实际过期前 60 秒就视为过期并触发刷新，以避免时钟偏差（clock skew）问题。该提前量通过leeway参数控制，默认值为 60（见 authlib/oauth2/client.py）。过期判定逻辑在 authlib/oauth2/rfc6749/wrappers.py 的OAuth2Token.is_expired(leeway)：expires_at - leeway < time.time()即为过期。测试 test_token_status2 演示了leeway对过期判定的影响。

6.2 手动刷新

调用refresh_token用refresh_token换取新的access_token：

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

从 authlib/oauth2/client.py 的源码可见，未显式传入refresh_token时会自动从当前令牌中读取，且若未配置scope会沿用初始化时的 scope；刷新成功后如果响应中没有新的refresh_token，客户端会保留旧值（见 authlib/oauth2/client.py）。

6.3 通过 update_token 自动持久化

Authlib 还支持在请求资源时自动刷新并调用你定义的update_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 # 更新旧令牌 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)

此后发送资源请求时，如果之前保存的令牌已过期，客户端会自动调用.refresh_token并回调update_token保存新令牌：

token = restore_previous_token_from_database() client.token = token # 如果令牌已过期，这次 GET 会自动完成令牌刷新 client.get('https://openidconnect.googleapis.com/v1/userinfo')

测试 test_auto_refresh_token 验证了过期令牌下 GET 请求会触发update_token；而client_credentials场景（test_auto_refresh_token2）中，仅当传入update_token时才会在令牌过期后自动重取。

异步版本：AsyncOAuth2Client的update_token既可以是同步函数也可以是async函数：

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 # 更新旧令牌 item.access_token = token['access_token'] item.refresh_token = token.get('refresh_token') item.expires_at = token['expires_at'] await item.save()

值得注意的一个实现细节：AsyncOAuth2Client内部使用anyio.Lock同步协程（见 authlib/integrations/httpx_client/oauth2_client.py），防止并发请求同时触发多次令牌刷新。测试 test_auto_refresh_token4 用asyncio.gather并发发起 10 个请求，最终update_token只被调用一次。

七、撤销与内省令牌

如果服务商支持令牌撤销（RFC 7009）与内省（RFC 7662），可以这样使用：

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)

两个方法均支持token_type_hint参数（access_token或refresh_token），并会自动携带客户端认证（revoke_token使用revocation_endpoint_auth_method，introspect_token使用token_endpoint_auth_method，见 authlib/oauth2/client.py）。未显式传token时，客户端会优先取refresh_token再取access_token。对应测试见 test_revoke_token 与 test_revoke_token。

八、Compliance Fix：适配非标准服务

有些自称提供 OAuth API 的服务与标准存在细微差异，甚至返回错误的 Content-Type。Authlib 通过 compliance hooks 解决这类问题，可用的钩子类型：

此外，源码 authlib/oauth2/client.py 还定义了refresh_token_request、revoke_token_request、introspect_token_request三类请求钩子；protected_request钩子被挂载到token_auth.hooks，在每次令牌签名后执行。

以 Stackoverflow 为例：它要求必须在查询字符串中附加site参数以保护用户资源，且其响应不是 JSON 格式。可以这样修复：

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)

对非protected_request类型的钩子，register_compliance_hook会校验钩子类型是否在预定义集合内，非法类型直接抛出ValueError（测试见 test_register_compliance_hook）。

九、OAuth 2 + OpenID Connect：解析 id_token

对支持 OpenID Connect 的服务，只要 scope 中包含openid，授权服务器就会在响应中返回id_token：

client_id = 'Your Google client ID' client_secret = 'Your Google client secret' scope = 'openid email profile' # 使用 requests client = OAuth2Session(client_id, client_secret, scope=scope) # 使用 httpx2 client = AsyncOAuth2Client(client_id, client_secret, scope=scope)

某些远程服务要求额外的 OpenID Connect 参数（例如nonce），你需要自己生成并传入create_authorization_url：

from authlib.common.security import generate_token # 记得保存这个 nonce 供后续校验 nonce = generate_token() client.create_authorization_url(url, redirect_uri='xxx', nonce=nonce, ...)

fetch_token的返回值中包含id_token：

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

id_token是一段 JWT 文本，必须解析后才能使用。Authlib 提供了 OpenID Connect 的解析与校验工具：

from authlib.oidc.core import CodeIDToken from joserfc import jwt # 从 https://www.googleapis.com/oauth2/v3/certs 获取 keys token = jwt.decode(resp['id_token'], keys) claims = CodeIDToken(token.claims, token.header) claims.validate()

自 Authlib 1.7 起，JWT 编解码统一使用 joserfc 库，可参考 docs/upgrades/jose.rst 了解相关变更。

十、断言客户端（AssertionSession / Service Account）

AssertionSession是 OAuth 2.0 授权框架（RFC 7521）的 requests 实现，即通常所说的Service Account（服务账号）。配置好的AssertionSession会自动处理令牌授权——直接使用即可。

以 Google Service Account 为例，使用服务账号 JSON 配置文件中的信息：

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 将 scope 放在 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(...)

异步版本（AsyncAssertionClient，见 docs/oauth2/client/http/httpx.rst）：

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 将 scope 放在 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(...)

其底层行为见 authlib/oauth2/rfc7521/client.py 与 authlib/integrations/requests_client/assertion_session.py：

• 构造函数必须提供token_endpoint、issuer、subject；audience未指定时默认等于token_endpoint；
• 每次请求前若令牌缺失或过期（AssertionAuth.ensure_active_token），会自动调用refresh_token()生成新的 JWT 断言并换发令牌；
• 断言 JWT 默认使用jwt-bearer授权类型（urn:ietf:params:oauth:grant-type:jwt-bearer），签名算法由header中的alg决定，缺少alg会抛出ValueError；
• JWT 载荷自动包含iss、aud、iat、exp（默认有效期 3600 秒）以及自动生成的唯一jti（防重放）；每次刷新都会生成新的jti。

这些行为均有测试覆盖：tests/clients/test_requests/test_assertion_session.py（断言请求体含assertion=参数）、test_assertion_includes_default_jti（jti为 36 位唯一值）、test_assertion_jti_is_unique_per_refresh（每次刷新jti不同）。

十一、会话关闭与自签名证书

11.1 正确关闭会话

开发者应当在任务完成后关闭 requests/httpx 会话，以释放底层连接。可以手动调用.close()，或使用with上下文自动关闭：

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

httpx 同步客户端用法相同；异步客户端则需要await client.close()：

client = OAuth2Client(client_id, client_secret) client.get(url) client.close() with OAuth2Client(client_id, client_secret) as client: client.get(url) # 异步版本 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)

Authlib 的内置 Web 框架客户端（Flask/Django/Starlette/FastAPI）会自动关闭每个会话，无需手动处理。

11.2 自签名证书（RFC 8705 第 2.2 节）

对于使用自签名证书做双向 TLS 的场景，可以通过环境变量CURL_CA_BUNDLE和REQUESTS_CA_BUNDLE指定 CA 证书文件：

REQUESTS_CA_BUNDLE=/path/to/ca-cert.pem

请务必只在开发环境中设置该环境变量。

十二、API 一览

下表汇总 docs/oauth2/client/http/api.rst 中列出的核心 API 及其在OAuth2Session（requests）与AsyncOAuth2Client（httpx）两套实现中的行为：

构造函数常用参数（见 authlib/integrations/requests_client/oauth2_session.py 的 docstring）：client_id、client_secret、authorization_endpoint、token_endpoint、token_endpoint_auth_method、revocation_endpoint、revocation_endpoint_auth_method、scope、state、redirect_uri、token、token_placement（header/body/uri）、update_token、leeway（默认 60 秒）、default_timeout。requests 版本额外支持proxies、verify、cert、trust_env等会话级配置（见 authlib/integrations/requests_client/utils.py）。

十三、延伸阅读

• HTTP 客户端总览与授权码流程示例
• OAuth 2.0 for Requests（含 JWT 客户端认证与 OAuth2Auth）
• OAuth 2.0 for HTTPX2（含异步用法与断言客户端）
• OAuth 2.0 概念导读
• RFC 7523：JWT 客户端认证与断言授权
• Web 框架客户端（Flask/Django/Starlette/FastAPI）
• JWT / JOSE 指南

如果需要将这套 HTTP 客户端接入 Web 框架（自动完成 state 管理、token 持久化与会话生命周期管理），建议直接使用 Authlib 内置的 Flask/Django/Starlette/FastAPI 集成，它们构建在本指南所述的同一套 OAuth 2.0 客户端核心之上。