为 API BaaS 配置 TLS

Edge for Private Cloud v4.18.01

TLS（传输层安全协议，其前身是 SSL）是一种标准安全技术，用于确保在您的 API 环境中进行安全加密的消息传递。您可以在 API BaaS 门户和 API BaaS 堆栈节点上配置 TLS。

下图显示了包含一个 BaaS 门户节点和三个 API BaaS 堆栈节点的 API BaaS 的典型部署图。

开发者使用浏览器向门户发出请求。默认情况下，这些请求在门户节点的端口 9000 上使用 HTTP 协议。

此部署在门户和堆栈节点之间包含一个负载平衡器。在此配置中，门户会向负载平衡器发出 HTTP 请求，然后负载平衡器会将请求转发到其中一个堆栈节点。这是生产系统推荐的部署环境。

TLS 配置选项

为 API BaaS 配置 TLS 时，您有以下几种选择：

  • 在门户和 Stack 节点的负载平衡器上配置 TLS

    在此配置中，开发者使用 HTTPS 协议访问门户，在浏览器中运行的门户使用 HTTPS 通过负载平衡器向堆栈节点发出请求。负载平衡器使用 HTTP 访问堆栈节点。
  • 在门户、负载平衡器和堆栈节点上配置 TLS

    为提高安全性，请将负载平衡器配置为使用 TLS 访问堆栈节点。
  • 在门户和单个堆栈节点上配置 TLS

    在小型环境（例如测试或开发环境）中，您可能只有一个堆栈节点，这意味着无需添加负载平衡器。在此配置中，您需要在门户和堆栈节点上配置 TLS。
  • 在门户的负载平衡器上配置 TLS

    上方未列出的一个选项是在门户节点前面使用负载平衡器。在该配置中，您可以在负载平衡器上配置 TLS，也可以选择在负载平衡器和门户之间的连接上配置 TLS。

确保 TLS 端口已打开

以下步骤将在默认门户端口 9000 和堆栈节点 8080 上配置 TLS。 不过，您可以根据需要更改此端口。

无论您使用哪个端口，都必须确保该端口在节点上是开放的。例如，您可以使用以下命令打开端口 8443：

$ iptables -A INPUT -m state --state NEW -m tcp -p tcp --dport 8443 -j ACCEPT --verbose

在 API BaaS 堆栈上配置 TLS

默认情况下，系统会为 API BaaS 堆栈停用 TLS。然后，您可以使用堆栈节点的 IP 地址或 DNS 名称和端口 8080，通过 HTTP 访问 BaaS API。例如：

http://stack_IP:8080

或者，您可以配置对 BaaS API 的 TLS 访问，以便通过以下方式对其进行访问：

https://stack_IP:8080

在此示例中，配置 TLS 访问以使用端口 8080。但是，端口 8080 不是必需的，您可以将堆栈配置为使用其他端口。唯一的要求是您的防火墙允许通过指定端口传输流量。

堆栈只能在单个端口上支持一种请求类型（HTTP 或 HTTPS）。因此，如果您在端口 8080 上配置 HTTPS 访问，则无法使用 HTTP 访问端口 8080。如果您将堆栈配置为使用端口 8443 和 HTTPS，则堆栈将不再监听端口 8080。

