本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 为您的门户配置自定义域
您可以为 WorkSpaces 安全浏览器门户配置自定义域，以允许通过自己的域名而不是默认的门户 URL 进行访问。此功能允许您使用与贵组织品牌相一致的域名为用户提供更加集成的体验。
**概述**
自定义域名允许您对用户体验的以下方面进行个性化设置：
+ **品牌门户访问**-用户通过您组织的域而不是默认 AWS 终端节点访问您的门户。
+ **一致的用户体验**-使用与您的组织一致的熟悉域名，保持品牌一致性。
**注意**
要自定义门户的视觉外观和品牌元素，请参阅[Amazon WorkSpaces 安全浏览器中的品牌定制](branding-customization.md)。
**Topics**
+ [为您的门户配置自定义域](configure-custom-domains.md)
+ [自定义域名问题疑难解答](custom-domains-troubleshooting.md)
# 为您的门户配置自定义域
## 工作原理
配置自定义域名时：
+ 您可以使用自定义域创建和配置反向代理，以将流量路由到门户终端节点。
+ 用户通过您的自定义域而不是默认的门户终端节点访问您的门户。
+ SSL 证书可确保整个过程的安全连接。
## 先决条件
在设置自定义域名之前，请确保您已经：
+ 您通过 DNS 服务提供商（例如 Amazon Route53）管理的域名。
+ WorkSpaces 安全浏览器门户。有关创建门户的更多信息，请参阅[为 Amazon WorkSpaces 安全浏览器创建门户](getting-started-step1.md)。
+ 确保您拥有管理 AWS Certifice Manager 和 DNS 配置所需的权限。 CloudFront
**重要**
用户必须在其浏览器中为自定义域启用第三方 Cookie，以确保门户网站功能正常。
确保您拥有并正确管理自定义域及其 DNS 记录，以维护门户的安全性和功能。
**注意**
要为自定义域启用单点登录扩展程序，用户必须在其浏览器中安装版本高于 1.0.2505.6608 的扩展程序。
当用户登录门户时，系统会提示他们安装扩展。有关该扩展的用户体验的详细信息，请参阅[Amazon WorkSpaces 安全浏览器的单点登录扩展程序](extension.md)。
## 开始使用
在创建新门户或编辑现有门户时，您可以将自定义域配置为门户设置属性。这可以使用 AWS 控制台、SDK CloudFormation 或 AWS CLI 命令来完成。
我们建议将 Amazon CloudFront 分配设置为反向代理，将来自您的自定义域的流量路由到 WorkSpaces 安全浏览器门户终端节点。
**注意**
尽管建议 CloudFront 将 Amazon 作为反向代理解决方案，但您可以使用其他反向代理配置。确保您满足 Amazon 设置步骤中详述的所需来源和缓存配置 CloudFront 设置。
## 设置 CloudFront 为反向代理
要完成反向代理的设置，您需要：
+ 通过 AWS Certificate Manager (ACM) 获得 SSL 证书
+ 亚马逊 CloudFront 配送
+ DNS 记录
+ 使用您的自定义域名配置的门户
**SSL 证书**
如果您还没有，请按照以下步骤通过 ACM 申请一个：
1. 导航到 ACM 控制台，网址为。[https://console.aws.amazon.com/acm](https://console.aws.amazon.com/acm)
**重要**
使用美国东部（弗吉尼亚北部）区域，因为 CloudFront 需要将证书存储在那里。
1. 申请证书：
+ 对于新 ACM 用户：在 “**配置**证书” 下选择 “**开始**”
+ 对于现有 ACM 用户：选择**申请证书**
1. 选择 “**申请公共证书**”，然后选择 “**申请证书**”。
**注意**
您也可以导入现有证书。有关更多信息，请参阅《[ACM 用户指南》中的将证书导入](https://docs.aws.amazon.com/acm/latest/userguide/import-certificate.html) *ACM*。
1. 输入您的主域名（例如，**myportal.example.com**）。
1. 选择验证方法：
+ **DNS 验证**（建议对 Route 53 用户使用）-允许在您的托管区域中自动创建记录集。有关更多信息，请参阅《*ACM 用户指南》*中的 [DNS 验证](https://docs.aws.amazon.com/acm/latest/userguide/gs-acm-validate-dns.html)。
+ **电子邮件验证**-有关更多信息，请参阅《*ACM 用户指南*》中的[电子邮件验证](https://docs.aws.amazon.com/acm/latest/userguide/gs-acm-validate-email.html)。
1. 查看您的设置，然后选择**确认并申请**。
**CloudFront 分配**
为从您的自定义域到门户终端节点的代理请求创建 CloudFront 分配。
1. 导航到 CloudFront 控制台，网址为[https://console.aws.amazon.com/cloudfront](https://console.aws.amazon.com/cloudfront)。
1. 选择 **Create Distribution**（创建分配）。
+ **分发名称**：输入分配的名称
+ **分发类型**：单个网站或应用程序
**注意**
如果您的自定义域名在 Route 53 中使用同一 AWS 账户进行管理，则 CloudFront 可以自动为您管理您的 DNS。输入您的自定义域名，然后单击 “检查域名”。如果您有来自其他 DNS 提供商的域名，请跳过此步骤，稍后再配置您的域名。
1. 配置起源设置：
+ **产地类型**：其他
+ **自定义来源**：输入门户端点 ** .workspaces-web.com
+ **原始路径**：留空（默认）
1. 自定义起源设置：
+ 添加自定义标头
**重要**
只有在代理请求中存在此标头时，才能通过自定义域进行门户访问。确保标头名称和值的指定完全如上所述。
+ **标题名称**： workspacessecurebrowser-custom-domain
+ **值**：您的自定义域名（例如，**myportal.example.com**）
+ **协议**：仅限 HTTPS
+ **HTTPS 端口**：443（保持默认值）
+ **原始 SSL 协议的最低要求**： TLSv1.2（默认）
+ **来源 IP 地址类型**： IPv4 仅限（在撰写本管理指南 IPv6 时，亚马逊 WorkSpaces 安全浏览器尚不支持。）
1. 自定义缓存设置：
+ **查看器协议策略**：将 HTTP 重定向到 HTTPS
+ **允许的 HTTP 方法**：GET、HEAD、OPTIONS、PUT、POST、PATCH
+ **缓存策略**： CachingDisabled
+ **起源请求政策**： AllViewerExceptHostHeader
**重要**
只有将原始请求策略设置为，才能通过自定义域进行门户访问 AllViewerExceptHostHeader。顾名思义，此策略仅从请求标头中过滤掉主机标头，并将所有剩余的标头传递给源。
1. 您可以根据需要配置 WAF，但对于此设置而言，这不是必需的。
1. 在获取 TLS 证书中，选择在步骤 1 中创建的 TLS 证书。
1. 查看设置并选择 “**创建分发**”。
**DNS 记录**
如果您的托管区域位于同一 AWS 账户中，Cloudfront 可以更新您在 Route 53 中的 DNS 记录，将来自指定域的流量路由到步骤 2 中创建的分配。
1. 导航到 CloudFront 设置
1. 点击 “将域名路由至 CloudFront”
1. 单击 “自动设置路由”
如果您已在其他服务提供商或其他 AWS 账户中为自定义域配置了 DNS，请将您的 DNS 提供商配置为将您的域的流量路由到分配。以下步骤描述了如何使用 Route 53 执行此操作。
1. 打开亚马逊 Route 53 控制台，网址为[https://console.aws.amazon.com/route53](https://console.aws.amazon.com/route53)。
1. 访问 DNS 管理：
+ 如果您不熟悉通过此 AWS 账户使用 Route 53，则会打开亚马逊 Route 53 概述页面。在 DNS 管理下，选择**立即开始**。
+ 如果您之前使用过此 AWS 账户 Route 53，请继续下一步。
1. 在导航窗格中，选择 **Hosted zones（托管区域）**。
1. 如果您还没有托管区域，请创建一个托管区域：
+ 要将互联网流量路由到您的资源，请参阅 *Amazon Route 53 开发者指南*中的[创建公共托管区域](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/CreatingHostedZone.html)。
+ 要在您的 VPC 中路由流量，请参阅 *Amazon Route 53 开发者指南*中的[创建私有托管区域](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/hosted-zone-private-creating.html)。
1. 在**托管区域**页面上，选择要管理的托管区域的名称。
1. 请选择 **Create Record Set**。
1. 为您的域名创建一个条目（例如，**myportal.example.com**）：
+ **类型**：A — IPv4 地址
+ **别名**：是
+ **别名目标**： CloudFront 分发 URL
将所有其他设置保留为默认值。
**注意**
如果您没有使用 Route 53 来管理您的域名的 DNS，请使用您的 DNS 服务提供商，并将指向您的域的 DNS 条目添加到 CloudFront 分配的 URL 中。
**或者，您可以使用以下 CloudFormation 模板来创建 CloudFront 分配：**
此 CloudFormation 模板会自动创建 CloudFront 分发、配置反向代理设置，并可选择创建 Route53 DNS 记录：
**Example workspaces-web-custom-domain-template.yaml**
```
AWSTemplateFormatVersion: '2010-09-09'
Description: 'CloudFront Distribution for custom domain configuration with existing AWS WorkSpaces Secure Browser Portal'
Parameters:
PortalEndpoint:
Type: String
Description: 'The endpoint of your existing WorkSpaces Web Portal (e.g., abc123.workspaces-web.com)'
AllowedPattern: '^[a-zA-Z0-9-]+(\.[a-zA-Z0-9-]+)?\.workspaces-web\.com$'
ConstraintDescription: 'Must be a valid WorkSpaces Web portal endpoint'
CustomDomainName:
Type: String
Description: 'Custom domain name for the portal (e.g., myportal.example.com)'
AllowedPattern: '^([a-zA-Z0-9]?((?!-)([A-Za-z0-9-]*[A-Za-z0-9])\.)+[a-zA-Z0-9]+)$'
ConstraintDescription: 'Must be a valid domain name'
CertificateArn:
Type: String
Description: 'ARN of the validated SSL certificate in ACM (must be in us-east-1 region for CloudFront)'
AllowedPattern: 'arn:aws:acm:us-east-1:[0-9]{12}:certificate/[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}'
ConstraintDescription: 'Must be a valid ACM certificate ARN in us-east-1 region'
CreateRoute53Record:
Type: String
Description: 'Create Route53 record for custom domain (requires existing hosted zone)'
Default: 'No'
AllowedValues:
- 'Yes'
- 'No'
HostedZoneId:
Type: String
Description: 'Route53 Hosted Zone ID for the custom domain (required if creating Route53 record)'
Default: ''
Conditions:
ShouldCreateRoute53Record: !And
- !Equals [!Ref CreateRoute53Record, 'Yes']
- !Not [!Equals [!Ref HostedZoneId, '']]
Resources:
# CloudFront Distribution
CloudFrontDistribution:
Type: AWS::CloudFront::Distribution
Properties:
DistributionConfig:
Aliases:
- !Ref CustomDomainName
Comment: !Sub 'CloudFront distribution for WorkSpaces Web Portal - ${CustomDomainName}'
Enabled: true
HttpVersion: http2
IPV6Enabled: false # WorkSpaces Secure Browser does not support IPv6
PriceClass: PriceClass_All
# Origin Configuration
Origins:
- Id: WorkSpacesWebOrigin
DomainName: !Ref PortalEndpoint
CustomOriginConfig:
HTTPSPort: 443
OriginProtocolPolicy: https-only
OriginSSLProtocols:
- TLSv1.2
OriginCustomHeaders:
- HeaderName: workspacessecurebrowser-custom-domain
HeaderValue: !Ref CustomDomainName
# Default Cache Behavior
DefaultCacheBehavior:
TargetOriginId: WorkSpacesWebOrigin
ViewerProtocolPolicy: https-only
AllowedMethods:
- GET
- HEAD
- OPTIONS
- PUT
- POST
- PATCH
- DELETE
Compress: false
# Cache Policy: CachingDisabled (using predefined managed policy)
CachePolicyId: 4135ea2d-6df8-44a3-9df3-4b5a84be39ad
# Origin Request Policy: AllViewerExceptHostHeader (using predefined managed policy)
OriginRequestPolicyId: b689b0a8-53d0-40ab-baf2-68738e2966ac
# SSL Configuration
ViewerCertificate:
AcmCertificateArn: !Ref CertificateArn
SslSupportMethod: sni-only
MinimumProtocolVersion: TLSv1.2_2021
Tags:
- Key: Name
Value: !Sub '${AWS::StackName}-cloudfront'
# Route 53 Record (optional - requires hosted zone to exist)
Route53Record:
Type: AWS::Route53::RecordSet
Condition: ShouldCreateRoute53Record
Properties:
HostedZoneId: !Ref HostedZoneId
Name: !Ref CustomDomainName
Type: A
AliasTarget:
DNSName: !GetAtt CloudFrontDistribution.DomainName
HostedZoneId: Z2FDTNDATAQYW2 # CloudFront Hosted Zone ID
EvaluateTargetHealth: false
Outputs:
PortalEndpoint:
Description: 'WorkSpaces Web Portal endpoint used as origin'
Value: !Ref PortalEndpoint
Export:
Name: !Sub '${AWS::StackName}-PortalEndpoint'
CustomDomainEndpoint:
Description: 'Custom domain endpoint for the portal'
Value: !Sub 'https://${CustomDomainName}'
Export:
Name: !Sub '${AWS::StackName}-CustomDomainEndpoint'
CloudFrontDistributionId:
Description: 'CloudFront Distribution ID'
Value: !Ref CloudFrontDistribution
Export:
Name: !Sub '${AWS::StackName}-CloudFrontDistributionId'
CloudFrontDomainName:
Description: 'CloudFront Distribution Domain Name'
Value: !GetAtt CloudFrontDistribution.DomainName
Export:
Name: !Sub '${AWS::StackName}-CloudFrontDomainName'
CertificateArn:
Description: 'SSL Certificate ARN used by CloudFront'
Value: !Ref CertificateArn
Export:
Name: !Sub '${AWS::StackName}-CertificateArn'
Metadata:
AWS::CloudFormation::Interface:
ParameterGroups:
- Label:
default: "Existing Portal Configuration"
Parameters:
- PortalEndpoint
- Label:
default: "Custom Domain Configuration"
Parameters:
- CustomDomainName
- CertificateArn
- CreateRoute53Record
- HostedZoneId
ParameterLabels:
PortalEndpoint:
default: "Portal Endpoint"
CustomDomainName:
default: "Custom Domain Name"
CertificateArn:
default: "SSL Certificate ARN"
CreateRoute53Record:
default: "Create Route53 Record"
HostedZoneId:
default: "Hosted Zone ID"
```
要使用此模板，请执行以下操作：
1. 将上面的模板另存为 `workspaces-web-custom-domain-template.yaml`
1. 使用 AWS 控制台、 AWS CLI 或 AWS SDK 以及您的特定参数值进行部署
1. 部署完成后，使用自定义域配置您的门户，如以下步骤 4 所述
**门户配置**
使用 AWS 控制台、 UpdatePortal API 或 update-portal AWS CLI 命令将您的自定义域注册为门户设置属性。
1. 打开 WorkSpaces 安全浏览器控制台，网址为[https://console.aws.amazon.com/workspaces-web/home](https://console.aws.amazon.com/workspaces-web/home)。
1. 在导航窗格中，选择 **Web 门户**。
1. 选择要配置的 Web 门户，然后选择**编辑**。
1. 在门户设置中，添加您的自定义域名。
1. 保存门户配置。
**测试您的配置**
要测试您的配置，请执行以下步骤：
1. 打开 Web 浏览器并导航到您的自定义域名的 URL（例如**https://myportal.example.com**）。
1. 如果一切设置正确，您应该会看到门户的登录页面。
1. 接下来，在浏览器中输入门户 URL，您应该在登录 IdP 后被重定向到自定义域。
1. 最后，登录您的 IdP，然后单击门户的应用程序图块。您应该被重定向到自定义域。
# 自定义域名问题疑难解答
如果用户在远程浏览器会话中遇到通过自定义域访问门户的问题，请使用以下故障排除步骤来识别和解决常见问题。
**Topics**
+ [常见错误消息](common-errors.md)
# 常见错误消息
以下是设置自定义域名时的常见错误消息及其解决方法：
## CSRF 令牌无效错误
当安全浏览器未通过 CloudFront 设置正确接收您的请求时，就会发生此错误。
要解决此问题，请执行以下操作：
+ 检查您的 CloudFront 分配中的自定义来源设置。
+ 验证自定义标头的名称是否完全匹配`workspacessecurebrowser-custom-domain`且值与您的自定义域名完全匹配（没有 https://或任何查询参数）。
+ 清除本地浏览器上的缓存。
+ 使缓存失效。 CloudFront
## 502 错误的网关错误
此错误通常表示存在缓存配置问题。
要解决此问题，请执行以下操作：
+ 检查 CloudFront 分配的缓存设置。
+ 确认缓存策略已设置为`CachingDisabled`。
+ 确认 Origin 请求策略已设置为`AllViewerExceptHostHeader`。
+ 清除本地浏览器上的缓存。
+ 使缓存失效。 CloudFront
## “访问被拒绝” 错误
如果您的自定义域名配置不正确，则可能会出现此错误。
要解决此问题，请执行以下操作：
+ 检查您的 CloudFront 配送中的来源设置。
+ 验证源是否设置为正确的门户 URL。
+ 确认门户配置了正确的自定义域。
+ 清除本地浏览器上的缓存。
+ 使缓存失效。 CloudFront