RestSharp 认证机制完全指南：从 Basic、OAuth1 到 JWT 与自定义 Authenticator

后端API设计【免费下载链接】RestSharpSimple REST and HTTP API Client for .NET项目地址https://gitcode.com/gh_mirrors/re/RestSharp点击查看免费下载RestSharp 内置了一套分层清晰的认证体系覆盖 HTTP Basic、OAuth1含 xAuth 与 0-legged 流程、OAuth2 令牌携带以及 JWT Bearer Token 等常见场景同时通过IAuthenticator接口与AuthenticatorBase抽象基类支持完全自定义的认证逻辑。本文将基于 RestSharp v112 版本文档authenticators.md结合仓库源码与测试用例逐一拆解各类认证器的构造方式、配置位置、底层实现与调用时机帮助你为不同类型的 API 客户端选择并落地正确的认证方案。认证器的两种挂载方式RestSharp 允许你把认证器挂载在两个层级上二者取其一即可客户端级client-wide通过RestClientOptions.Authenticator属性设置作用于该客户端发起的每一次请求适合整个 API 服务使用同一种认证方式的场景var options new RestClientOptions(https://example.com) { Authenticator new HttpBasicAuthenticator(username, password) }; var client new RestClient(options);请求级per-request通过RestRequest.Authenticator属性设置只对当前这一次请求生效适合同一客户端内不同接口使用不同认证方式的场景var request new RestRequest(/api/users/me) { Authenticator new HttpBasicAuthenticator(username, password) }; var response await client.ExecuteAsync(request, cancellationToken);从源码实现看无论哪种挂载方式最终认证逻辑都收敛到同一个接口。IAuthenticator 的定义极为精简只有一个异步方法public interface IAuthenticator { ValueTask Authenticate(IRestClient client, RestRequest request, CancellationToken cancellationToken default); }也就是说任何认证器本质上都是在请求发出前往RestRequest上附加认证参数的一段逻辑。RestSharp 内置认证器大多继承自 AuthenticatorBase该基类保存了一个可变的Token字符串并通过一个抽象方法把令牌转换为请求参数public abstract class AuthenticatorBase(string token) : IAuthenticator { protected string Token { get; set; } token; protected abstract ValueTaskParameter GetAuthenticationParameter(string accessToken); public async ValueTask Authenticate(IRestClient client, RestRequest request, CancellationToken cancellationToken default) request.AddOrUpdateParameter(await GetAuthenticationParameter(Token).ConfigureAwait(false)); }因此RestSharp 所有内置认证器的职责都很单一把认证信息翻译成一个Parameter通常是HeaderParameter也可能是GetOrPostParameter再通过AddOrUpdateParameter附加到请求上。这一设计也让自定义认证器变得非常直接。Basic 认证HttpBasicAuthenticator用于 HTTP Basic 访问认证。它把username:password按 Base64 编码后放入Authorization请求头编码结果以Basic前缀开头。最常用的两参数构造方式var options new RestClientOptions(https://example.com) { Authenticator new HttpBasicAuthenticator(username, password) }; var client new RestClient(options);从 HttpBasicAuthenticator 源码可以看到它还提供一个三参数重载允许指定字符编码public class HttpBasicAuthenticator(string username, string password, Encoding encoding) : AuthenticatorBase(GetHeader(username, password, encoding)) { public HttpBasicAuthenticator(string username, string password) : this(username, password, Encoding.UTF8) { } static string GetHeader(string username, string password, Encoding encoding) Convert.ToBase64String(encoding.GetBytes(${username}:{password})); protected override ValueTaskParameter GetAuthenticationParameter(string accessToken) new(new HeaderParameter(KnownHeaders.Authorization, $Basic {accessToken})); }要点说明默认使用UTF-8编码拼接username:password后做 Base64部分旧服务器可能期望 ISO-8859-1 编码此时可以传入自定义Encoding。编码在构造器里一次性完成之后每次请求都复用同一个 Base64 字符串。认证参数以 HeaderParameter 形式写入Authorization头。仓库测试 HttpBasicAuthTests.cs 对该行为有专门覆盖。OAuth1OAuth1 是签名型认证协议RestSharp 的OAuth1Authenticator会为请求自动生成并附加所需的 OAuth 参数与签名。它默认使用HMAC-SHA1生成签名但每个静态工厂方法都支持通过signatureMethod参数切换算法。底层签名与参数生成由 OAuthWorkflow 完成它负责生成oauth_timestamp、oauth_nonce、oauth_signature_method、oauth_version等参数并按 RFC 5849 的规则拼接签名基串后计算签名。支持的签名算法定义在 Enums.cs 中public enum OAuthSignatureMethod { HmacSha1, HmacSha256, PlainText, RsaSha1 }对应的测试见 OAuth1SignatureTests.cs 与 OAuth1AuthTests.cs。OAuth1Authenticator的公开属性见 OAuth1Authenticator.cs非常完备包括ConsumerKey、ConsumerSecret、Token、TokenSecret、Verifier、Version、CallbackUrl、SessionHandle、ClientUsername、ClientPassword、Realm、SignatureMethod、ParameterHandling等。日常使用只需调用静态工厂方法无需手动逐项赋值。获取 Request Token三步授权流程第一步获取临时 request token 是 OAuth1 三足授权流程的常规第一步使用ForRequestToken工厂方法只需consumerKey和consumerSecretvar options new RestClientOptions(https://api.twitter.com) { Authenticator OAuth1Authenticator.ForRequestToken(consumerKey, consumerSecret) }; var client new RestClient(options); var request new RestRequest(oauth/request_token);响应中应包含 token 与 token secret用于后续完成授权。如果需要指定回调地址可给认证器赋CallbackUrl属性var authenticator OAuth1Authenticator.ForRequestToken(consumerKey, consumerSecret); authenticator.CallbackUrl https://myapp.example.com/callback;实际上ForRequestToken还提供了一个直接接收回调地址的重载见 OAuth1Authenticator.cs。换取 Access Token三步授权流程第三步拿到 request token 后用ForAccessToken换取 access token需要传入consumerKey、consumerSecret、oauthToken与oauthTokenSecretvar authenticator OAuth1Authenticator.ForAccessToken( consumerKey, consumerSecret, oauthToken, oauthTokenSecret ); var options new RestClientOptions(https://api.twitter.com) { Authenticator authenticator }; var client new RestClient(options); var request new RestRequest(oauth/access_token);如果三步流程的第二步返回了 verifier用户授权后服务端下发的校验码使用带verifier参数的重载var authenticator OAuth1Authenticator.ForAccessToken( consumerKey, consumerSecret, oauthToken, oauthTokenSecret, verifier );ForAccessToken的可选signatureMethod参数同样默认是HmacSha1。响应中应包含可用于访问受保护资源的 access token。刷新 Access TokenRestSharp 提供两个接受sessionHandle的刷新重载ForAccessTokenRefresh见 OAuth1Authenticator.cs分别对应无 verifier与有 verifier两种情况// 不带 verifier 的刷新 var authenticator OAuth1Authenticator.ForAccessTokenRefresh( consumerKey, consumerSecret, oauthToken, oauthTokenSecret, sessionHandle ); // 带 verifier 的刷新 var authenticator OAuth1Authenticator.ForAccessTokenRefresh( consumerKey, consumerSecret, oauthToken, oauthTokenSecret, verifier, sessionHandle );访问受保护资源拿到 access token 后调用ForProtectedResource获取用于访问受保护资源的认证器var authenticator OAuth1Authenticator.ForAccessToken( consumerKey, consumerSecret, accessToken, accessTokenSecret ); var options new RestClientOptions(https://api.twitter.com/1.1) { Authenticator authenticator }; var client new RestClient(options); var request new RestRequest(statuses/update.json, Method.Post) .AddParameter(status, Hello Ladies Gentlemen, a signed OAuth request!) .AddParameter(include_entities, true);需要注意源码中AddOAuthData会明确拒绝在 base URL 中携带查询字符串的用法抛ApplicationException提示改用AddDefaultQueryParameter这是使用 OAuth1 时容易踩到的坑。xAuthxAuth 是 OAuth1 的简化变体直接把用户名密码以x_auth_username和x_auth_password请求参数发送从而直接换取 access token。该方式并未被广泛支持但 RestSharp 仍然保留了它。通过ForClientAuthentication创建var authenticator OAuth1Authenticator.ForClientAuthentication( consumerKey, consumerSecret, username, password );从 OAuthWorkflow.cs 可以看到xAuth 流程会额外生成x_auth_modeclient_auth参数且签名基于用户名密码与 consumer 密钥计算。0-legged OAuth0-legged零足OAuth 场景下access token 认证器可把consumerSecret传为null用于对访问令牌已预先签发、无需完整授权流程的情况var authenticator OAuth1Authenticator.ForAccessToken( consumerKey, null, oauthToken, oauthTokenSecret );OAuth1 的参数携带方式OAuth1Authenticator还暴露了ParameterHandling属性支持两种 OAuth 参数携带策略见 Enums.csHttpAuthorizationHeader默认把所有oauth_*参数拼进Authorization请求头UrlOrPostParameters把参数作为 URL 查询串或 POST 表单参数发送。默认工厂方法统一采用HttpAuthorizationHeader模式并配合Escaped的签名处理方式。OAuth2RestSharp 内置了两个非常简单的 OAuth2 认证器——它们只负责把已经获取到的 access token 附加到请求上本身不参与令牌的获取与刷新。以查询参数携带令牌OAuth2UriQueryParameterAuthenticator该认证器只接受 access token 一个构造参数会把令牌作为名为oauth_token的查询参数附加到请求 URL 上见 OAuth2UriQueryParameterAuthenticator.csvar authenticator new OAuth2UriQueryParameterAuthenticator(accessToken);其内部实现正是把令牌包装成GetOrPostParameter(oauth_token, accessToken)——这也是它与其它认证器产出HeaderParameter的关键区别。以请求头携带令牌OAuth2AuthorizationRequestHeaderAuthenticator该认证器提供两个构造重载单参数只传 access token此时默认令牌类型为OAuth双参数可额外指定令牌类型如Bearer。它会按{tokenType} {accessToken}的格式写入Authorization头见 OAuth2AuthorizationRequestHeaderAuthenticator.csvar authenticator new OAuth2AuthorizationRequestHeaderAuthenticator( token, Bearer ); var options new RestClientOptions(https://example.com) { Authenticator authenticator }; var client new RestClient(options);上述代码等同于后续 JWT 小节中JwtAuthenticator的效果——每个请求都会携带Authorization: Bearer token。由于这两个认证器都不负责获取令牌本身如果你需要自取令牌的完整 OAuth2 客户端可以参考仓库中的 示例 OAuth2 认证器位于 usage 示例文档它展示了如何请求 token endpoint 并把拿到的 bearer token 自动附加到后续请求。补充仓库中还有一个能力更强的 OAuth2TokenAuthenticator。它接受一个异步的FuncCancellationToken, TaskOAuth2Token令牌获取委托会在内部缓存令牌并在过期后自动重新获取通过SemaphoreSlim保证并发安全。它适用于非标准 OAuth2 流程或自定义令牌提供方相关设计文档见 docs/plans。JWTJwtAuthenticator是携带 JWT Bearer Token 的最简实现var authenticator new JwtAuthenticator(myToken); var options new RestClientOptions(https://example.com) { Authenticator authenticator }; var client new RestClient(options);每次请求时它都会添加值为Bearer your token的Authorization头。从 JwtAuthenticator.cs 源码可以看到两个值得注意的实现细节自动补前缀如果传入的 token 本身不以Bearer 开头构造器会自动补上该前缀如果已经带前缀则原样保留。同时会通过Ensure.NotEmptyString拒绝空字符串。运行期换令牌SetBearerToken方法允许在请求执行过程中动态更新令牌底层只是替换AuthenticatorBase.Token属性authenticator.SetBearerToken(newToken);自定义 Authenticator当内置认证器无法满足需求时可以直接实现IAuthenticator接口并注册到RestClientOptionsvar authenticator new SuperAuthenticator(); // implements IAuthenticator var options new RestClientOptions(https://example.com) { Authenticator authenticator }; var client new RestClient(options);Authenticate方法在调用RestClient.Execute或RestClient.ExecuteT时是最先被调用的逻辑之一。它接收当前正在执行的RestRequest因此你可以访问请求数据的每一个部分headers、parameters、body 等对请求做任意形式的改写。两种推荐的实现路径直接实现IAuthenticator适合完全不依赖令牌缓存的场景接口只有一个ValueTask Authenticate(...)方法签名见 IAuthenticator.cs。继承AuthenticatorBase适合需要懒加载令牌并缓存复用的场景只需实现抽象方法GetAuthenticationParameter。仓库的 usage 示例文档 给出了一个真实可运行的参考TwitterAuthenticator继承AuthenticatorBase首次调用时发现Token为空于是内部用HttpBasicAuthenticator请求oauth2/token端点换取 bearer token随后复用该 token 直到需要刷新。其核心代码模式为public class TwitterAuthenticator : AuthenticatorBase { protected override async ValueTaskParameter GetAuthenticationParameter(string accessToken) { Token string.IsNullOrEmpty(Token) ? await GetToken() : Token; return new HeaderParameter(KnownHeaders.Authorization, Token); } }注意该示例文档同时提示示例代码为生产级代码当令牌尚未获取时若多个请求并发执行可能产生重复获取令牌的副作用实际生产环境可通过信号量semaphore等方式规避。小结RestSharp 的认证体系可以用一张表概括场景推荐认证器附加位置HTTP Basic 用户名密码HttpBasicAuthenticatorAuthorization: Basic ...头OAuth1 三步授权/受保护资源OAuth1Authenticator.ForRequestToken/ForAccessToken/ForProtectedResourceAuthorization头默认OAuth1 简化/xAuthOAuth1Authenticator.ForClientAuthenticationAuthorization头 x_auth_*参数OAuth2 令牌走查询参数OAuth2UriQueryParameterAuthenticatoroauth_token查询参数OAuth2 令牌走请求头OAuth2AuthorizationRequestHeaderAuthenticatorAuthorization: {tokenType} {token}头JWT BearerJwtAuthenticator可用SetBearerToken刷新Authorization: Bearer token头完全自定义实现IAuthenticator或继承AuthenticatorBase任意位置选择建议单客户端统一认证时挂载到RestClientOptions混合认证时挂载到单个RestRequest需要令牌自动获取与缓存的复杂 OAuth2 场景优先考虑继承AuthenticatorBase的懒加载模式。仓库中对应的测试Auth 测试目录与 OAuth2 认证器测试 是验证各类认证器行为最直接的参考。赞分享后端API设计【免费下载链接】RestSharpSimple REST and HTTP API Client for .NET项目地址https://gitcode.com/gh_mirrors/re/RestSharp点击查看免费下载相关推荐RestSharp 认证机制完全指南Basic、OAuth1、OAuth2、JWT 与自定义 AuthenticatorRestSharp 认证机制完全指南Basic、OAuth1、OAuth2、JWT 与自定义 Authenticator RestSharp 是面向 .NET后端API设计RestSharp 认证机制全解Basic、OAuth1、OAuth2 与 JWT 认证器实战指南RestSharp 认证机制全解Basic、OAuth1、OAuth2 与 JWT 认证器实战指南 本文以 RestSharp v113 文档中的认证器指南为后端API设计RestSharp 认证体系完全指南从 Basic、OAuth1 到 OAuth2 与 JWT 的认证器详解RestSharp 认证体系完全指南从 Basic、OAuth1 到 OAuth2 与 JWT 的认证器详解 本指南以 RestSharp v114 版本化文后端API设计上一篇PDF限制怎么解除PDF补丁丁去复制、打印限制的完整操作指南下一篇Ultimate SD UpscaleAI图像分块放大技术深度解析与实践指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考