为 API BaaS 配置 TLS

适用于私有云的 Edge v. 4.16.09

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

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

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

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

TLS 配置选项

为 API BaaS 配置 TLS 时，您有多个选项：

  • 在门户和堆栈节点的负载平衡器上配置 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 访问权限，以便以以下形式访问该 API：

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
    tomcat-server_keystore.password=password
    tomcat-server_keyalias=keystore_alias
    tomcat-server_clientauth.enabled=false
    tomcat-server_ssl.protocols=TLSv1,TLSv1.1,TLSv1.2
    # By default, TLS access uses port 8080.
    # Use this property to specify a different port.
    # 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. 配置 Stack 节点：
    > /opt/apigee/apigee-service/bin/apigee-service baas-usergrid configure
  6. 将更改部署到 Tomcat：
    > /opt/apigee/apigee-service/bin/apigee-service baas-usergrid deploy
  7. 重启 BaaS 堆栈：
    > /opt/apigee/apigee-service/bin/apigee-service baas-usergrid restart
  8. 使用 HTTPS 在堆栈节点上运行以下 c网址 命令，确认 TLS 是否正常运行：
    > curl -k https://localhost:8080/status -v

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

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

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

配置门户以通过 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 configure
  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.ssl.protocols=TLSv1 TLSv1.1 TLSv1.2
    # By default, TLS access uses port 9000.
    # Use this property to specify a different port.
    # 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 configure
  6. 部署配置：
    > /opt/apigee/apigee-service/bin/apigee-service baas-portal deploy
  7. 重启门户：
    > /opt/apigee/apigee-service/bin/apigee-service baas-portal restart
  8. 请按照“为堆栈或门户上的 TLS 配置 API BaaS 栈节点”中的流程，确保栈节点具有门户的正确 TLS 网址。

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

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

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

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

usergrid-deployment_swagger.basepath=http://localhost:8080
usergrid-deployment_usergrid.organization.activation.url=http://localhost:8080/management/organizations/%s/activate
usergrid-deployment_usergrid.admin.activation.url=http://localhost:8080/management/users/%s/activate
usergrid-deployment_usergrid.admin.resetpw.url=http://localhost:8080/management/users/%s/resetpw
usergrid-deployment_usergrid.admin.confirmation.url=http://localhost:8080/management/users/%s/confirm
usergrid-deployment_usergrid.user.activation.url=http://localhost:8080/%s/%s/users/%s/activate
usergrid-deployment_usergrid.user.confirmation.url=http://localhost:8080/%s/%s/users/%s/confirm
usergrid-deployment_usergrid.user.resetpw.url=http://localhost:8080/%s/%s/users/%s/resetpw

将 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_usergrid.view.management.organizations.organization.activate=http://localhost:9000
usergrid-deployment_usergrid.view.management.organizations.organization.confirm=http://localhost:9000
usergrid-deployment_usergrid.view.management.users.user.activate=http://localhost:9000
usergrid-deployment_usergrid.view.management.users.user.confirm=http://localhost:9000

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

修改 usergrid.properties 后：

  1. 配置 Stack 节点：
    > /opt/apigee/apigee-service/bin/apigee-service baas-usergrid configure
  2. 将更改部署到 Tomcat：
    > /opt/apigee/apigee-service/bin/apigee-service baas-usergrid deploy
  3. 重启 BaaS 堆栈：
    > /opt/apigee/apigee-service/bin/apigee-service baas-usergrid restart
  4. 如果您修改了 portal.properties，请配置门户节点：
    > /opt/apigee/apigee-service/bin/apigee-service baas-portal configure
  5. 部署更改：
    > /opt/apigee/apigee-service/bin/apigee-service baas-portal deploy
  6. 重启 BaaS 门户：
    > /opt/apigee/apigee-service/bin/apigee-service baas-portal restart