跳过内容
Capgo - 为 Capacitor 应用提供实时更新 Capgo

通用 OAuth2 提供商

介绍

标题为“介绍”的部分

The Capgo Social Login plugin includes a built-in OAuth2 and OpenID Connect engine. You can use it to connect any standards-based identity provider, including:

  • GitHub
  • Azure AD / Microsoft Entra ID
  • Auth0
  • Okta
  • Keycloak
  • 自定义 OAuth2 或 OIDC 服务器

The oauth2 配置是多提供者设计的。您可以一次注册多个提供者，然后在登录时选择一个。 providerId.

您需要什么

标题：您需要什么

在配置提供者之前，请收集：

  • 您的 OAuth 客户端 ID
  • 与您的应用程序方案或 Web 回调 URL 匹配的重定向 URL
  • 授权终端
  • 授权流程 code 的令牌终端，或者授权终端 issuerUrl for OIDC discovery
  • 您的应用程序需要的范围，例如 openid profile email

多提供商配置

多提供商配置

在应用程序启动时只需执行一次，注册所需的每个提供商： SocialLogin.initialize() 复制到剪贴板

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


await SocialLogin.initialize({
  oauth2: {
    github: {
      appId: 'your-github-client-id',
      authorizationBaseUrl: 'https://github.com/login/oauth/authorize',
      accessTokenEndpoint: 'https://github.com/login/oauth/access_token',
      redirectUrl: 'myapp://oauth/github',
      scope: 'read:user user:email',
      pkceEnabled: true,
      resourceUrl: 'https://api.github.com/user',
    },
    azure: {
      appId: 'your-azure-client-id',
      authorizationBaseUrl: 'https://login.microsoftonline.com/common/oauth2/v2.0/authorize',
      accessTokenEndpoint: 'https://login.microsoftonline.com/common/oauth2/v2.0/token',
      redirectUrl: 'myapp://oauth/azure',
      scope: 'openid profile email User.Read',
      pkceEnabled: true,
      resourceUrl: 'https://graph.microsoft.com/v1.0/me',
    },
    auth0: {
      issuerUrl: 'https://your-tenant.auth0.com',
      appId: 'your-auth0-client-id',
      redirectUrl: 'myapp://oauth/auth0',
      scope: 'openid profile email offline_access',
      pkceEnabled: true,
      additionalParameters: {
        audience: 'https://your-api.example.com',
      },
    },
  },
});

如果您的提供商公开了OpenID Connect发现文档，则

是最简单的设置：

复制到剪贴板 issuerUrl __CAPGO_KEEP_0__

await SocialLogin.initialize({
  oauth2: {
    keycloak: {
      issuerUrl: 'https://sso.example.com/realms/mobile',
      clientId: 'mobile-app',
      redirectUrl: 'myapp://oauth/keycloak',
      scope: 'openid profile email offline_access',
      pkceEnabled: true,
    },
  },
});

该插件还支持常见的OAuth和OIDC别名:

  • clientId 作为__CAPGO_KEEP_0__的别名 appId
  • authorizationEndpoint 作为__CAPGO_KEEP_0__的别名 authorizationBaseUrl
  • tokenEndpoint 作为__CAPGO_KEEP_0__的别名 accessTokenEndpoint
  • endSessionEndpoint 作为__CAPGO_KEEP_0__的别名 logoutUrl
  • scopes 作为__CAPGO_KEEP_0__的别名 scope

另外可用:

  • additionalParameters 用于授权请求覆盖
  • additionalTokenParameters 用于令牌交换覆盖
  • additionalResourceHeaders 用于自定义资源端点头
  • additionalLogoutParameters 和 postLogoutRedirectUrl 用于注销流程
  • loginHint, prompt, 和 iosPrefersEphemeralSession

Auth Connect 兼容的预设

标题：Auth Connect 兼容的预设

如果您从 Ionic Auth Connect 迁移并希望保留相同的提供者名称，请使用 SocialLoginAuthConnect.

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


await SocialLoginAuthConnect.initialize({
  authConnect: {
    auth0: {
      domain: 'https://your-tenant.auth0.com',
      clientId: 'your-auth0-client-id',
      redirectUrl: 'myapp://oauth/auth0',
      audience: 'https://your-api.example.com',
    },
    azure: {
      tenantId: 'common',
      clientId: 'your-azure-client-id',
      redirectUrl: 'myapp://oauth/azure',
    },
    okta: {
      issuer: 'https://dev-12345.okta.com/oauth2/default',
      clientId: 'your-okta-client-id',
      redirectUrl: 'myapp://oauth/okta',
    },
  },
});

支持的预设提供者 ID:

  • auth0
  • azure
  • cognito
  • okta
  • onelogin

