Creating an AS2TrustedDomains DNS TXT record to redirect the AppStream 2.0 native client to a third-party identity provider

The AS2TrustedDomains DNS TXT record can only enable the same domain (or subdomains) in which the DNS TXT record is created. In a scenario where you do not own the domain where your IdP resolves, an alternative architecture is required. In this blog, I outline the process to create an AS2TrustedDomains DNS TXT record for URL in third-party IdP domains.

When using a third-party identity provider (IdP), such as AWS IAM Identity Center, Azure Active Directory, or Okta for SAML authentication with AppStream 2.0, you must either create StartURL and TrustedDomain registry keys in Windows, or an AS2TrustedDomains DNS TXT record. Both methods allow you to use the IdP URL with AppStream 2.0 Windows Native Client and connect to the published application upon authentication. If you do not have one these configurations in place, the “Connect” button on the AppStream 2.0 native client is not available. When you create an AS2TrustedDomains DNS TXT record, the StartURL and TrustedDomains registry values are not required to connect to the URL in third-party IdP domain. This is a useful feature for Windows devices not joined to an Active Directory domain.

In the blog, enable your organizational domain for the AppStream 2.0 client with a Route 53 DNS TXT record you walk through creating an AS2TrustedDomains DNS TXT record for your own domains.

In this blog, I outline the process to create an AS2TrustedDomains DNS TXT record for URL in third-party IdP domains using Amazon Route 53, Amazon CloudFront, and AWS Certificate Manager (ACM). This solution uses CloudFront Functions to redirect users from a custom URL in your domain to the IdP URL in the IdP domain. Keep in mind the requirements and considerations for creating DNS TXT records.

Note: If you are using a third-party DNS service instead of Route 53, follow the vendor’s specific documentation to create DNS records.

Overview of the solution

1. You enter the URL https://appstream2saml.example.com/idp in the AppStream 2.0 native client.
2. The AppStream 2.0 native client queries the DNS TXT record in Route 53/DNS for the example.com domain.
3. Route 53 returns the DNS TXT record response for AS2TrustedDomains:AS2TrustedDomains=appstream2saml.example.com
4. The AppStream 2.0 native client queries the A Record for appstream2saml.example.com from Route 53.
5. Route 53 returns one or more IP addresses of the solution’s CloudFront distribution endpoints.
6. The AppStream 2.0 native client sends a GET request to the CloudFront distribution.
7. CloudFront Functions return a 302 Found reply, and redirects to the IdP URL.
8. The AppStream 2.0 native client sends a GET request to the IdP URL.
9. The AppStream 2.0 native client loads the IdP login page.

Prerequisites

• A DNS service provider, which can be a public hosted zone in Route 53, or third-party DNS service for a customer’s second level domain. For example, if a customer organization’s domain is example.net, Route 53 or their third-party DNS service must be configured for the example.net domain. If you want to use Route 53 as your DNS service provider, see Configuring Amazon Route 53 as your DNS service.
• Access to Route 53 or a third-party DNS service console, and permission to create DNS records in that domain.
• Access to CloudFront to create a CloudFront distribution and CloudFront Functions.
• Access to AWS Certificate Manager (ACM) to create and list certificates.
• A resolvable URL from your IdP that accepts SAML authentication requests and has access to your AppStream 2.0 application catalogs.
• A Windows client machine with the AppStream 2.0 native client installed that can resolve the DNS records created in this architecture.

Walkthrough

STEP 1: Create a CloudFront distribution point.

1. Navigate to the CloudFront console.
2. Choose Create distribution.
3. Under Origin, for Origin domain, enter the desired domain FQDN, or httpbin.com. For this blog post, I use the custom origin appstream2saml.example.com.
4. For Protocol, select HTTPS.
5. For Default cache behavior:
   • Viewer > Viewer Protocol Policy > select HTTPS only.
   • Allowed HTTP methods > select GET, HEAD.
   • Cache key and origin requests > Select Cache policy and origin request policy (recommended) > Select CachingDisabled
6. Select Create distribution.

After CloudFront creates the distribution, the Status changes from In Progress to Deployed.

Note the Distribution Id for your deployment, and the distribution domain name (Domain name column) from the list of distributions. You can also find the distribution domain name on the General tab for a selected distribution.

STEP 2: Create a CloudFront Function to redirect the user to an IdP URL

