推荐使用：适用于Keycloak的Apple身份提供者 :apple:

推荐使用：适用于Keycloak的Apple身份提供者 :apple:

这个开源项目是一个为Keycloak设计的扩展插件，它实现了使用Apple登录，以支持网页应用和原生应用（通过令牌交换）的集成。

Apple的独特之处

由于Apple不完全遵循现有的OpenID Connect标准，该项目针对以下差异进行了定制：

• 如果请求了范围，Apple会将TokenResponse作为POST请求发送。
• 没有userinfo端点，用户的email、firstName和lastName只在首次使用Apple登录时传输。
• /token请求必须包含一个客户端秘密（JWT），该JWT使用特定的私钥（.p8文件）签名。

安装

1. 获取最新JAR包或将其作为Maven依赖项添加到项目中：
2. 将JAR文件部署到Keycloak（将其放置在docker容器的/opt/keycloak/providers目录下；或参考此指南）
3. 可能需要重启Keycloak（或当使用docker时，使用新的容器）

查看示例Dockerfile了解更多信息。

兼容性

因为本项目实现的是Keycloak内部SPI，所以新版本的Keycloak可能会导致扩展不兼容。以下是兼容性列表：

| Keycloak 版本 | 扩展版本 | |---------------------------------------|---------------------------| | < 17.0.0 | 风险自负。 | | 17.0.0 <= 19.0.3 | 1.2.0 | | 20.0.0 <= 20.0.5 :information_source: | 1.3.0 <= 1.4.1 | | 21.0.0 <= 21.0.2 :information_source: | 1.5.0 | | 21.1.0 <= 21.1.2 :information_source: | 1.6.0 | | 22.0.0 < 23.0.0 | 1.7.0 <= 1.8.0 | | >= 23.0.0 | >= 1.9.0 |

:information_source: 在Keycloak v21.X.Y中，扩展无法有效使用，因为额外的配置选项如Team ID和Key ID不会显示在管理界面中。但您仍然可以使用此扩展与Keycloak v21.X.Y一起，如果您使用外部配置工具，如terraform或keycloak-config-cli，而不依赖Keycloak的UI。

:information_source: 对于Keycloak v19和v20，您需要切换回旧的管理界面才能使用此扩展。（参见这个关于Keycloak 19.0.0发布的说明：Keycloak 19.0.0发布）

配置

登录到Keycloak管理控制台，添加“Apple”作为新的身份提供者，并自定义配置选项：

| 选项 | 描述 | |------------------------|----------------------------------------------------------------------------------| | 客户端ID（=服务ID） | 从您的Apple开发者帐户获取的服务ID。 | | 客户端秘密 | （忽略）只需使用一个占位符值。 | | 团队ID | 从您的Apple开发者帐户获取的团队ID。 | | 密钥ID | 来自您的Apple开发者帐户的密钥标识符。 | | p8密钥 | 从您的Apple开发者帐户获取的p8密钥文件的原始内容。 | | 默认范围 | 从Apple请求的范围（用于Web登录）。默认为name%20email |

:raising_hand: 如果您不确定如何从Apple开发者帐户获得这些值，请参考这篇指南。

:warning: 确保将Keycloak的代理URL（https://<keycloak-url>/realms/<realm>/broker/apple/endpoint）添加到Apple开发者帐户的有效重定向URL中。

令牌交换

:point_right: 不确定是否需要令牌交换？请查阅此wiki。

令牌交换可用于将Apple令牌交换为Keycloak访问令牌和刷新令牌。这主要对iOS等原生应用程序有价值，以便提供本地登录选项。

1. 使用Apple ID-Token（推荐）

您可以使用Keycloak领域中的/token端点，以Apple ID-Token交换Keycloak令牌。 <keycloak server url>/realms/<realm>/protocol/openid-connect/token application/x-www-form-urlencoded

| 参数 | 描述 | |------------------|-----------------------------------------------------------------------------------------------------------------------------------------| | client_id | Keycloak客户端的客户端ID | | grant_type | urn:ietf:params:oauth:grant-type:token-exchange | | subject_token | Apple的ID-Token | | subject_issuer | apple（Keycloak中的社交提供商名称） | | subject_token_type | urn:ietf:params:oauth:token-type:id_token | | user_profile | { "name": { "firstName": string, "lastName": string }, "email": string } 可选。Apple首次登录发送的JSON字符串（仅在首次登录时需要，如果要存储用户名）|

2. 使用Apple authorization_code

查看图像中的“3”，您想要使用领域中的/token端点，以Apple的authorizationCode交换Keycloak令牌。
<keycloak server url>/realms/<realm>/protocol/openid-connect/token
application/x-www-form-urlencoded

详细的参数解释可见原文档。

结论

此项目是将Apple登录体验无缝集成到Keycloak环境中的理想解决方案。无论你是网页应用开发者还是移动应用开发者，都可以轻松地让使用者利用他们的Apple账户安全登录你的应用。它提供了清晰的安装步骤，详尽的配置选项，并且具有良好的兼容性列表，帮助你在不同版本的Keycloak上顺利运行。现在就加入并尝试一下吧，让Apple用户也能享受到便捷的登录体验！