通用 OAuth2 提供商

GitHub

复制包含安装步骤和该插件完整 Markdown 指南的配置 prompt。

简介

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

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

本指南中介绍的 oauth2 配置在设计上支持多提供商。您可以同时注册多个提供商，然后在登录时选择其中一个： providerId.

准备工作

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

您的 OAuth 客户端 ID
与您的应用 scheme 或 Web 回调 URL 匹配的 redirect URL
授权端点
用于授权 code 流程的 token 端点，或 issuerUrl 用于 OIDC 发现的端点
您的应用所需的 scopes，例如 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',
      },
    },
  },
});

OIDC 发现与别名

如果你的提供商提供 OpenID Connect discovery 文档， 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,
    },
  },
});

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

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

还提供：

additionalParameters 用于覆盖 auth 请求
additionalTokenParameters 用于覆盖 token 交换
additionalResourceHeaders 用于自定义资源端点请求头
additionalLogoutParameters 以及 postLogoutRedirectUrl 用于登出流程
loginHint, prompt，以及 iosPrefersEphemeralSession

兼容 Auth Connect 的预设

如果你要从 Ionic Auth Connect 迁移，并想保留相同的 provider 名称，请使用 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',
    },
  },
});

支持的预设 provider ID：

auth0
azure
cognito
okta
onelogin

如果某个提供商需要自定义端点，可以在预设中覆盖，或跳过预设，直接在 oauth2.

配置选项

选项	类型	必填	描述
`appId` / `clientId`	字符串	是	OAuth2 客户端标识符
`issuerUrl`	字符串	否	OIDC discovery 基础 URL
`authorizationBaseUrl` / `authorizationEndpoint`	字符串	是*	授权端点 URL
`accessTokenEndpoint` / `tokenEndpoint`	字符串	否*	Token 端点 URL
`redirectUrl`	字符串	是	回调 URL
`scope` / `scopes`	OAuth2	否	请求的 scope
`pkceEnabled`	布尔值	否	默认为 `true`
`responseType`	`'code'` 或 `'token'`	否	默认为 `'code'`
`resourceUrl`	字符串	否	用户信息或资源端点
`logoutUrl` / `endSessionEndpoint`	字符串	否	登出或结束会话 URL
`postLogoutRedirectUrl`	字符串	否	登出后的重定向 URL
`additionalParameters`	`Record<string, string>`	否	额外的认证请求参数
`additionalTokenParameters`	`Record<string, string>`	否	额外的令牌请求参数
`additionalResourceHeaders`	`Record<string, string>`	否	额外的请求头 `resourceUrl`
`additionalLogoutParameters`	`Record<string, string>`	否	额外的登出参数
`loginHint`	字符串	否	快捷键： `additionalParameters.login_hint`
`prompt`	字符串	否	快捷键： `additionalParameters.prompt`
`iosPrefersEphemeralSession`	布尔值	否	在 iOS 上优先使用临时浏览器会话
`logsEnabled`	布尔值	否	启用详细调试日志

authorizationBaseUrl 以及 accessTokenEndpoint 仅在以下情况下为可选 issuerUrl 足以用于发现。显式端点始终优先于发现的值。

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

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 Token

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

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

refresh() 使用插件存储的 refresh token。 refreshToken() 允许您自行传入 refresh token，并返回最新的 OAuth2 响应。

获取当前 Access Token

const code = await SocialLogin.getAuthorizationCode({
  provider: 'oauth2',
  providerId: 'github',
});

console.log(code.accessToken);

各提供商示例

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

如果您需要 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 示例

当您需要 OIDC 以及自定义 API 受众时，Auth0 是一个不错的选择：

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

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

如果您的提供商发布了发现文档，请使用 discovery /.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 登录返回：

字段	描述
`providerId`	用于登录的已配置 provider key
`accessToken`	Access token payload 或 `null`
`idToken`	如果 provider 返回了 OIDC ID token
`refreshToken`	如果请求的 scopes 允许，则返回 Refresh token
`resourceData`	从以下位置获取的原始 JSON `resourceUrl`
`scope`	已授予的 scopes
`tokenType`	通常 `bearer`
`expiresIn`	Token 有效期（秒）

服务商配置参考

