通用 OAuth2 提供者

GitHub

复制一个包含安装步骤和本插件的完整Markdown指南的设置提示。

介绍

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

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

本配置是多供应商设计。您可以一次注册多个供应商，然后在登录时选择一个。 oauth2 您需要什么 providerId.

在配置供应商之前，请收集：

与您的应用程序方案或 Web 回调 URL 匹配的重定向 URL

授权终点
授权流程中的令牌终点，或 OIDC 发现终点
您的应用程序需要的范围，例如
A token endpoint for authorization code flow, or an issuerUrl __CAPGO_KEEP_0__
__CAPGO_KEEP_0__ openid profile email

__CAPGO_KEEP_0__

在应用启动时只需一次使用并注册所需的每个提供者： SocialLogin.initialize() Copy to clipboard

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发现和别名

Copy to clipboard issuerUrl 该插件还支持常见的OAuth和OpenID Connect别名：

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

的别名

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

也可用：

additionalParameters 用于 auth 请求覆盖
additionalTokenParameters 用于 token 交换覆盖
additionalResourceHeaders 用于自定义资源端点头
additionalLogoutParameters 和 postLogoutRedirectUrl 用于注销流程
loginHint, prompt、 iosPrefersEphemeralSession

Auth Connect 兼容的预设

If you are migrating from Ionic Auth Connect and want to keep the same provider names, use 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

If a provider needs custom endpoints, either override them in the preset or bypass presets and configure the provider directly in oauth2.

配置选项

类型	是否必填	描述	字符串
`appId` / `clientId`	是	Yes	OAuth2客户端标识符
`issuerUrl`	string	否	OIDC发现基址URL
`authorizationBaseUrl` / `authorizationEndpoint`	string	是*	授权端点URL
`accessTokenEndpoint` / `tokenEndpoint`	string	否*	令牌端点URL
`redirectUrl`	string	是	回调 URL
`scope` / `scopes`	string / string[]	否	请求的权限
`pkceEnabled`	boolean	否	默认值 `true`
`responseType`	`'code'` 或 `'token'`	否	默认值 `'code'`
`resourceUrl`	string	否	用户信息或资源端点
`logoutUrl` / `endSessionEndpoint`	字符串	否	注销或结束会话 URL
`postLogoutRedirectUrl`	字符串	否	注销后重定向 URL
`additionalParameters`	`Record<string, string>`	否	额外的认证请求参数
`additionalTokenParameters`	`Record<string, string>`	否	额外的令牌请求参数
`additionalResourceHeaders`	`Record<string, string>`	否	Extra headers for `resourceUrl`
`additionalLogoutParameters`	`Record<string, string>`	不需要	Extra logout params
`loginHint`	字符串	不需要	Shortcut for `additionalParameters.login_hint`
`prompt`	字符串	不需要	Shortcut for `additionalParameters.prompt`
`iosPrefersEphemeralSession`	布尔值	不需要	在 iOS 上优先使用临时浏览器会话
`logsEnabled`	boolean	否	启用详细调试日志

authorizationBaseUrl 并且 accessTokenEndpoint 只有当 issuerUrl 仅仅是足够的发现。显式端点总是优先于发现的值。

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

在 Web 上重定向流

Use 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

Use GitHub when you want a simple OAuth app flow and basic profile data:

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

__CAPGO_KEEP_0__

当您需要 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 适合需要 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 示例

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

当提供者发布时，请使用发现 /.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`	访问令牌负载或
`accessToken`	如果提供者返回了一个 OIDC ID 令牌，则是 OIDC ID 令牌 `null`
`idToken`	__CAPGO_KEEP_0__
`refreshToken`	如果请求的权限范围允许，刷新令牌
`resourceData`	原始 JSON 从 `resourceUrl`
`scope`	已授权的权限范围
`tokenType`	通常 `bearer`
`expiresIn`	令牌有效期（秒）

提供者设置参考

GitHub

打开 __CAPGO_KEEP_0__ 开发者设置 GitHub 并创建一个新的 OAuth App。
设置回调 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

创建本机应用 打开 Auth0 控制台并创建一个本机应用。
设置允许的回调 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,
    },
  },
});

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

平台相关说明

iOS

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

Android

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

Web

当提供商阻止弹出式浏览器或您的认证规则需要顶级导航时，重定向流程更好。
某些提供商阻止直接浏览器令牌交换。在这种情况下，请使用后端交换或允许公共客户端的提供商设置。
安全最佳实践

安全最佳实践

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

故障排除

`providerId is required`

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

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

`OAuth2 provider "xxx" not configured`

Call SocialLogin.initialize() 在登录之前确保 providerId 与 oauth2.

重定向 URL 不匹配

将您的应用程序和提供商控制台中配置的重定向 URL 字符逐一比较。
注意URL末尾是否有斜杠、协议不匹配以及主机不同。
确保在设备上测试前，已注册移动应用程序URL方案。

未返回刷新令牌

大多数提供商只有在您请求像“或明确要求同意”这样的范围时才会返回刷新令牌。请查看提供商的具体政策。 offline_access 令牌交换调试

标题：令牌交换调试

在提供商配置中启用以检查生成的URL和令牌交换详细信息。 logsEnabled: true 相关文档

继续使用通用 OAuth2 提供商

如果您正在使用 通用 OAuth2 提供商 来规划身份验证和帐户流程，连接它使用 @capgo/capacitor-social-login 为 @capgo/capacitor-social-login 原生能力使用 @capgo/capacitor-social-login 为 @capgo/capacitor-social-login 实现细节使用 @capgo/capacitor-passkey for the implementation detail in @capgo/capacitor-passkey, @capgo/capacitor-native-biometric for the implementation detail in @capgo/capacitor-native-biometric, and 双因素认证 for the implementation detail in 双因素认证。

通用 OAuth2 提供者

介绍

在配置供应商之前，请收集：

__CAPGO_KEEP_0__

OpenID Connect发现和别名

Auth Connect 兼容的预设

配置选项

使用 OAuth2 登录

登录

在 Web 上重定向流

登录状态和注销

刷新令牌

获取当前访问令牌

提供商特定的示例

示例：GitHub

__CAPGO_KEEP_0__

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

重定向 URL 不匹配

未返回刷新令牌

标题：令牌交换调试

标题：相关文档

继续使用通用 OAuth2 提供商

`providerId is required`

`OAuth2 provider "xxx" not configured`