1. Navigate to the CloudFront console.
2. Select Functions. Choose Create function.
3. Enter a function name. Optionally, enter a description. For example, AppStream 2.0 SAML Redirection. Choose Create Function.
4. In the Build tab, copy the following function code, and paste it into the code editor to replace the example. This function code redirects the AppStream 2.0 client from a custom URL in your domain to an external IdP URL.

   function handler(event) 
   {
       var request = event.request;
       var method = request.method;
       var uri = request.uri;
       var host = request.headers.host.value;
       var newurl = 'https://appstreamapps.awsapps.com/start'; // Change the value of newurl to your IDP URL.
       if (method === 'GET' && host === 'appstream2saml.example.com' && uri === '/idp') // Host value should be a URL that your users can resolve in your domain (domain that customer owns). 
       {
           var response = {
                   statusCode: 302,
                   statusDescription: 'Found',
                   headers:
                       { "location": { "value": newurl } }
                   }
               return response;
           }
       return request;
   }

5. In the code, replace newurl value with your IdP URL.
6. In the code, replace host (URL) value with a value for which the AS2TrustedDomain DNS TXT record will be created in the desired domain’s DNS database. This is the URL that you enter in the AppStream 2.0 client. In this example, I’ve added the URI evaluation in the code. Configured this way, users can optionally add /idp at the end of the URL in the AppStream 2.0 client.
7. Choose Save changes to create this CloudFront Function.
8. Choose the Publish tab, then choose Publish Function to publish the CloudFront Function.
9. On the Publish tab in Associated Distributions section, choose Add Association.
10. For Distribution, select the distribution id you created in STEP 1.
11. For Event type, choose Viewer Request.
12. For Cache behavior, choose Default(*).
13. Choose Add Association

To verify the distribution’s status, choose Distributions from the CloudFront console.

STEP 3: (Optional) Making Amazon Route 53 the DNS service for an existing domain

If you are already using Route 53 as the DNS service provider for your domain, and have a public hosted zone created in Route 53 for that domain, go to STEP 4.

If you are using a third-party DNS Service, go to STEP 4.

Alternatively, review making Amazon Route 53 the DNS service for an existing domain

Note: Customers do not have to transfer the domain registration to Route 53; you only have to make Route 53 a DNS service provider for your domain.

STEP 4: Create the AS2TrustedDomains DNS TXT record in the Route 53 public hosted zone

The following steps create the AS2TrustedDomains DNS TXT record in Route 53. If you are using a third-party DNS service, follow the vendor-specific documentation to create this record, and go to STEP 5.

1. Navigate to the Route 53 console.
2. Choose Hosted zones.
3. On the Hosted zones page, choose the name of the hosted zone where you want to create the record. For this blog post, I use example.com public hosted zone.
4. Choose Create record.
5. For Record type, choose TXT.
6. For Value, enter AS2TrustedDomains=appstream2saml.example.com. Replace appstream2saml.example.com with the value that you provided for host (URL) in the function code in STEP 2 Point 4. This value must resolve in your domain.

For more examples of DNS TXT record configuration, see DNS TXT record configuration.

STEP 5: Request a public SSL certificate for your domain using AWS Certificate Manager

Configure an Alternate Domain Name in the CloudFront distribution we created in STEP 1. To add an Alternate Domain Name, you must create and add an SSL/TLS certificate from an authorized certificate authority (CA) that covers the target domain name. Adding the certificate to your distribution validates that you are authorized to use the domain.

1. Navigate to AWS Certificate Manager console.
2. Choose Request certificate.
3. For Certificate type, select Request a public certificate.
4. For Fully qualified domain name, enter the domain name that you specified for AS2TrustedDomains DNS TXT record in STEP 4 Point 6. For this blog post, I use appstream2saml.example.com
5. You can also add another name to the certificate (Subject Alternative Name). For example, if you are requesting a certificate for appstream2saml.example.com, you can add example.com or *.example.com to the certificate.
6. For Validation Method, choose either DNS validation or Email validation. If you can edit your DNS configuration, we recommend that you use DNS domain validation rather than email validation. Refer to DNS validation and email validation documentation for further information.
7. In the Key algorithm section, choose RSA 2048.
8. Optionally, add tags to the certificates.
9. Choose Request.

After the request is processed, you are redirected to your certificate list, where the new certificate is displayed. When requested, a certificate enters Pending validation status. If you don’t see the certificate, select the Refresh button.

STEP 6: Set up DNS validation in the console

