通用 OAuth2 提供商

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

介绍

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 服务器

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

您需要什么

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

您的 OAuth 客户端 ID
一个与您的应用程序方案或 Web 回调 URL 匹配的重定向 URL
授权终端
A token endpoint for authorization code flow, or an issuerUrl 授权流程的令牌终端，或者 OIDC 发现
您的应用程序需要的权限，例如 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发现文档 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 用于授权请求覆盖
additionalTokenParameters 用于令牌交换覆盖
additionalResourceHeaders 用于自定义资源端点头
additionalLogoutParameters 并且（在Capgo营销网站上） postLogoutRedirectUrl 用于注销流程
loginHint, prompt，并且 iosPrefersEphemeralSession

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` / `clientId`	OAuth2 客户端标识符	是	OAuth2 客户端标识符
`issuerUrl`	字符串	否	OIDC 发现基址 URL
`authorizationBaseUrl` / `authorizationEndpoint`	字符串	是*	授权端点 URL
`accessTokenEndpoint` / `tokenEndpoint`	字符串	否*	令牌端点 URL
`redirectUrl`	string	是	回调 URL
`scope` / `scopes`	string / string[]	否	请求的权限
`pkceEnabled`	boolean	否	默认值 `true`
`responseType`	`'code'` 或 `'token'`	否	默认值 `'code'`
`resourceUrl`	授权登录	否	用户信息或资源端点
`logoutUrl` / `endSessionEndpoint`	string	否	注销或结束会话 URL
`postLogoutRedirectUrl`	string	否	注销后重定向 URL
`additionalParameters`	`Record<string, string>`	string	否
`additionalTokenParameters`	`Record<string, string>`	额外的身份验证请求参数	额外的令牌请求参数
`additionalResourceHeaders`	`Record<string, string>`	否	额外的头部 `resourceUrl`
`additionalLogoutParameters`	`Record<string, string>`	否	额外的注销参数
`loginHint`	字符串	否	快捷方式 `additionalParameters.login_hint`
`prompt`	字符串	否	快捷方式 `additionalParameters.prompt`
`iosPrefersEphemeralSession`	布尔值	No	在 iOS 中优先使用临时会话
`logsEnabled`	boolean	No	启用详细调试日志

authorizationBaseUrl and accessTokenEndpoint context:Capgo营销网站, 角色:短 UI 标签或导航项, 见于: page trust.astro. Message key `and` (And). 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',
});

刷新令牌

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 应用流程和基本的用户资料：

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

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`	访问令牌载荷或 `null`
`idToken`	OIDC ID令牌，如果提供者返回了一个
`refreshToken`	刷新令牌，如果请求的范围允许的话
`resourceData`	从原始JSON中获取 `resourceUrl`
`scope`	已批准的范围
`tokenType`	通常 `bearer`
`expiresIn`	令牌有效时间（秒）

提供者设置参考

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

创建原生应用 打开 Auth0 控制台并创建一个原生应用。
设置允许的回调 URL 添加您的 Capacitor 应用程序使用的exact 重定向 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 注册您的应用程序使用的exact 回调 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 的私有浏览器会话中使用 OAuth2。

Android

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

Web

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

安全最佳实践

使用 PKCE 保持 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`

呼叫 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 社交登录的实现细节 @capgo/capacitor 传递密钥为 @capgo/capacitor 传递密钥的实现细节 @capgo/capacitor 原生生物识别为 @capgo/capacitor 原生生物识别的实现细节, 和双因素认证为双因素认证的实现细节

通用 OAuth2 提供商

介绍

您需要什么

多提供商配置

OIDC发现和别名

Auth Connect兼容的预设

配置选项

使用 OAuth2 登录

登录

在 Web 上重定向

登录状态和注销

刷新令牌

获取当前访问令牌

提供商特定的示例

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

重定向 URL 不匹配

未返回刷新令牌

标题：调试令牌交换

相关文档

继续使用通用 OAuth2 提供商

`providerId is required`

`OAuth2 provider "xxx" not configured`