GitHub

创建 OAuth 应用 打开 GitHub 开发者设置并创建一个新的 OAuth 应用。
设置回调 URL 使用应用的重定向 URL，例如 myapp://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',
    },
  },
});

Azure AD / Microsoft Entra ID

注册应用 前往 Azure Portal，打开 App registrations，并创建原生或移动应用注册。
添加重定向 URI 添加与您的应用回调 URL 匹配的移动或桌面重定向 URI。

配置插件

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

创建 Native 应用 打开 Auth0 控制台并创建一个 Native 应用。
设置允许的回调 URL 添加您的 Capacitor 应用所使用的确切重定向 URL。

配置插件

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

创建 OIDC 原生应用 在 Okta 管理控制台中，创建一个 OIDC 原生应用。
添加重定向 URI 注册应用使用的确切回调 URL。

配置插件

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 提供商

如果您的提供商支持 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,
    },
  },
});

如果无法使用 discovery，请手动配置授权和 token 端点。

平台特定说明

iOS

该插件使用 ASWebAuthenticationSession.
设置 iosPrefersEphemeralSession: true 如果你想要一个不共享 Cookie 的私密浏览器会话。

Android

OAuth 重定向会通过你的应用 scheme 和 host 返回。
请确保提供商的回调 URL 与您的 Android deep link 配置完全一致。
该插件已处理 OAuth Activity。仅当您的应用需要不同的重定向模式时，才需添加自定义 intent filters。

Web 端

Popup 流程是默认选项，非常适合单页应用 (SPA)。
当提供商拦截弹窗，或您的身份验证规则需要顶层导航时，Redirect 流程更佳。
部分提供商会通过 CORS 拦截浏览器的直接 token 交换。在这种情况下，请使用后端交换，或配置允许公共客户端的提供商。

安全最佳实践

使用 PKCE 保留 pkceEnabled: true 用于公共客户端。
优先使用授权 code 流程 responseType: 'code' 比隐式流程更安全。
在后端验证令牌 在服务端解码并验证签发者、受众、过期时间和签名。
安全存储刷新令牌 对于原生应用，将此插件与 @capgo/capacitor-persistent-account.
全程使用 HTTPS 生产环境的认证端点和登出端点应始终使用 HTTPS。

故障排除

`providerId is required`

每个 OAuth2 方法都需要已配置的 provider key：

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

`OAuth2 provider "xxx" not configured`

调用 SocialLogin.initialize() 在登录前，并确保 providerId 与……下的对象键匹配 oauth2.

Redirect URL 不匹配

请逐字符对比 App 与 provider dashboard 中配置的 Redirect URL。
注意末尾斜杠、scheme 不匹配以及 host 不同。
在真机测试前，请确保已注册移动端 App 的 URL scheme。

未返回 refresh token

大多数提供商仅在请求类似 offline_access 的 scope 或显式强制同意时才会返回 refresh token。请查阅提供商的具体策略。

调试 Token 交换

启用 logsEnabled: true 在提供商配置中启用，以检查生成的 URL 和 token 交换详情。

从通用 OAuth2 提供商继续

如果你正在使用 通用 OAuth2 提供商 用来规划身份验证和账户流程，并将它与使用 @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 中的实现细节，双因素认证有关双重身份验证的实现细节。

通用 OAuth2 提供商

简介

准备工作

多提供商配置

OIDC 发现与别名

兼容 Auth Connect 的预设

配置选项

使用 OAuth2 登录

登录

Web 端重定向流程

登录状态与登出

Refresh Token

获取当前 Access Token

各提供商示例

GitHub 示例

Azure AD / Microsoft Entra ID 示例

Auth0 示例

Okta 示例

Keycloak 示例

OAuth2 响应结构

服务商配置参考

GitHub

Azure AD / Microsoft Entra ID

Auth0

Okta

Keycloak 和自定义 OIDC 提供商

平台特定说明

iOS

Android

Web 端

安全最佳实践

故障排除

providerId is required

OAuth2 provider "xxx" not configured

Redirect URL 不匹配

未返回 refresh token

调试 Token 交换

相关文档

从通用 OAuth2 提供商继续

`providerId is required`

`OAuth2 provider "xxx" not configured`