Keycloak

概览

Keycloak 通过内置的通用 OAuth2 provider 接入。无需为 Keycloak 新增 native provider。将 Keycloak client 配置为 OpenID Connect client，并使用 provider: 'oauth2' 搭配稳定的 providerId，例如 keycloak.

Keycloak client 设置

在你的 Keycloak realm 中，创建或打开 Capacitor 应用所用的 client：

1. 使用授权 code flow。
2. 在应用配置中保持启用 PKCE。
3. 注册你的应用用到的所有 redirect URI，例如 myapp://oauth/keycloak 用于移动端，以及用于生产环境 Web 的 HTTPS callback URL。
4. 使用如下 scope： openid profile email。添加 offline_access 仅当您的 realm 和 client 已配置为签发 refresh token 时。

确切的 issuer URL 因部署而异。当前 Keycloak 部署通常会在以下位置发布 realm 元数据： https://keycloak.example.com/realms/my-realm/.well-known/openid-configuration但某些部署会包含额外的 base path。请使用您的 realm 的 OpenID Endpoint Configuration 中显示的 issuer URL。

OIDC discovery 示例

优先使用 issuerUrl 以便插件可以从 realm 元数据中发现 authorization、token 和 logout 端点：

import { SocialLogin } from '@capgo/capacitor-social-login';

const keycloakIssuer = 'https://keycloak.example.com/realms/my-realm';

await SocialLogin.initialize({
  oauth2: {
    keycloak: {
      appId: 'your-keycloak-client-id',
      issuerUrl: keycloakIssuer,
      redirectUrl: 'myapp://oauth/keycloak',
      scope: 'openid profile email',
      pkceEnabled: true,
      resourceUrl: `${keycloakIssuer}/protocol/openid-connect/userinfo`,
    },
  },
});

const result = await SocialLogin.login({
  provider: 'oauth2',
  options: {
    providerId: 'keycloak',
  },
});

console.log(result.result.idToken);
console.log(result.result.accessToken?.token);
console.log(result.result.resourceData);

如需 refresh token，请请求 offline_access 仅当您的 Keycloak realm 和 client 允许此应用使用 refresh token 时：

await SocialLogin.initialize({
  oauth2: {
    keycloak: {
      appId: 'your-keycloak-client-id',
      issuerUrl: keycloakIssuer,
      redirectUrl: 'myapp://oauth/keycloak',
      scope: 'openid profile email offline_access',
      pkceEnabled: true,
    },
  },
});

手动端点回退

如果 OIDC discovery 被阻止，或您的部署未向应用暴露元数据，请直接配置 endpoint。请保持 base URL 与 Keycloak 部署发布的完全一致：

const keycloakRealmUrl = 'https://keycloak.example.com/realms/my-realm';

await SocialLogin.initialize({
  oauth2: {
    keycloak: {
      appId: 'your-keycloak-client-id',
      authorizationBaseUrl: `${keycloakRealmUrl}/protocol/openid-connect/auth`,
      accessTokenEndpoint: `${keycloakRealmUrl}/protocol/openid-connect/token`,
      redirectUrl: 'myapp://oauth/keycloak',
      scope: 'openid profile email',
      pkceEnabled: true,
      resourceUrl: `${keycloakRealmUrl}/protocol/openid-connect/userinfo`,
      logoutUrl: `${keycloakRealmUrl}/protocol/openid-connect/logout`,
    },
  },
});

Auth Connect 兼容性

Keycloak 不在 Auth Connect 的预设 provider ID 列表中。如果您已经在使用 SocialLoginAuthConnect，您仍然可以初始化通用的 oauth2 provider 并使用 provider: 'oauth2' 加 providerId: 'keycloak'.

请参阅 Keycloak OpenID Connect endpoint 参考文档 以获取 discovery 和 endpoint 路径。

相关文档

• OAuth2 和 OIDC 提供商
• Better Auth 集成
• Ionic Auth Connect 迁移

从 Keycloak 继续

如果你正在使用 Keycloak 用来规划身份验证和账户流程，并将它与 使用 @capgo/capacitor-social-login 关于使用 @capgo/capacitor-social-login 的原生能力， @capgo/capacitor-social-login 在 @capgo/capacitor-social-login 中查看实现细节， @capgo/capacitor-passkey 有关 @capgo/capacitor-passkey 的实现细节， @capgo/capacitor-native-biometric 以及 @capgo/capacitor-native-biometric 中的实现细节， 双因素认证 有关双重身份验证的实现细节。