App2Web（预验证 URL）¶

预验证 URL 是一项功能，可以实现从移动应用到网站的单点登录（SSO）。它允许已经在移动应用中完成身份验证的用户，以已验证状态打开网站。

预验证 URL 的一个典型使用场景是在 WebView 中打开 Web 应用。

前提条件¶

要使用预验证 URL，您需要满足以下条件：

一个使用 Authany 进行身份验证的原生应用
一个使用相同 Authany 项目进行身份验证的 Web 应用

如何在应用中实现预验证 URL¶

步骤 1：在原生客户端应用中启用 SSO 和预验证 URL¶

首先，确保您的移动应用使用的是 原生应用（Native App） 类型的 Authany 应用。启用 "preAuthenticatedURL"，让预验证 URL 生效。

Ionic

authgear
  .configure({
    clientID: '<CLIENT_ID>',
    preAuthenticatedURLEnabled: true
  })

步骤 2：向 Web 应用客户端添加允许的来源¶

接下来，在 Authany 中为 Web 应用客户端添加允许的来源。

在 Authany 管理台中进入 高级 > 编辑配置，找到 Web 应用客户端，在 x_pre_authenticated_url_allowed_origins 键中添加您希望用于预验证 URL 的来源。同时将 x_pre_authenticated_url_enabled 设置为 true。

oauth:
  clients:
  - client_id: <Client ID of the web app>
    x_pre_authenticated_url_enabled: true
    x_pre_authenticated_url_allowed_origins:
    - <origin 1>
    - <origin 2>
    - ...
    ...

请注意，来源的格式应为「协议（scheme）+ 域名 + 端口」。例如，如果移动应用想要打开 https://www.mywebapp.com/home?key=value，来源必须是 https://www.mywebapp.com。

步骤 3：生成预验证 URL¶

预验证 URL 是 Authany SDK 为已启用预验证 URL 功能的移动客户端生成的链接。您的移动应用可以在 WebView 中打开预验证 URL，让用户以已验证状态开始浏览来源站点。

要生成预验证 URL，请按如下方式调用 Authany SDK 的 makePreAuthenticatedURL() 方法：

Ionic

const url = await authgear.makePreAuthenticatedURL({
    webApplicationClientID: "YOUR_WEB_APP_CLIENT_ID", // Replace with you web app client id
    webApplicationURI: "YOUR_WEB_APP_URI", // Replace with you web app uri
  });

makePreAuthenticatedURL() 方法接受一个对象作为参数。在该对象中，您需要提供 Web 应用的客户端 ID 和 Web 应用 URI。

步骤 4：在 WebView 中打开预验证 URL¶

在 makePreAuthenticatedURL() 返回 URL 之后，您的移动应用应在 WebView 中打开该 URL。此后，用户就可以在 Web 应用中延续（来自移动应用的）当前已验证会话。

IonicReact Native

以下代码示例展示了如何在 Ionic 中使用 Browser.open() 方法打开预验证 URL。

Browser.open({ url: url }).catch(err =>
      console.error("Couldn't load page", err),
);

以下代码示例展示了如何使用 React Native 的 Linking.openURL() 方法打开预验证 URL。

Linking.openURL(url).catch(err =>
      console.error("Couldn't load page", err),
);

步骤 5：在 Web 应用中获取已验证状态¶

预验证 URL 由原生应用在浏览器中打开。在 Web 应用中，使用注入的 SSO 会话触发身份验证，并获取已验证状态。

Web

在 Web 应用中，启用 SSO 以让预验证 URL 生效。您可以按如下方式初始化 SDK：

import authgear, { PromptOption } from "@authgear/web";

authgear.configure({
    endpoint: "AUTHGEAR_ENDPOINT",
    clientID: "CLIENT_ID",
    sessionType: "refresh_token",
    isSSOEnabled: true
});

然后在 Web 应用的 URI 中，按如下方式触发身份验证。请注意，这里使用 prompt: PromptOption.None 来跳过 SSO 继续页面。

import authgear, { PromptOption } from "@authgear/web";

authgear.startAuthentication({
  redirectURI: import.meta.env.VITE_AUTHGEAR_REDIRECT_URL,
  prompt: PromptOption.None // use "None" to skip the continue screen
})
.then(
  () => {
    // started authentication, user should be redirected to Authgear
   },
  (err) => {
    // failed to start authorization
  }
);

在正常的登录流程中，例如用户直接在浏览器中浏览网页，而不是通过原生应用中的链接打开，则不应使用该 prompt 参数，因为这会妨碍用户打开登录页面。只有在浏览器中确定已经设置了 SSO 会话时才应使用该 prompt，例如配合本预验证 URL 功能使用时。