跳到主要内容

Protected App — 非 SDK 认证 (Authentication) 集成

Protected App 旨在通过将认证 (Authentication)层与应用程序分离，消除SDK 集成的复杂性。我们负责认证 (Authentication)，让你专注于核心功能。一旦用户通过认证 (Authentication)，Protected App 就会从你的服务器提供内容。

Protected App 的工作原理​

Protected App 由 Cloudflare 提供支持，在全球边缘网络上运行，确保你的应用低延迟和高可用性。

Protected App 会维护会话状态和用户信息。如果用户未通过认证 (Authentication)，Protected App 会将其重定向到登录页面。认证 (Authentication) 成功后，Protected App 会将用户请求附带认证 (Authentication) 和用户信息后转发到源服务器。

此过程可通过以下流程图进行可视化：

保护你的源服务器​

源服务器可以是物理或虚拟设备，不属于 Logto 的 Protected App，存放你的应用内容。类似于内容分发网络 (CDN) 服务器，Protected App 管理认证 (Authentication) 流程并从你的源服务器获取内容。因此，如果用户可以直接访问你的源服务器，就能绕过认证 (Authentication)，你的应用将不再受保护。

因此，保护源服务器连接非常重要，这可以防止攻击者在未认证 (Authentication) 的情况下发现并访问你的源服务器。常见的做法有：

  1. HTTP 头验证
  2. JSON Web Token (JWT) 验证

HTTP 头验证​

你可以使用 HTTP 基本认证 (Authentication) 来保护你的源服务器。

每个来自 Protected App 的请求都会包含如下头部：

Authorization: Basic base64(appId:appSecret)

通过验证该头部，你可以确认请求来自 Protected App，并拒绝所有未包含该头部的请求。

如果你使用 Nginx 或 Apache，可以参考以下指南在源服务器上实现 HTTP 基本认证 (Authentication)：

  1. Nginx: 配置 HTTP 基本认证 (Authentication)
  2. Apache: 认证 (Authentication) 与授权 (Authorization)

如需在应用中检查头部，可参考 Cloudflare 提供的 HTTP Basic Authentication 示例，了解如何使用 HTTP Basic 方案限制访问。

JSON Web Token (JWT) 验证​

另一种保护源服务器的方法是使用 JSON Web Token (JWT)。

每个通过认证 (Authentication) 的 Protected App 请求都会包含如下头部：

Logto-ID-Token: <JWT>

该 JWT 被称为 ID 令牌 (ID Token)，由 Logto 签名并包含用户信息。通过验证该 JWT，你可以确认请求来自 Protected App，并拒绝所有未包含该头部的请求。

该令牌以 JWS 令牌的形式加密和签名。

验证步骤如下：

  1. 验证 JWT
  2. 验证 JWS 签名
  3. 令牌的发行者 (Issuer) 是 https://<your-logto-domain>/oidc（由你的 Logto 认证 (Authentication) 服务器签发）
const express = require('express');
const jwksClient = require('jwks-rsa');
const jwt = require('jsonwebtoken');

const ISSUER = 'https://<your-logto-domain>/oidc';
const CERTS_URL = 'https://<your-logto-domain>/oidc/jwks';

const client = jwksClient({
  jwksUri: CERTS_URL,
});

const getKey = (header, callback) => {
  client.getSigningKey(header.kid, function (err, key) {
    callback(err, key?.getPublicKey());
  });
};

const verifyToken = (req, res, next) => {
  const token = req.headers['Logto-ID-Token'];

  // 确保传入请求包含我们的令牌头部
  if (!token) {
    return res.status(403).send({ status: false, message: '缺少必要的 Logto-ID-Token 头部' });
  }

  jwt.verify(token, getKey, { issuer: ISSUER }, (err, decoded) => {
    if (err) {
      return res.status(403).send({ status: false, message: '无效的 ID 令牌' });
    }

    req.user = decoded;
    next();
  });
};

const app = express();

app.use(verifyToken);

app.get('/', (req, res) => {
  res.send('Hello World!');
});

app.listen(3000);

获取认证 (Authentication) 状态和用户信息​

如果你需要获取应用的认证 (Authentication) 和用户信息，也可以使用 Logto-ID-Token 头部。

如果你只想解码令牌，可以使用如下代码：

const express = require('express');

const decodeIdToken = (req, res, next) => {
  const token = req.headers['Logto-ID-Token'];

  if (!token) {
    return res.status(403).send({
      status: false,
      message: '缺少必要的 Logto-ID-Token 头部',
    });
  }

  const parts = token.split('.');
  if (parts.length !== 3) {
    throw new Error('无效的 ID 令牌');
  }

  const payload = parts[1];
  const decodedPayload = atob(payload.replace(/-/g, '+').replace(/_/g, '/'));
  const claims = JSON.parse(decodedPayload);

  req.user = claims;
  next();
};

const app = express();

app.use(decodeIdToken);

app.get('/', (req, res) => {
  res.json(req.user);
});

app.listen(3000);

自定义 ID 令牌 (ID Token) 声明 (Claims)​

默认情况下，Logto-ID-Token 头部包含标准 OIDC 声明 (Claims)（如 sub、name 和 email）。如需包含扩展声明 (Claims)（如角色或组织数据），需同时配置以下两项：

  1. 租户开关：在 控制台 > 自定义 JWT > ID 令牌 (ID Token) 启用该声明 (Claim)。
  2. Protected App 权限 (Scopes)：在 Protected App 设置中，于 ID 令牌 (ID Token) 声明 (Claims) > 附加权限 (Scopes) 选择对应权限 (Scope)。

只有在自定义 JWT 启用声明 (Claim) 且 Protected App 选择了对应权限 (Scope) 时，扩展声明 (Claims) 才会包含在转发的 ID 令牌 (ID Token) 中。完整扩展权限 (Scopes) 和声明 (Claims) 列表见 自定义 ID 令牌 (ID Token)。

权限 (Scope)声明 (Claims)
custom_datacustom_data
identitiesidentities, sso_identities
rolesroles
urn:logto:scope:organizationsorganizations, organization_data
urn:logto:scope:organization_rolesorganization_roles

获取原始主机​

如果你需要获取客户端请求的原始主机，可以使用 Logto-Host 或 x-forwarded-host 头部。

自定义认证 (Authentication) 规则​

默认情况下，Protected App 会保护所有路由。如果你需要自定义认证 (Authentication) 规则，可以在控制台设置“自定义认证 (Authentication) 规则”字段。

支持正则表达式，以下为两种场景示例：

  1. 仅保护 /admin 和 /privacy 路由：^/(admin|privacy)/.*
  2. 排除 JPG 图片不做认证 (Authentication)：^(?!.*\.jpg$).*$

本地开发​

Protected App 设计用于与你的源服务器配合使用。如果你的源服务器未公开访问，可以使用 ngrok 或 Cloudflare Tunnels 等工具将本地服务器暴露到互联网。

迁移到 SDK 集成​

Protected App 旨在简化认证 (Authentication) 流程。但如果你希望获得更好的控制和自定义，可以在 Logto 创建新应用 并配置 SDK 集成。为顺利迁移，你可以复用 Protected App 的应用配置。Protected App 实际上是 Logto 中的“传统 Web 应用”，你可以在应用设置中找到 “AppId” 和 “AppSecret”。迁移完成后，可以将 Protected App 从你的应用中移除。

Protected App：几分钟内为你的应用构建认证 (Authentication)，无需编码。

 Protected App 背后的动机

构建认证 (Authentication) 系统的最快方式