请按照以下步骤配置对堆栈的 TLS 访问权限：

  1. 生成包含 TLS 证书和私钥的密钥库 JKS 文件。如需了解详情，请参阅为边缘本地配置 TLS/SSL。
    注意：请确保密钥库的密码和密钥的密码相同。
  2. 将密钥库 JKS 文件复制到堆栈节点上的目录，例如 /opt/apigee/customer/application。 该目录必须可供“apigee”用户访问。
  3. 将 JKS 文件的所有权更改为“apigee”用户：
    > chown apigee:apigee /opt/apigee/customer/application/keystore.jks

    ，其中 keystore.jks 是密钥库文件的名称。
  4. 修改 /opt/apigee/customer/application/usergrid.properties 文件以设置以下属性，包括 JKS 文件的路径以及密钥库和密钥上的密码。如果该文件不存在，请创建：
    tomcat-server_scheme=https
    tomcat-server_secure=true
    tomcat-server_ssl.enabled=true
    tomcat-server_keystore.type=JKS
    tomcat-server_keystore.file=/opt/apigee/customer/application/keystore.jks
    tom.



    /opt/apigee/customer/application/keystore.jks
    # 使用此属性指定其他端口。
    # tomcat-server_port=8080

    警告：password 值必须采用明文形式。 因此，您应保护 usergrid.properties 免遭未经授权的访问。

    使用 tomcat-server_keyalias 属性指定密钥库别名。您需要在创建密钥时设置密钥别名。 例如，您可以通过在 keytool 命令中使用 -alias 选项进行设置。

    使用 tomcat-server_ssl.protocols 设置堆栈支持的 TLS 协议。如需查看 Java 8 支持的协议列表，请参阅 http://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#jssename。
  5. 配置堆栈节点：
    > /opt/apigee/apigee-service/bin/apigee-service baas-usergrid configure
  6. 重启 BaaS 堆栈：
    > /opt/apigee/apigee-service/bin/apigee-service baas-usergrid restart
  7. 使用 HTTPS 在堆栈节点上运行以下 c网址 命令，确认 TLS 可以正常运行：
    > curl -k https://localhost:8080/status -v

    如果 TLS 配置正确，您应该会看到包含状态信息的响应。

    如果您通过 8080 以外的端口配置了 TLS 访问，请修改上述命令以使用正确的端口。
  8. 在所有堆栈节点上重复执行上述步骤。
  9. 如果您在堆栈节点前面有负载平衡器，请将负载平衡器配置为通过 HTTPS 向堆栈节点发出请求。如需了解详情，请参阅有关负载平衡器的文档。

    如果门户向堆栈直接发出请求，请按照下一部分中的说明，配置门户以通过 HTTPS 访问堆栈。
  10. 请按照下文“在堆栈或门户上为 TLS 配置 API BaaS 堆栈节点”中的步骤，确保堆栈节点在生成用户响应时具有正确的 TLS 网址。

配置门户以访问 Stack over TLS

在浏览器中运行的 BaaS 门户通过对 BaaS 堆栈进行 API 调用来运行。如果您将 BaaS 堆栈配置为使用 TLS，则还必须将门户配置为通过 HTTPS 进行这些调用。

API BaaS 安装通常配置为：

  • 在门户和堆栈节点之间使用负载平衡器

    配置负载平衡器，以通过 HTTPS 向堆栈节点发出请求。如需了解详情，请参阅有关负载平衡器的文档。

    在此配置中，门户可以通过 HTTP 或 HTTPS 访问负载平衡器，具体取决于您配置负载平衡器的方式。如果负载平衡器使用 TLS，请按照以下过程配置门户，以向 HTTPS 的负载平衡器发出请求。
  • 让门户向堆栈直接发出请求

    如下所述，将门户配置为通过 HTTPS 访问堆栈。

请按照以下步骤配置 API BaaS 门户，以通过 HTTPS 进行 API 调用：

  1. 如上所述，在 BaaS 栈上配置 TLS 访问权限，或如您的负载平衡器文档中所述，在栈节点的负载平衡器上配置 TLS 访问。
  2. 修改 /opt/apigee/customer/application/portal.properties，以设置以下属性。如果该文件不存在，请创建：
    baas.portal.config.overrideUrl=https://stackIP:port

    将此属性的值指定为单个节点的 API 堆栈节点的 IP 地址或 DNS 名称和端口；如果您在 API BaaS 堆栈节点前面有负载平衡器，则指定为负载平衡器的 IP 地址或 DNS 端口。
  3. 配置门户节点：
    > /opt/apigee/apigee-service/bin/apigee-service baas-portal 配置
  4. 使用以下命令重启门户：
    > /opt/apigee/apigee-service/bin/apigee-service baas-portal restart
  5. 如果您在配置对上方堆栈的 TLS 访问时使用了自签名证书，您的浏览器可能不允许从门户向堆栈发送请求。如果您在浏览器中看到不允许通过 HTTPS 访问堆栈的错误，请在浏览器中请求以下网址，并添加安全异常以允许访问：
    https://stackIP:port/status

    指定 API 堆栈节点或负载平衡器的 IP 地址或 DNS 名称和端口。

在 API BaaS 门户上配置 TLS

默认情况下，用户通过门户服务器上的端口 9000 发出未加密的 HTTP 请求来访问门户。您可以将门户配置为使用 HTTPS 对发送到和从该门户发送的数据进行加密。

默认情况下，您可以使用门户节点的 IP 地址或 DNS 名称和端口 9000 通过 HTTP 访问门户。例如：

http://portal_IP:9000

