如何解决Flutter Web中用openid_client实现Keycloak授权码流程的问题？

一、基于openid_client的正确实现 #

1. 核心参数说明 #

• Redirect URI：必须与Keycloak后台配置的Valid Redirect URIs完全一致（即http://localhost:54841/），Flutter Web中该URI对应应用根地址，无需额外路径。
• State参数：openid_client会自动生成、存储并校验，无需手动处理，用于防止CSRF攻击。
• Code Verifier/Challenge：public类型客户端强制要求PKCE，openid_client默认自动生成并处理相关参数，无需手动编写逻辑。

2. 完整代码示例 #

import 'dart:html' as html;
import 'package:openid_client/openid_client.dart';
import 'package:openid_client/openid_client_io.dart';

Future<void> initKeycloakAuth() async {
  // 替换为你的Keycloak配置
  const issuerUrl = 'http://你的Keycloak地址/auth/realms/你的Realm名称';
  const clientId = '你的客户端ID';
  const redirectUri = 'http://localhost:54841/';

  // 初始化Issuer与客户端
  final issuer = await Issuer.discover(Uri.parse(issuerUrl));
  final client = Client(issuer, clientId);

  // 检查当前URL是否为授权回调
  final currentUri = Uri.parse(html.window.location.href);
  if (currentUri.queryParameters.containsKey('code')) {
    // 交换授权码获取Token
    final credential = await client.createCredential(
      authorizationCode: currentUri.queryParameters['code']!,
      redirectUri: Uri.parse(redirectUri),
    );
    // 存储Token（可使用shared_preferences_web）
    print('获取到AccessToken: ${credential.accessToken}');
    // 清除URL中的回调参数，避免重复处理
    html.window.history.replaceState(null, '', redirectUri);
  } else {
    // 发起授权请求
    final authRequest = client.authorizationCodeFlow(
      redirectUri: Uri.parse(redirectUri),
      scopes: ['openid', 'profile', 'email'],
    );
    // 存储PKCE验证所需的code verifier
    await authRequest.pkce!.storeVerifier();
    // 跳转至Keycloak登录页
    html.window.location.href = authRequest.authenticationUri.toString();
  }
}

3. 循环跳转问题排查与解决 #

循环跳转通常由以下原因导致，逐一排查：

• 回调URI不匹配：确保Keycloak后台Valid Redirect URIs与代码中redirectUri完全一致，包括协议、端口、路径，无多余斜杠或大小写差异。
• PKCE验证失败：public客户端必须启用PKCE，禁止手动关闭openid_client的PKCE逻辑，否则Keycloak会拒绝授权触发重试。
• State参数校验失败：不要手动篡改或清除框架自动存储的state参数，否则会导致校验失败重新发起登录请求。
• Keycloak配置错误：确认Access Type为public、Standard Flow Enabled为ON，未开启冲突的Implicit Flow。

二、备选方案：flutter_appauth的Web适配 #

flutter_appauth已支持Flutter Web，可作为替代方案：

1. Web端配置 #

在web/index.html中添加：

<script>
  window.flutterAppAuth = {
    redirectUri: 'http://localhost:54841/',
    clientId: '你的客户端ID'
  };
</script>

2. 代码实现 #

import 'package:flutter_appauth/flutter_appauth.dart';

Future<void> initAppAuth() async {
  const issuer = 'http://你的Keycloak地址/auth/realms/你的Realm名称';
  const clientId = '你的客户端ID';
  const redirectUri = 'http://localhost:54841/';

  final appAuth = FlutterAppAuth();
  final authResult = await appAuth.authorizeAndExchangeCode(
    AuthorizationTokenRequest(
      clientId,
      redirectUri,
      issuer: issuer,
      scopes: ['openid', 'profile', 'email'],
      usePkce: true, // public客户端必须开启
    ),
  );

  if (authResult != null) {
    print('获取到AccessToken: ${authResult.accessToken}');
  }
}

三、Keycloak后台配置确认 #

最后再次核对Keycloak客户端配置：

• Access Type设置为public
• Standard Flow Enabled勾选ON
• Valid Redirect URIs精确配置为http://localhost:54841/（开发环境可临时用http://localhost:*，生产环境需严格限制）
• Web Origins设置为http://localhost:54841/或*，避免CORS问题

内容的提问来源于stack exchange，提问作者Reda Antar