For this blog post, I use the DNS Validation method. If you are using a third-party party DNS service and DNS validation method, you must create the records in the DNS database. If you are using Email Validation method, review the documentation for email validation.

1. Navigate to AWS Certificate Manager console.
2. Select List certificate. Choose the Certificate ID of a certificate with status Pending that you requested.
3. In the Domains section, complete one of the following two procedures:
   • Choose Create records in Route 53, then choose Create records. The Certificate status page should open with a status banner reporting Successfully created DNS records. Your new certificate might continue to display a status of Pending validation for up to 30 minutes.
   • If you are not using Route 53 as your DNS provider, you must retrieve the CNAME information and add it your DNS database. On the details page for the new certificate, you can do this in either of two ways:
     • Copy the CNAME components displayed in the Domains section. This information must be added manually to your DNS database.
     • Alternatively, choose Export to CSV. Open the csv file and manually add the records to your DNS database.

If ACM is not able to validate the domain name within 72 hours, ACM changes the certificate status to Validation timed out. The most likely reason for this result is that you did not successfully update your DNS configuration with the value that ACM generated. To remedy this issue, you must request a new certificate after reviewing the CNAME instructions.

STEP 7: Adding an alternate domain name (CNAME) to use a custom URL

In this step, you add an alternate domain name (CNAME) to your CloudFront distribution to use your own domain name.

1. Navigate to the CloudFront console.
2. Choose the ID for the distribution that you created in STEP 1.
3. On the General tab, choose Edit.
4. Update the following values:
   • Alternate Domain Names (CNAMEs): Enter the domain name that you specified for AS2TrustedDomains DNS TXT record in STEP 4 Point 6.
   • Custom SSL Certificate: From the drop down, choose the certificate that you created in STEP 5.
5. Choose Save Changes.

STEP 8: Create an A (Alias) or CNAME record for the host URL

If you are using a third-party DNS service, create a CNAME record in DNS following the vendor documentation. The Record Name must be the subdomain name and value should be the CloudFront distribution URL (d123456abcdef8.cloudfront.net) that you noted in STEP 1. In my example, the subdomain is appstream2saml.

1. Navigate to the Route 53 console.
2. Choose Hosted zones.
3. On the Hosted zones page, choose the name of the hosted zone that you want to create records in.
4. Choose Create record.
5. For Record name, enter the subdomain name. In my example, I defined host (URL) as appstream2saml.example.com in the code in STEP 2 Point 4.
6. For Record type, choose A
7. Enable Alias record.
8. For Route traffic to, select Alias to CloudFront distribution.
9. Select on Choose Distribution. Select your CloudFront distribution.
10. Choose Create Records.

STEP 9: Testing the solution

1. Launch the AppStream 2.0 native client.
2. Enter the custom URL that you specified in STEP 2 Point 4 for host value followed by /idp. In this blog example, the URL is https://appstream2saml.example.com/idp. If you added the URI evaluation in the CloudFront Function code add /idp at the end of the URL, or you will encounter an HTTP 504
3. Choose Connect. The CloudFront Function redirects the client to your IdP login page.
4. Enter credentials for successful authentication.

Cleaning up

In this blog post, you created several components that may generate costs based on usage. To avoid incurring future charges, remove the following resources.

• Delete the CloudFront Function by navigating to CloudFront Console > Functions > Select the function > Delete.
• Delete the CloudFront distribution.
• Delete the AS2TrustedDomains DNS TXT record, Alias record, and CNAME records for Public Certificates in Route 53. Make sure to delete only the records that you created for this blog solution.
• Delete the ACM certificates that you requested for the Alternate Domains. Make sure to delete the certificates that you created for this blog solution.
• Delete the Public Hosted Zone. Do not delete the zone if you are using it in production environment.

Conclusion:

In this blog, you learned how to create an AS2TrustedDomains DNS TXT record in DNS targeting a third-party IdP domain with the AppStream 2.0 native client. Creating a DNS TXT record that is resolvable removes the need to create StartURL and TrustedDomains registry keys on Windows client devices. This is a useful feature for Windows devices not joined to an Active Directory domain.

TAGS: Amazon AppStream 2.0, AppStream 2.0 Client, AS2TrustedDomains, AWS End User Computing, SAML Authentication, third-party IdP URL, EUC

Mayank Jain is a Cloud Support Engineer in AWS Support Engineering who specializes in End User Computing Services. He is SME for Workspaces and Appstream services and loves helping customers on all things EUC.