Flutter OAuth2客户端认证插件ac_oauth2_client的使用

Flutter OAuth2客户端认证插件ac_oauth2_client的使用

一个不带任何假设的符合RFC标准的OAuth 2.0客户端。

特性

它实现了以下功能：

• 授权码授权（RFC-6749 §4.1）；
• 隐式授权（RFC-6749 §4.2）；
• 资源所有者密码凭据授权（RFC-6749 §4.3）；
• 客户端凭证授权（RFC-6749 §4.4）；
• 扩展授权（RFC-6749 §4.5）；
• 访问令牌刷新（RFC-6749 §6）；
• 令牌撤销（RFC-7009）；

它不会实现以下功能：

• 实际的HTTP请求到服务器，尽管它提供了数据以进行请求并转换响应。
• 一种呈现网页给用户并检索重定向URI的方法。你可以使用WebView（仅用于开发/调试目的）或启动外部浏览器来呈现网页，并使用深度链接检索重定向URI。

使用

使用描述假定你对OAuth 2.0认证流程和涉及的数据有所了解。

HTTP请求处理器

典型的实现方式如下，使用http包：

import 'package:http/http.dart' as http;

class MyHttpRequestHandler 
    implements OAuth2HttpRequestHandler {
  Future<OAuth2HttpResponse> post(
    Uri url,
    Map<String, String> headers,
    Map<String, String> formData,
  ) async {
    final response = await http.post(
        url, 
        headers: headers, 
        body: Uri(queryParameters: formData).query,
    );

    return OAuth2HttpResponse(
        status: response.statusCode,
        formData: Uri.splitQueryString(response.body),
    );
  }
}

或者如果你使用ac_fetch包：

class MyHttpRequestHandler 
    implements OAuth2HttpRequestHandler {
  Future<OAuth2HttpResponse> post(
    Uri url,
    Map<String, String> headers,
    Map<String, String> formData,
  ) {
    final options = FetchOptions(
        method: 'POST',
        url: url,
        headers: headers,
    );

    final response = await fetchWithStructuredData(options, formData);

    return OAuth2HttpResponse(
        status: response.status,
        formData: response.ok
            ? await response.waitStructuredData()
            : null,
    );
  }
}

授权码授权

生成授权URL

final authorizationEndpoint = 
    Uri.parse('https://www.example.com/oauth/authorize');

final clientCredentialsIdentifier = 
    OAuth2ClientCredentialsIdentifier(
        identifier: '<client_id>',
        authentication: OAuth2ClientAuthenticationSecret(
            secret: '<client_secret>',
        ),
    );

// 可选地定义一个随机状态。
final state = OAuth2State.random();

// 可选地，对于允许多个重定向URI的服务提供商，
// 你可以传递重定向URI。对于只允许一个重定向URI的服务提供商，
// 他们可能会使此参数成为必需。
final redirectUri = Uri.parse('my-app://deeplink');

// 可选地传递所需的OAuth 2.0作用域
final scopes = ['read', 'write'];

// 可选地传递自定义参数
final customParameters = <String, String>{
    'my-provider-custom-parameter': 'value',
}

final url = OAuth2Client.composeAuthorizationCodeGrantUrl(
    authorizationEndpoint: authorizationEndpoint,
    clientCredentialsIdentifier: clientCredentialsIdentifier,
    state: state,
    redirectUri: redirectUri,
    scopes: scopes,
    customParameters: customParameters,
);

// ... 呈现URL给用户

解析重定向URI

// 从授权获取回来的重定向URI
Uri redirectionUri;

// 你在composeAuthorizationCodeGrantUrl时传递的状态
OAuth2State? state;

final result =  OAuth2Client.parseAuthorizationCodeGrantRedirectionUri(
    redirectionUri: redirectionUri,
    state: state,
);

// 授权码，只有几分钟的有效期，可用于创建令牌。
print(result.code);

通过授权码获取令牌

final tokenEndpoint = 
    Uri.parse('https://www.example.com/oauth/token');

// 你在composeAuthorizationCodeGrantUrl时使用的重定向URI。
Uri? originalRedirectUri;

// 可选地传递一些自定义参数
Map<String, String>? customParameters;

final result = await OAuth2Client.authorizationCodeTokenGrant(
    requestHandler: MyHttpRequestHandler(),
    tokenEndpoint: tokenEndpoint,
    clientCredentials: clientCredentialsIdentifier,
    authorizationCode: authorizationResult.code,
    originalRedirectUri: originalRedirectUri,
    customParameters: customParameters,
);

print(result.accessToken);
print(result.expiresIn);
print(result.refreshToken); 
// ...

刷新访问令牌

final tokenEndpoint = 
    Uri.parse('https://www.example.com/oauth/token');

final clientCredentials = 
    OAuth2ClientCredentialsIdentifier(
        identifier: '<client_id>',
        authentication: OAuth2ClientAuthenticationSecret(
            secret: '<client_secret>',
        ),
    );

// 从OAuth2TokenGrantResult.refreshToken中可能获取到的刷新令牌
final refreshToken = '<refresh_token>';

// 可选地传递所需的OAuth 2.0作用域
OAuth2Scopes? scopes = ['read'];

// 可选地传递一些自定义参数
Map<String, String>? customParameters;

final result = await OAuth2Client.refreshToken(
    requestHandler: MyHttpRequestHandler(),
    tokenEndpoint: tokenEndpoint,
    clientCredentials: clientCredentials,
    refreshToken: refreshToken,
    scopes: scopes,
    customParameters: customParameters,
);

// 新的访问令牌
print(result.accessToken);

撤销令牌

final revocationEndpoint = 
    Uri.parse('https://www.example.com/oauth/revoke');

final token = '<access_or_refresh_token>';

// 可选地，给服务器一个提示，指明你要撤销哪个令牌
OAuth2TokenType? tokenTypeHint;

// 可选地传递一些自定义参数
Map<String, String>? customParameters;

await OAuth2Client.revokeToken(
    requestHandler: MyHttpRequestHandler(),
    revocationEndpoint: revocationEndpoint,
    clientCredentials: clientCredentials,
    token: token,
    tokenTypeHint: tokenTypeHint,
    customParameters: customParameters,
);