跳转至

为基于 Cookie 的身份验证配置本地开发环境

本指南提供了一种简单的方法，帮助您快速搭建与 Authany SaaS 服务器通信的本地应用。

注意

本指南仅适用于本地开发环境中基于 Cookie 的身份验证场景，典型场景是开发网站。如果您开发的是使用基于令牌身份验证的移动应用，可以跳过本指南，照常开发即可。

使用 localhost 作为本地网站域名的问题

Authany 会在浏览器中为项目域名设置 Cookie。当您在 localhost 上运行应用时，浏览器无法看到这些 Cookie，因为该网站不属于设置 Cookie 的域名的子域。因此，浏览器将无法完成身份验证。

创建新的 Authany 项目

建议在继续本指南之前，先在 Authany 上为本地开发创建一个新应用。

  1. 登录并在 https://manage.authany.com/ 上创建一个新项目
  2. 进入控制台的 Application 标签页
  3. 在 Allowed Origins 列表中添加您的本地应用域名 {SUBDOMAIN}.{PROJECT_NAME}.authgear.cloud
  4. 添加一个应用，名称随意。请勿勾选 Issue JWT as access token 复选框，因为我们使用的是基于 Cookie 的授权方式。
  5. 分别在 Redirect URIs 列表和 Post Logout Redirect URIs 列表中填入登录和登出的重定向 URI。

在 hosts 中映射域名

为了让浏览器能看到 Cookie，本地网站域名必须处于设置 Cookie 的域名之内。

在本地机器的 /etc/hosts 文件中添加以下这行，即可将应用域名指向 localhost。

127.0.0.1 {SUBDOMAIN}.{PROJECT_NAME}.authgear.cloud

通过该域名访问网站时，浏览器就能看到身份验证 Cookie 了。

使用 HTTPS

虽然现在可以看到 Cookie 了，但这些 Cookie 设置了 Secure 属性。要在 HTTP 请求中携带它们，请求必须通过安全通道（在大多数浏览器中即 HTTPS）传输。因此，我们还需要为浏览器与服务器之间建立 HTTPS 连接。

生成证书

一种简便的方法是使用 mkcert，您可以按照这里的步骤安装。安装 mkcert 后，用以下命令生成证书：

mkcert "*.{PROJECT_NAME}.authgear.cloud"

系统会生成一个密钥文件和一个证书文件，将在本指南的下一部分用到。

使用 nginx

我们需要一台 nginx 服务器来提供证书并启用 SSL。

将以下配置文件添加到您的 nginx/conf.d 目录中；如果您在 Docker 中使用 nginx，则将其与证书和密钥一起挂载到卷中。

下面的示例分别展示了运行在主机上的 nginx 和运行在 Docker 中的 nginx 的配置文件。

server {
  listen       443 ssl;
  server_name  {SUBDOMAIN}.{PROJECT_NAME}.authgear.cloud;

  ssl_certificate      /path/to/your/cert;
  ssl_certificate_key  /path/to/your/key;

  location / {
    # Change it to your service endpoint
    proxy_pass http://127.0.0.1:3000;
    proxy_set_header Host $host;

    auth_request /_auth;
    auth_request_set $x_authgear_session_valid $upstream_http_x_authgear_session_valid;
    auth_request_set $x_authgear_user_id $upstream_http_x_authgear_user_id;
    auth_request_set $x_authgear_user_anonymous $upstream_http_x_authgear_user_anonymous;
    auth_request_set $x_authgear_user_verified $upstream_http_x_authgear_user_verified;
    auth_request_set $x_authgear_session_acr $upstream_http_x_authgear_session_acr;
    auth_request_set $x_authgear_session_amr $upstream_http_x_authgear_session_amr;
    auth_request_set $x_authgear_session_authenticated_at $upstream_http_x_authgear_session_authenticated_at;
    auth_request_set $x_authgear_user_can_reauthenticate $upstream_http_x_authgear_user_can_reauthenticate;

    proxy_set_header x-authgear-session-valid $x_authgear_session_valid;
    proxy_set_header x-authgear-user-id $x_authgear_user_id;
    proxy_set_header x-authgear-user-anonymous $x_authgear_user_anonymous;
    proxy_set_header x-authgear-user-verified $x_authgear_user_verified;
    proxy_set_header x-authgear-session-acr $x_authgear_session_acr;
    proxy_set_header x-authgear-session-amr $x_authgear_session_amr;
    proxy_set_header x-authgear-session-authenticated-at $x_authgear_session_authenticated_at;
    proxy_set_header x-authgear-user-can-reauthenticate $x_authgear_user_can_reauthenticate;
  }

  location /_auth {
    internal;
    resolver 8.8.8.8;
    set $resolver https://{PROJECT_NAME}.authgear.cloud/_resolver/resolve;
    proxy_pass $resolver;
    proxy_pass_request_body off;
    proxy_set_header Content-Length "";
  }
}