如果提供者需要自定义端点，请在预设中覆盖它们，或者绕过预设并直接在 oauth2.

配置选项

标题：配置选项
选项类型必填描述
appId / clientId字符串是OAuth2 客户端标识符
issuerUrl字符串否OIDC 发现基址 URL
authorizationBaseUrl / authorizationEndpoint是*授权终端 URL字符串
accessTokenEndpoint / tokenEndpoint否*__CAPGO_KEEP_0____CAPGO_KEEP_0__
redirectUrl字符串是__CAPGO_KEEP_1__
scope / scopes字符串 / 字符串[]否__CAPGO_KEEP_2__
pkceEnabled布尔否__CAPGO_KEEP_3__ true
responseType'code' 或 'token'否默认值为 'code'
resourceUrl__CAPGO_KEEP_0__否用户信息或资源端点
logoutUrl / endSessionEndpoint__CAPGO_KEEP_0__否注销或结束会话URL
postLogoutRedirectUrl__CAPGO_KEEP_0__注销后重定向URL否
additionalParametersRecord<string, string>额外的身份验证请求参数__CAPGO_KEEP_0__
additionalTokenParametersRecord<string, string>否__CAPGO_KEEP_0__
additionalResourceHeadersRecord<string, string>否__CAPGO_KEEP_0__ resourceUrl
additionalLogoutParametersRecord<string, string>否__CAPGO_KEEP_0__
loginHint字符串否__CAPGO_KEEP_0__ additionalParameters.login_hint
prompt__CAPGO_KEEP_0__否__CAPGO_KEEP_0__ additionalParameters.prompt
iosPrefersEphemeralSessionboolean否在 iOS 上优先使用短暂的浏览器会话
logsEnabledboolean否启用详细的调试日志

authorizationBaseUrl 和 accessTokenEndpoint 只有当 issuerUrl 足以进行发现。显式端点始终优先于发现的值。

使用 OAuth2 登录

标题：使用 OAuth2 登录

登录

登录
const result = await SocialLogin.login({
  provider: 'oauth2',
  options: {
    providerId: 'github',
    scope: 'read:user user:email',
    loginHint: 'user@example.com',
  },
});

在 Web 上重定向流程

在 Web 上重定向流程

使用 flow: 'redirect' 如果您想要全屏重定向而不是弹出窗口：

await SocialLogin.login({
  provider: 'oauth2',
  options: {
    providerId: 'auth0',
    flow: 'redirect',
  },
});

复制到剪贴板

const result = await SocialLogin.handleRedirectCallback();
if (result?.provider === 'oauth2') {
  console.log(result.result.providerId);
}

复制到剪贴板

登录状态和注销
const status = await SocialLogin.isLoggedIn({
  provider: 'oauth2',
  providerId: 'github',
});


await SocialLogin.logout({
  provider: 'oauth2',
  providerId: 'github',
});

刷新令牌

刷新令牌
await SocialLogin.refresh({
  provider: 'oauth2',
  options: {
    providerId: 'github',
  },
});


const refreshed = await SocialLogin.refreshToken({
  provider: 'oauth2',
  providerId: 'github',
  refreshToken: 'existing-refresh-token',
});

refresh() 使用插件存储的刷新令牌。 refreshToken() 让您传递一个刷新令牌并返回新的 OAuth2 响应。

获取当前访问令牌

获取当前访问令牌
const code = await SocialLogin.getAuthorizationCode({
  provider: 'oauth2',
  providerId: 'github',
});


console.log(code.accessToken);

提供商特定的示例

提供商特定的示例

GitHub示例

GitHub示例

在需要简单的 OAuth 应用流程和基本的用户资料时，请使用 GitHub：

await SocialLogin.initialize({
  oauth2: {
    github: {
      appId: 'your-github-client-id',
      authorizationBaseUrl: 'https://github.com/login/oauth/authorize',
      accessTokenEndpoint: 'https://github.com/login/oauth/access_token',
      redirectUrl: 'myapp://oauth/github',
      scope: 'read:user user:email',
      pkceEnabled: true,
      resourceUrl: 'https://api.github.com/user',
    },
  },
});


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


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

Azure AD / Microsoft Entra ID 示例

Azure AD / Microsoft Entra ID 示例

当您需要 Microsoft Graph 数据（如用户资料）时，请使用 Azure：

await SocialLogin.initialize({
  oauth2: {
    azure: {
      appId: 'your-azure-client-id',
      authorizationBaseUrl: 'https://login.microsoftonline.com/common/oauth2/v2.0/authorize',
      accessTokenEndpoint: 'https://login.microsoftonline.com/common/oauth2/v2.0/token',
      redirectUrl: 'myapp://oauth/azure',
      scope: 'openid profile email User.Read',
      pkceEnabled: true,
      resourceUrl: 'https://graph.microsoft.com/v1.0/me',
    },
  },
});


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


