Logto 是一个为现代应用和 SaaS 产品设计的 Auth0 替代方案。它提供 Cloud 和 开源 服务，帮助你快速启动身份和管理 (IAM) 系统。享受认证 (Authentication)、授权 (Authorization) 和多租户管理 一体化。
我们建议从 Logto Cloud 上的免费开发租户开始。这可以让你轻松探索所有功能。
在本文中，我们将介绍使用 Flutter 和 Logto 快速构建 Facebook 登录体验（用户认证 (Authentication)）的步骤。
先决条件
在 Logto 中创建一个应用程序
Logto 基于 OpenID Connect (OIDC) 认证 (Authentication) 和 OAuth 2.0 授权 (Authorization)。它支持跨多个应用程序的联合身份管理，通常称为单点登录 (SSO)。
要创建你的 Native app 应用程序，只需按照以下步骤操作：
- 打开 Logto Console。在“开始使用”部分，点击“查看全部”链接以打开应用程序框架列表。或者，你可以导航到 Logto Console > Applications，然后点击“创建应用程序”按钮。
- 在打开的模态窗口中，点击“Native app”部分，或使用左侧的快速过滤复选框过滤所有可用的“Native app”框架。点击 "Flutter" 框架卡片以开始创建你的应用程序。
- 输入应用程序名称，例如“Bookstore”，然后点击“创建应用程序”。
🎉 太棒了！你刚刚在 Logto 中创建了你的第一个应用程序。你将看到一个祝贺页面，其中包含详细的集成指南。按照指南查看你的应用程序中的体验将会是什么样的。
集成 Flutter SDK
- SDK 包可以在 pub.dev 和 Logto GitHub 仓库 上获取。
- 示例项目是使用 Flutter material 构建的。你可以在 pub.dev 和我们的 GitHub 仓库 上找到它。
- SDK 仅兼容 Android 和 iOS 平台。
- SDK v1.x 兼容 Dart 2.x。对于 SDK v2.x，你需要将 Dart 版本更新到 3.x 或更高。
安装
- pub.dev
- GitHub
你可以使用 pub 包管理器直接安装 logto_dart_sdk package。在你的项目根目录下运行以下命令：
flutter pub get logto_dart_sdk
如果你更喜欢 fork 自己版本的 SDK，你可以直接从 GitHub 克隆仓库。
git clone https://github.com/logto-io/dart
模块
logto_dart_sdk 包含两个主要模块：
-
logto_core.dart 这个核心模块提供了 Logto SDK 的基本功能和接口。
-
logto_client.dart 这个客户端模块提供了一个高级的 Logto 客户端类，用于与 Logto 服务器交互。
依赖和配置
依赖和配置
此 SDK 具有以下依赖项，其中一些需要额外配置：
flutter_secure_storage
我们使用 flutter_secure_storage 来实现跨平台的持久安全令牌存储。
- iOS 使用 Keychain
- Android 使用 AES 加密。
配置 Android 版本
在项目的 android/app/build.gradle 文件中将 android:minSdkVersion 设置为 18。
android {
...
defaultConfig {
...
minSdkVersion 18
...
}
}
禁用自动备份
默认情况下，Android 可能会自动在 Google Drive 上备份数据。这可能导致异常 java.security.InvalidKeyException:Failed to unwrap key。
为避免这种情况，你可以禁用应用的自动备份或从 FlutterSecureStorage 中排除 sharedprefs。
-
要禁用自动备份，请转到应用的清单文件，并将
android:allowBackup和android:fullBackupContent属性设置为false。AndroidManifest.xml<manifest ... >
...
<application
android:allowBackup="false"
android:fullBackupContent="false"
...
>
...
</application>
</manifest> -
从
FlutterSecureStorage中排除sharedprefs。如果你需要保留应用的
android:fullBackupContent而不是禁用它，可以从备份中排除sharedprefs目录。 请参阅 Android 文档 了解更多详情。在 AndroidManifest.xml 文件中，将 android:fullBackupContent 属性添加到
<application>元素，如以下示例所示。此属性指向一个包含备份规则的 XML 文件。AndroidManifest.xml<application ...
android:fullBackupContent="@xml/backup_rules">
</application>在
res/xml/目录中创建一个名为@xml/backup_rules的 XML 文件。在此文件中，使用<include>和<exclude>元素添加规则。以下示例备份所有共享首选项，除了 device.xml：@xml/backup_rules<?xml version="1.0" encoding="utf-8"?>
<full-backup-content>
<exclude domain="sharedpref" path="FlutterSecureStorage"/>
</full-backup-content>
请查看 flutter_secure_storage 了解更多详情。
flutter_web_auth
flutter_web_auth 在 Logto 的 flutter SDK 背后使用。我们依赖其基于 webview 的交互界面来认证用户。
此插件在 iOS 12+ 和 macOS 10.15+ 上使用 ASWebAuthenticationSession，在 iOS 11 上使用 SFAuthenticationSession，在 Android 上使用 Chrome Custom Tabs，并在 Web 上打开一个新窗口。
在 Android 上注册回调 url
为了捕获 Logto 登录网页的回调 url，你需要将登录的 redirectUri 注册到 AndroidManifest.xml 文件中。
<activity android:name="com.linusu.flutter_web_auth.CallbackActivity" android:exported="true">
<intent-filter android:label="flutter_web_auth">
<action android:name="android.intent.action.VIEW"/>
<category android:name="android.intent.category.DEFAULT"/>
<category android:name="android.intent.category.BROWSABLE"/>
<data android:scheme="io.logto"/>
</intent-filter>
</activity>
http.dart
由于 SDK 需要进行网络请求，你需要向 SDK 传入一个 HTTP 客户端。你可以使用来自 http.dart 的默认 http.Client，或者创建一个具有自定义配置的 http.Client。
import 'package:http/http.dart' as http;
集成
初始化 LogtoClient
导入 logto_dart_sdk 包，并在应用程序的根部初始化 LogtoClient 实例。
import 'package:logto_dart_sdk/logto_dart_sdk.dart';
import 'package:http/http.dart' as http;
void main() async {
WidgetsFlutterBinding.ensureInitialized();
runApp(const MyApp());
}
class MyApp extends StatelessWidget {
const MyApp({Key? key}) : super(key: key);
Widget build(BuildContext context) {
return const MaterialApp(
title: 'Flutter Demo',
home: MyHomePage(title: 'Logto Demo Home Page'),
);
}
}
class MyHomePage extends StatefulWidget {
const MyHomePage({Key? key, required this.title}) : super(key: key);
final String title;
State<MyHomePage> createState() => _MyHomePageState();
}
class _MyHomePageState extends State<MyHomePage> {
late LogtoClient logtoClient;
void render() {
// 状态变化
}
// LogtoConfig
final logtoConfig = const LogtoConfig(
endpoint: "<your-logto-endpoint>",
appId: "<your-app-id>"
);
void _init() {
logtoClient = LogtoClient(
config: logtoConfig,
httpClient: http.Client(), // 可选的 http 客户端
);
render();
}
void initState() {
super.initState();
_init();
}
// ...
}
实现登录
在我们深入细节之前，这里是终端用户体验的快速概述。登录过程可以简化如下：
- 你的应用调用登录方法。
- 用户被重定向到 Logto 登录页面。对于原生应用，将打开系统浏览器。
- 用户登录并被重定向回你的应用（配置为重定向 URI）。
关于基于重定向的登录
- 此认证 (Authentication) 过程遵循 OpenID Connect (OIDC) 协议，Logto 强制执行严格的安全措施以保护用户登录。
- 如果你有多个应用程序，可以使用相同的身份提供商 (IdP)（日志 (Logto)）。一旦用户登录到一个应用程序，当用户访问另一个应用程序时，Logto 将自动完成登录过程。
要了解有关基于重定向的登录的原理和好处的更多信息，请参阅 Logto 登录体验解释。
在开始之前，你需要在管理控制台中为你的应用程序添加一个重定向 URI。
让我们切换到 Logto Console 的应用详情页面。添加一个重定向 URI io.logto://callback 并点击“保存更改”。
- 对于 iOS，重定向 URI 方案并不重要，因为
ASWebAuthenticationSession类会监听重定向 URI，无论它是否已注册。 - 对于 Android，重定向 URI 方案必须在
AndroidManifest.xml文件中注册。
配置重定向 URI 后，我们在页面上添加一个登录按钮，该按钮将调用 logtoClient.signIn API 来启动 Logto 登录流程：
class _MyHomePageState extends State<MyHomePage> {
// ...
final redirectUri = 'io.logto://callback';
Widget build(BuildContext context) {
// ...
Widget signInButton = TextButton(
onPressed: () async {
await logtoClient.signIn(redirectUri);
render();
},
child: const Text('Sign In'),
);
return Scaffold(
appBar: AppBar(
title: Text(widget.title),
),
body: Center(
child: Column(
mainAxisAlignment: MainAxisAlignment.center,
children: <Widget>[
SelectableText('My Demo App'),
signInButton,
],
),
),
);
}
}
实现登出
现在让我们在主页上添加一个登出按钮，以便用户可以从你的应用程序中登出。
class _MyHomePageState extends State<MyHomePage> {
// ...
Widget build(BuildContext context) {
// ...
Widget signOutButton = TextButton(
onPressed: () async {
await logtoClient.signOut();
render();
},
child: const Text('Sign Out'),
);
return Scaffold(
appBar: AppBar(
title: Text(widget.title),
),
body: Center(
child: Column(
mainAxisAlignment: MainAxisAlignment.center,
children: <Widget>[
SelectableText('My Demo App'),
signInButton,
signOutButton,
],
),
),
);
}
}
处理认证状态
Logto SDK 提供了一个异步方法来检查认证状态。该方法是 logtoClient.isAuthenticated。如果用户已认证，该方法返回布尔值 true，否则返回 false。
在示例中，我们根据认证状态有条件地渲染登录和登出按钮。现在让我们更新 Widget 中的 render 方法来处理状态变化：
class _MyHomePageState extends State<MyHomePage> {
// ...
bool? isAuthenticated = false;
void render() {
setState(() async {
isAuthenticated = await logtoClient.isAuthenticated;
});
}
Widget build(BuildContext context) {
// ...
return Scaffold(
appBar: AppBar(
title: Text(widget.title),
),
body: Center(
child: Column(
mainAxisAlignment: MainAxisAlignment.center,
children: <Widget>[
SelectableText('My Demo App'),
isAuthenticated == true ? signOutButton : signInButton,
],
),
),
);
}
}
检查点：测试你的应用程序
现在，你可以测试你的应用程序：
- 运行你的应用程序，你将看到登录按钮。
- 点击登录按钮，SDK 将初始化登录过程并将你重定向到 Logto 登录页面。
- 登录后，你将被重定向回你的应用程序，并看到登出按钮。
- 点击登出按钮以清除令牌存储并登出。
添加 Facebook 连接器
要实现快速登录并提高用户转化率，请将 Flutter 作为身份提供商 (IdP) 进行连接。Logto 社交连接器可以帮助你在几分钟内通过允许输入多个参数来建立此连接。
要添加社交连接器，只需按照以下步骤操作：
- 导航到 Console > Connectors > Social Connectors。
- 点击“添加社交连接器”并选择“Facebook”。
- 按照 README 指南完成必填字段并自定义设置。
如果你正在按照现场连接器指南进行操作，可以跳过下一部分。
设置 Facebook 登录
注册 Facebook 开发者账户
如果你还没有，请注册为 Facebook 开发者
设置 Facebook 应用
- 访问 Apps 页面。
- 点击你现有的应用或创建一个新应用（如果需要）。
- 选择的应用类型由你决定，但它应该包含 Facebook 登录 产品。
- 在应用仪表板页面，滚动到“添加产品”部分，并点击“Facebook 登录”卡片上的“设置”按钮。
- 跳过 Facebook 登录快速入门页面，点击侧边栏 -> “产品” -> “Facebook 登录” -> “设置”。
- 在 Facebook 登录设置页面，在“有效的 OAuth 重定向 URI”字段中填写
${your_logto_origin}/callback/${connector_id}。connector_id可以在 Logto 管理控制台连接器详情页面的顶部栏找到。例如：https://logto.dev/callback/${connector_id}用于生产环境https://localhost:3001/callback/${connector_id}用于本地环境测试
- 点击右下角的“保存更改”按钮。
组合连接器 JSON
- 在 Facebook 应用仪表板页面，点击侧边栏 -> “设置” -> “基本”。
- 你将在面板上看到“App ID”和“App secret”。
- 点击 App secret 输入框后的“显示”按钮以复制其内容。
- 填写 Logto 连接器设置：
- 在
clientId字段中填写来自 App ID 的字符串。 - 在
clientSecret字段中填写来自 App secret 的字符串。 - 在
scope字段中填写以逗号或空格分隔的权限列表字符串。如果你没有指定权限，默认权限是email,public_profile。
- 在
使用 Facebook 的测试用户测试登录
你可以使用测试、开发者和管理员用户的账户，在开发和实时应用模式下测试相关应用的登录。
你也可以直接将应用上线，以便任何 Facebook 用户都可以使用该应用登录。
- 在应用仪表板页面，点击侧边栏 -> “角色” -> “测试用户”。
- 点击“创建测试用户”按钮以创建一个测试用户。
- 点击现有测试用户的“选项”按钮，你将看到更多操作，例如“更改姓名和密码”。
发布 Facebook 登录设置
通常，只有测试、管理员和开发者用户可以在开发模式下使用相关应用登录。
为了让普通 Facebook 用户在生产环境中使用该应用登录，你可能需要将你的 Facebook 应用切换到*实时模式，这取决于应用类型。例如，纯商业类型*应用没有“实时”切换按钮，但这不会阻碍你的使用。
- 在 Facebook 应用仪表板页面，点击侧边栏 -> “设置” -> “基本”。
- 如果需要，在面板上填写“隐私政策 URL”和“用户数据删除”字段。
- 点击右下角的“保存更改”按钮。
- 点击应用顶部栏的“实时”切换按钮。
配置类型
| 名称 | 类型 |
|---|---|
| clientId | string |
| clientSecret | string |
| scope | string |
保存你的配置
仔细检查你是否在 Logto 连接器配置区域填写了必要的值。点击“保存并完成”（或“保存更改”），Facebook 连接器现在应该可用了。
在登录体验中启用 Facebook 连接器
一旦你成功创建了一个社交连接器，你可以在登录体验中将其启用为“继续使用 Facebook”按钮。
- 导航到 Console > 登录体验 > 注册和登录。
- （可选）如果只需要社交登录，选择“无”作为注册标识符。
- 将配置好的 Facebook 连接器添加到“社交登录”部分。
测试和验证
返回到你的 Flutter 应用。你现在应该可以使用 Facebook 登录了。享受吧！
拓展阅读
终端用户流程：Logto 提供开箱即用的认证 (Authentication) 流程，包括多因素认证 (MFA) 和企业单点登录 (SSO)，以及强大的 API，用于灵活实现账户设置、安全验证和多租户体验。
授权 (Authorization)：授权 (Authorization) 定义了用户在被认证 (Authentication) 后可以执行的操作或访问的资源。探索如何保护你的 API 以用于原生和单页应用程序，并实现基于角色的访问控制 (RBAC)。
组织 (Organizations)：在多租户 SaaS 和 B2B 应用中特别有效，组织功能支持租户创建、成员管理、组织级 RBAC 和即时供应。
客户 IAM 系列：我们关于客户（或消费者）身份和访问管理的系列博客文章，从 101 到高级主题及更深入的内容。