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

通用 OAuth2 服务商

介绍

标题为“介绍”的部分。

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

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

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

您需要什么

标题：您需要什么

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

  • 您的 OAuth 客户端 ID
  • 一个与您的应用程序方案或 Web 回调 URL 匹配的重定向 URL
  • 授权终端
  • 授权流程的令牌端点code，或者 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发现和别名

标题为“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_KEEP_0__ 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__
redirectUrl字符串是__CAPGO_KEEP_0__
scope / scopes字符串 / 字符串[]否__CAPGO_KEEP_0__
pkceEnabled布尔值否__CAPGO_KEEP_0__ true
responseType'code' 或 'token'否默认值为 'code'
resourceUrl字符串否用户信息或资源端点
logoutUrl / endSessionEndpoint字符串否注销或结束会话 URL
postLogoutRedirectUrl字符串注销后重定向 URL否
additionalParametersRecord<string, string>__CAPGO_KEEP_0__额外的认证请求参数
additionalTokenParametersRecord<string, string>否额外的令牌请求参数
additionalResourceHeadersRecord<string, string>否额外的 resourceUrl
additionalLogoutParametersRecord<string, string>否额外的注销参数
loginHint字符串否快捷方式 additionalParameters.login_hint
prompt字符串否快捷方式 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);
}

登录状态和注销

Copy to clipboard
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 示例

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__CAPGO_KEEP_0__
accessToken登录时使用的配置提供者密钥 null
idToken如果提供者返回了一个，则是访问令牌载荷或 OIDC ID 令牌
refreshToken如果请求的范围允许，则是刷新令牌
resourceData从提供者获取的原始 JSON 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 注册您的应用程序使用的精确回调 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

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

安全最佳实践

安全最佳实践

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

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

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

  4. 安全存储刷新令牌 For native apps, pair this plugin with @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”未配置”

Call SocialLogin.initialize() 在登录之前确保 providerId 与对象键对应的值 oauth2.

重定向 URL 不匹配

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

未返回刷新令牌

未返回刷新令牌

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

调试令牌交换

__CAPGO_KEEP_0__

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

标题为“相关文档”的部分

从通用 OAuth2 提供商继续

标题为“从通用 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的实现细节, 双因素认证 为双因素认证的实现细节