console.log(azureResult.result.idToken);
console.log(azureResult.result.resourceData);

Auth0 示例

Auth0 示例

Auth0 适合需要 OIDC 加自定义 API 受众时：

await SocialLogin.initialize({
  oauth2: {
    auth0: {
      appId: 'your-auth0-client-id',
      authorizationBaseUrl: 'https://your-tenant.auth0.com/authorize',
      accessTokenEndpoint: 'https://your-tenant.auth0.com/oauth/token',
      redirectUrl: 'myapp://oauth/auth0',
      scope: 'openid profile email offline_access',
      pkceEnabled: true,
      additionalParameters: {
        audience: 'https://your-api.example.com',
      },
    },
  },
});


const auth0Result = await SocialLogin.login({
  provider: 'oauth2',
  options: {
    providerId: 'auth0',
    flow: 'redirect',
  },
});

如果您在 Web 上使用重定向流程，请在回调页面上读取结果：

const auth0Result = await SocialLogin.handleRedirectCallback();
if (auth0Result?.provider === 'oauth2') {
  console.log(auth0Result.result.idToken);
}

Okta 示例

Okta 示例
await SocialLogin.initialize({
  oauth2: {
    okta: {
      appId: 'your-okta-client-id',
      authorizationBaseUrl: 'https://your-domain.okta.com/oauth2/default/v1/authorize',
      accessTokenEndpoint: 'https://your-domain.okta.com/oauth2/default/v1/token',
      redirectUrl: 'myapp://oauth/okta',
      scope: 'openid profile email offline_access',
      pkceEnabled: true,
      resourceUrl: 'https://your-domain.okta.com/oauth2/default/v1/userinfo',
    },
  },
});


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


console.log(oktaResult.result.resourceData);

Keycloak 示例

Keycloak 示例

当提供者发布时，请使用发现 /.well-known/openid-configuration:

await SocialLogin.initialize({
  oauth2: {
    keycloak: {
      issuerUrl: 'https://sso.example.com/realms/mobile',
      clientId: 'mobile-app',
      redirectUrl: 'myapp://oauth/keycloak',
      scope: 'openid profile email offline_access',
      pkceEnabled: true,
    },
  },
});


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


console.log(keycloakResult.result.idToken);

OAuth2 响应形状

OAuth2 登录成功时返回：

字段

描述__CAPGO_KEEP_0__
providerId已配置的提供者密钥用于登录
accessToken访问令牌载荷或 null
idTokenOIDC ID令牌，如果提供者返回了一个
refreshToken刷新令牌，如果请求的范围允许的话
resourceData从 resourceUrl
scope已授予的范围
tokenType通常 bearer
expiresIn令牌有效期（秒）

提供者设置参考

标题为“提供者设置参考”的部分

GitHub

标题为“GitHub”的部分

  1. 创建 OAuth 应用 打开 GitHub 开发者设置 并创建一个新的 OAuth 应用。

  2. 设置回调 URL 使用您的应用重定向 URL，例如 myapp://oauth/github.

  3. 配置插件

    await SocialLogin.initialize({
      oauth2: {
        github: {
          appId: 'your-github-client-id',
          authorizationBaseUrl: 'https://github.com/login/oauth/authorize',
          accessTokenEndpoint: 'https://github.com/login/oauth/access_token',
          redirectUrl: 'myapp://oauth/github',
          scope: 'read:user user:email',
          pkceEnabled: true,
          resourceUrl: 'https://api.github.com/user',
        },
      },
    });

Azure AD / Microsoft Entra ID

Azure AD / Microsoft Entra ID 部分

  1. 注册应用 前往 Azure Portal，打开 App registrations, 并创建一个本地或移动应用程序注册。

  2. 添加重定向 URI 添加一个与您的应用回调 URL 匹配的移动或桌面重定向 URI。

  3. 配置插件

    await SocialLogin.initialize({
      oauth2: {
        azure: {
          appId: 'your-azure-client-id',
          authorizationBaseUrl: 'https://login.microsoftonline.com/common/oauth2/v2.0/authorize',
          accessTokenEndpoint: 'https://login.microsoftonline.com/common/oauth2/v2.0/token',
          redirectUrl: 'myapp://oauth/azure',
          scope: 'openid profile email User.Read',
          pkceEnabled: true,
          resourceUrl: 'https://graph.microsoft.com/v1.0/me',
        },
      },
    });

标题为“Auth0”的部分