或者，您也可以配置对门户的 TLS 访问，以便能够以如下形式对其进行访问：

https://portal_IP:9443

在此示例中，配置 TLS 访问以使用端口 9443。但是，端口 9443 不是必需的，您可以将门户配置为使用其他端口。

门户通过单个端口仅支持一种请求类型（HTTP 或 HTTPS）。因此，如果您在端口 9000 上配置 HTTPS 访问，则无法使用 HTTP 访问端口 9000。如果您将门户配置为使用端口 9443 和 HTTPS，则门户将不再监听端口 9000。

如需为门户配置 TLS，请执行以下操作：

  1. 创建 PEM 格式的密钥文件和证书文件。
    注意：请确保密钥或证书上没有密码/密码。
  2. 将 PEM 文件复制到门户节点上的目录，例如 /opt/apigee/customer/application。该目录必须可供“apigee”用户访问。
  3. 将 PEM 文件的所有权更改为“apigee”用户：
    > chown apigee:apigee /opt/apigee/customer/application/*.PEM
  4. 修改 /opt/apigee/customer/application/portal.properties 文件，以设置以下属性。如果该文件不存在，请创建：
    baas.portal.ssl=on
    baas.portal.ssl.certificate=/opt/apigee/customer/application/defaultcert.pem
    baas.portal.ssl.key=/opt/apigee/customer/application/defaultkey.pem
    baas.portal.ssl1.protocol.2TLS 访问。使用 TLS0，TLS 端口 1.v1.v2。

    # 使用此属性指定其他端口。
    # baas.portal.listen=9000

    使用 baas.portal.ssl.protocols 设置门户支持的 TLS 协议。如需查看支持的协议的列表，请参阅 Nginx 定义的 SSL 协议名称列表：http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_protocols。
  5. 配置门户节点：
    > /opt/apigee/apigee-service/bin/apigee-service baas-portal 配置
  6. 重启门户：
    > /opt/apigee/apigee-service/bin/apigee-service baas-portal restart
  7. 请按照下文“在堆栈或门户上为 TLS 配置 API BaaS 堆栈节点”中的步骤，确保堆栈节点具有正确的门户 TLS 网址。

在堆栈或门户上为 TLS 配置 API BaaS 节点

如果您在 Stack 或 Portal 节点前添加负载平衡器，或者直接在门户或堆栈节点上启用 TLS，则必须使用正确的网址配置节点才能访问堆栈和门户。例如，在以下情况下，堆栈节点需要此信息：

  • 在 BaaS API 请求的响应中包含网址。
  • 重置密码或发送其他通知时，在电子邮件模板中添加链接。
  • 将用户重定向到特定门户页面。

如果您在堆栈节点前使用负载平衡器，或在堆栈节点上配置 TLS，请在 /opt/apigee/customer/application/usergrid.properties 设置以下属性：

usergrid-deployment_usergrid.api.url.base=http://localhost:8080

将 http://localhost:8080 替换为负载平衡器的网址。如果负载平衡器配置为使用 TLS，请使用 HTTPS 协议。只有在使用非标准端口（即 HTTP 的端口 80 和 HTTPS 的端口 443）时，才需要包含端口。

如果您在堆栈节点前使用负载平衡器，还必须在 /opt/apigee/customer/application/portal.properties 设置以下属性：

baas.portal.config.overrideUrl=http://localhost:8080

将 http://localhost:8080 替换为堆栈的负载平衡器的网址。

如果您在门户节点之前使用负载平衡器，或在堆栈节点上配置 TLS，请在 usergrid.properties 中设置以下属性：

usergrid-deployment_portal.url=http://localhost:9000

将 http://localhost:9000 替换为负载平衡器的网址。如果负载平衡器配置为使用 TLS，请使用 HTTPS 协议。只有在使用非标准端口（即 HTTP 的端口 80 和 HTTPS 的端口 443）时，才需要包含端口。

修改 usergrid.properties 后：

  1. 配置堆栈节点：
    > /opt/apigee/apigee-service/bin/apigee-service baas-usergrid configure
  2. 重启 BaaS 堆栈：
    > /opt/apigee/apigee-service/bin/apigee-service baas-usergrid restart
  3. 如果您修改了 portal.properties，请配置门户节点：??
    > /opt/apigee/apigee-service/bin/apigee-service baas-portal 配置
  4. 重启 BaaS 门户：
    > /opt/apigee/apigee-service/bin/apigee-service baas-portal restart