Flutter Keycloak认证管理插件keycloak_wrapper的使用

Keycloak Wrapper

通过这个插件，可以无缝地将 Keycloak Single Sign-On (SSO) 认证集成到您的Flutter应用程序中。该插件自动管理令牌，并提供一个用户认证状态流，使应用程序能够监听以保持与认证状态的变化同步。

Getting Started

关键点

• 该插件集成了 AppAuth SDK 来建立使用 OAuth 2.0 和 OpenID Connect (OIDC) 的连接。
• 使用 flutter_secure_storage 包来安全地存储所有令牌。

注意事项

• AndroidX 是必需的。
• 从 Android API 28 和 iOS 9 开始，默认禁用不安全的 HTTP 连接。如果需要允许明文连接，请参阅相关指南，但建议尽可能使用安全连接。

Keycloak 配置

前往您的 Keycloak Administration Console 并选择您的 Client ID，在访问设置部分插入 <bundle_identifier>:/ 作为有效的重定向 URI 和登出重定向 URI。

Android 配置

在 build.gradle 文件中指定自定义方案：

android {
    ...
    defaultConfig {
        ...
        manifestPlaceholders += [
                'appAuthRedirectScheme': '<package_name>'
        ]
    }
}

确保 <package_name> 全为小写，且不要包含任何不允许出现在主机名中的字符。

iOS/macOS 配置

在 Info.plist 中指定自定义方案：

<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleTypeRole</key>
        <string>Editor</string>
        <key>CFBundleURLSchemes</key>
        <array>
            <string><bundle_identifier></string>
        </array>
    </dict>
</array>

Usage 示例代码

以下是一个完整的示例，展示了如何使用 keycloak_wrapper 插件：

import 'package:flutter/material.dart';
import 'package:keycloak_wrapper/keycloak_wrapper.dart';

final keycloakConfig = KeycloakConfig(
  bundleIdentifier: 'com.example.demo',
  clientId: '<client_id>',
  frontendUrl: '<frontend_url>',
  realm: '<realm>',
);
final keycloakWrapper = KeycloakWrapper(config: keycloakConfig);
final scaffoldMessengerKey = GlobalKey<ScaffoldMessengerState>();

void main() {
  WidgetsFlutterBinding.ensureInitialized();
  // 初始化插件
  keycloakWrapper.initialize();
  // 监听插件捕获的错误
  keycloakWrapper.onError = (message, _, __) {
    // 在snackbar中显示错误信息
    scaffoldMessengerKey.currentState
      ?..hideCurrentSnackBar()
      ..showSnackBar(SnackBar(content: Text(message)));
  };
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) => MaterialApp(
        scaffoldMessengerKey: scaffoldMessengerKey,
        // 监听用户认证状态流
        home: StreamBuilder<bool>(
          initialData: false,
          stream: keycloakWrapper.authenticationStream,
          builder: (context, snapshot) {
            if (snapshot.connectionState == ConnectionState.waiting) {
              return const LoadingScreen();
            } else if (snapshot.data!) {
              return const HomeScreen();
            } else {
              return const LoginScreen();
            }
          },
        ),
      );
}

class LoadingScreen extends StatelessWidget {
  const LoadingScreen({super.key});

  @override
  Widget build(BuildContext context) => const Scaffold(
        body: Center(
          child: CircularProgressIndicator.adaptive(),
        ),
      );
}

class LoginScreen extends StatelessWidget {
  const LoginScreen({super.key});

  // 登录
  Future<void> login() async {
    final isLoggedIn = await keycloakWrapper.login();

    if (isLoggedIn) debugPrint('User has successfully logged in.');
  }

  @override
  Widget build(BuildContext context) => Scaffold(
        body: Center(
          child: FilledButton(onPressed: login, child: const Text('Login')),
        ),
      );
}

class HomeScreen extends StatelessWidget {
  const HomeScreen({super.key});

  // 登出
  Future<void> logout() async {
    final isLoggedOut = await keycloakWrapper.logout();

    if (isLoggedOut) debugPrint('User has successfully logged out.');
  }

  @override
  Widget build(BuildContext context) => Scaffold(
        body: Center(
          child: Column(
            mainAxisSize: MainAxisSize.min,
            children: [
              FutureBuilder(
                future: keycloakWrapper.getUserInfo(),
                builder: (context, snapshot) {
                  final userInfo = snapshot.data ?? {};

                  return Column(children: [
                    ...userInfo.entries.map((entry) => Text('${entry.key}: ${entry.value}')),
                    if (userInfo.isNotEmpty) const SizedBox(height: 20),
                  ]);
                },
              ),
              FilledButton(onPressed: logout, child: const Text('Logout')),
            ],
          ),
        ),
      );
}

此示例展示了如何配置和使用 keycloak_wrapper 插件进行登录、获取用户信息、以及登出操作。请根据您的实际需求替换配置项中的占位符（如 <client_id>、<frontend_url> 等）。