说明

Docker Desktop 不支持 host 网络驱动，必须使用 bridge 网络。如果您在 Docker 中的 nginx 需要将请求代理到主机网络中的服务，需要通过 127.0.0.11 解析 host.docker.internal。如果您的服务也在同一个 Docker 桥接网络中（即同一个 docker-compose 且未指定多个网络），目标域名将是容器名称。

server {
  listen       443 ssl;
  server_name  {SUBDOMAIN}.{PROJECT_NAME}.authgear.cloud;

  ssl_certificate      /path/to/your/cert;
  ssl_certificate_key  /path/to/your/key;

  location / {
    resolver 127.0.0.11;
    # change {CONTAINER_NAME} to host.docker.internal if accessing host
    proxy_pass http://{CONTAINER_NAME}:{PORT};
    proxy_set_header Host $host;

    auth_request /_auth;
    auth_request_set $x_authgear_session_valid $upstream_http_x_authgear_session_valid;
    auth_request_set $x_authgear_user_id $upstream_http_x_authgear_user_id;
    auth_request_set $x_authgear_user_anonymous $upstream_http_x_authgear_user_anonymous;
    auth_request_set $x_authgear_user_verified $upstream_http_x_authgear_user_verified;
    auth_request_set $x_authgear_session_acr $upstream_http_x_authgear_session_acr;
    auth_request_set $x_authgear_session_amr $upstream_http_x_authgear_session_amr;
    auth_request_set $x_authgear_session_authenticated_at $upstream_http_x_authgear_session_authenticated_at;
    auth_request_set $x_authgear_user_can_reauthenticate $upstream_http_x_authgear_user_can_reauthenticate;

    proxy_set_header x-authgear-session-valid $x_authgear_session_valid;
    proxy_set_header x-authgear-user-id $x_authgear_user_id;
    proxy_set_header x-authgear-user-anonymous $x_authgear_user_anonymous;
    proxy_set_header x-authgear-user-verified $x_authgear_user_verified;
    proxy_set_header x-authgear-session-acr $x_authgear_session_acr;
    proxy_set_header x-authgear-session-amr $x_authgear_session_amr;
    proxy_set_header x-authgear-session-authenticated-at $x_authgear_session_authenticated_at;
    proxy_set_header x-authgear-user-can-reauthenticate $x_authgear_user_can_reauthenticate;
  }

  location /_auth {
    internal;
    resolver 8.8.8.8;
    set $resolver https://{PROJECT_NAME}.authgear.cloud/_resolver/resolve;
    proxy_pass $resolver;
    proxy_pass_request_body off;
    proxy_set_header Content-Length "";
  }
}

在上面的示例中，nginx 还会通过向 Authany 内部端点发起子请求来验证请求。您可以在这里了解更多信息。

完成

现在通过 https://<yourapp>.authgear.cloud 访问网站，浏览器就能携带身份验证 Cookie 发送请求了。

如需在网站中实现登录和登出逻辑，请参阅 Web SDK。