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

通用 OAuth2 提供商

GitHub

介绍

标题为“介绍”的部分

Capgo 社会登录插件内置了 OAuth2 和 OpenID Connect 引擎。您可以使用它连接任何基于标准的身份提供商，包括:

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

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

您需要什么

标题为“您需要什么”

在配置提供者之前，请收集以下信息：

  • 您的 OAuth 客户端 ID
  • 与您的应用程序方案或 Web 回调 URL 匹配的重定向 URL
  • 授权终端
  • 授权流程 code 的令牌终端，或者 OIDC 发现 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 该插件还支持常见的OAuth和OIDC别名:

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,
    },
  },
});

__CAPGO_KEEP_0__

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

此外可用:

  • additionalParameters 用于授权请求覆盖
  • additionalTokenParameters 用于令牌交换覆盖
  • additionalResourceHeaders 用于自定义资源端点头
  • additionalLogoutParameters 并且（在Capgo营销网站上，页面信任区域） 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.

配置选项

选项
类型必填描述Section titled “Configuration options”
appId / clientIdOAuth2 客户端标识符是OAuth2 客户端标识符
issuerUrl字符串否OIDC 发现基址 URL
authorizationBaseUrl / authorizationEndpoint字符串是*授权端点 URL
accessTokenEndpoint / tokenEndpoint字符串否*令牌端点 URL
redirectUrlstring是回调 URL
scope / scopesstring / string[]否请求的权限
pkceEnabledboolean否默认值 true
responseType'code' 或 'token'否默认值 'code'
resourceUrlstring没有用户信息或资源端点
logoutUrl / endSessionEndpointstring没有注销或结束会话URL
postLogoutRedirectUrlstring没有注销后重定向URL
additionalParametersRecord<string, string>没有额外的认证请求参数
additionalTokenParametersRecord<string, string>没有额外的令牌请求参数
additionalResourceHeadersRecord<string, string>否额外的请求头部 resourceUrl
additionalLogoutParametersRecord<string, string>否额外的注销参数
loginHint字符串否快捷方式 additionalParameters.login_hint
prompt字符串否快捷方式 additionalParameters.prompt
iosPrefersEphemeralSession布尔值No在 iOS 中优先使用会话式浏览器
logsEnabledbooleanNo启用详细调试日志

authorizationBaseUrl and 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',
});

Refresh tokens

Refresh tokens
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 示例

使用 GitHub 时，您可以实现一个简单的 OAuth 应用流程并获取基本的用户资料：

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 示例

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

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 响应形状

成功的 OAuth2 登录返回:

字段描述
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

标题为“Auth0”的部分

  1. 创建原生应用 打开 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 注册您的应用使用的exact 回调 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

该插件使用

__CAPGO_KEEP_0__
  • __CAPGO_KEEP_1__ ASWebAuthenticationSession.
  • 设置 iosPrefersEphemeralSession: true 如果您想在没有共享 Cookie 的私有浏览器会话中使用 OAuth2.

Android

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

Web

弹出式流程是默认的，适用于单页应用程序.
  • 重定向流程在提供商阻止弹出窗口或您的认证规则需要顶级导航时更好.
  • 一些提供商阻止直接浏览器令牌交换，使用 CORS。 在这种情况下，请使用后端交换或允许公共客户端的提供商设置.
  • Some providers block direct browser token exchange with CORS. In those cases, use a backend exchange or a provider setup that allows public clients.

安全最佳实践

安全最佳实践

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

  2. 优先使用 code 授权流 responseType: 'code' __CAPGO_KEEP_0__ 流比隐式流更安全。

  3. 在后端验证令牌 在服务器端解码和验证发行者、受众、过期时间和签名。

  4. 安全存储刷新令牌 对于原生应用程序，请将此插件与 @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-persistent-account 配对 @capgo/capacitor-persistent-account.

  5. 使用 HTTPS 全球 生产认证端点和注销端点应始终使用 HTTPS。

故障排除

故障排除

providerId is required

标题：“providerId 是必需的”

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

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

OAuth2 provider "xxx" not configured

标题：“OAuth2 提供者“xxx”未配置”

调用 SocialLogin.initialize() 在登录之前确保 providerId 匹配对象键下 oauth2.

重定向 URL 不匹配

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

No refresh token returned

Section titled “No refresh token returned”

大多数提供商只在您请求像“或显式强制-consent”这样的范围时才返回刷新令牌。 请查看提供商的具体政策。 offline_access Debugging token exchange

Section titled “Debugging token exchange”

在提供商配置中启用

以检查生成的 URL 和令牌交换详细信息。 logsEnabled: true 以检查生成的 URL 和令牌交换详细信息。

相关文档

从通用OAuth2提供商继续

从通用OAuth2提供商继续

如果您正在使用 通用OAuth2提供商 来规划身份验证和帐户流程，连接它 使用@capgo/capacitor-social-login 为使用@capgo/capacitor-social-login @capgo/capacitor-social-login 为 @capgo/capacitor 社交登录实现细节 @capgo/capacitor Passkey 为 @capgo/capacitor Passkey 实现细节 @capgo/capacitor 原生生物识别 为 @capgo/capacitor 原生生物识别实现细节, 和 双因素认证 为双因素认证实现细节