创建一个本地应用

  1. Add the redirect URI 打开__CAPGO_KEEP_0__ Auth0控制台 创建一个原生应用

  2. 设置允许的回调URL 添加您的Capacitor应用使用的exact重定向URL

  3. 配置插件

    await SocialLogin.initialize({
      oauth2: {
        auth0: {
          appId: 'your-auth0-client-id',
          authorizationBaseUrl: 'https://your-tenant.auth0.com/authorize',
          accessTokenEndpoint: 'https://your-tenant.auth0.com/oauth/token',
          redirectUrl: 'myapp://oauth/auth0',
          scope: 'openid profile email offline_access',
          pkceEnabled: true,
          additionalParameters: {
            audience: 'https://your-api.example.com',
          },
          logoutUrl: 'https://your-tenant.auth0.com/v2/logout',
        },
      },
    });

Okta

Okta部分

  1. 创建OIDC原生应用 在Okta管理控制台中，创建一个OIDC原生应用

  2. 添加重定向URI 在您的应用程序中使用的精确回调 URL 注册。

  3. 配置插件

    await SocialLogin.initialize({
      oauth2: {
        okta: {
          appId: 'your-okta-client-id',
          authorizationBaseUrl: 'https://your-domain.okta.com/oauth2/default/v1/authorize',
          accessTokenEndpoint: 'https://your-domain.okta.com/oauth2/default/v1/token',
          redirectUrl: 'myapp://oauth/okta',
          scope: 'openid profile email offline_access',
          pkceEnabled: true,
          resourceUrl: 'https://your-domain.okta.com/oauth2/default/v1/userinfo',
        },
      },
    });

Keycloak 和自定义 OIDC 提供商

Keycloak 和自定义 OIDC 提供商部分

如果您的提供商支持 OpenID Connect 发现，优先 issuerUrl:

await SocialLogin.initialize({
  oauth2: {
    keycloak: {
      issuerUrl: 'https://sso.example.com/realms/mobile',
      clientId: 'mobile-app',
      redirectUrl: 'myapp://oauth/keycloak',
      scope: 'openid profile email offline_access',
      pkceEnabled: true,
    },
  },
});

如果发现不可用，请手动配置授权和令牌端点。

平台特定说明

平台特定说明部分

iOS

iOS部分
  • 该插件使用 ASWebAuthenticationSession.
  • 设置 iosPrefersEphemeralSession: true 如果您想要一个不共享Cookie的私有浏览器会话。

Android

Android部分
  • OAuth重定向返回到您的应用程序方案和主机。
  • 确保提供商回调URL与您的Android深度链接设置完全匹配。
  • 该插件已经处理了OAuth活动。只有当您的应用程序需要不同的重定向模式时才添加自定义意图过滤器。

Web

Web部分
  • 弹出流程是默认的，适用于单页应用程序。
  • 重定向流程在提供商阻止弹出窗口或您的认证规则要求顶级导航时更好。
  • 某些提供商会阻止直接浏览器令牌交换，使用 CORS。 在这种情况下，请使用后端交换或允许公共客户端的提供商设置。

安全最佳实践

安全最佳实践

  1. 使用 PKCE 保留 pkceEnabled: true 用于公共客户端的

  2. Prefer authorization code flow responseType: 'code' 在您的后端验证令牌

  3. 在服务器端解码和验证发行者、受众、过期时间和签名 安全存储刷新令牌

  4. 对于原生应用程序，请将此插件与 Capacitor @capgo/capacitor-持久性账户.

  5. 全局使用 HTTPS 生产环境的认证端点和注销端点应该始终使用 HTTPS。

故障排除

故障排除

providerId is required

需要配置的提供者 ID：

每个 OAuth2 方法都需要配置的提供者密钥：

await SocialLogin.login({
  provider: 'oauth2',
  options: { providerId: 'github' },
});

OAuth2 provider "xxx" not configured

未配置 OAuth2 提供者 "xxx"

在登录之前调用并确保 SocialLogin.initialize() 与对象键匹配 providerId 全局使用 HTTPS oauth2.

重定向 URL 不匹配

重定向 URL 不匹配
  • 在应用程序和提供商控制台中比较配置的重定向 URL 的每个字符。
  • 注意尾随斜杠、方案不匹配和不同主机。
  • 在设备上测试之前，请确保已注册移动应用程序 URL 方案。

未返回刷新令牌

未返回刷新令牌

大多数提供商仅在您请求的范围（如“openid”或“profile”）或明确要求同意时才返回刷新令牌。请查看提供商的具体政策。 offline_access 调试令牌交换

调试令牌交换

启用

调试令牌交换 logsEnabled: true 在提供者配置中检查生成的 URL 和令牌交换详细信息。

标题：相关文档