Desktop and Application Streaming

Using custom domains with Amazon AppStream 2.0

For many Amazon AppStream 2.0 customers, providing their users with a familiar experience for streaming sessions is an important requirement. In response to this feedback, we launched custom branding and embedded AppStream 2.0 streaming sessions. Another common customer request is the ability to use custom domains for AppStream 2.0 streaming sessions. This blog post shows you how to use an Amazon CloudFront distribution to stream an AppStream 2.0 session with a custom domain.

Note

To use a custom domain for AppStream 2.0 streaming sessions, you must create a streaming URL for these sessions. To create the streaming URL, use the CreateStreamingURL API action or the create-streaming-url AWS Command Line Interface (AWS CLI) command. You cannot use the AppStream 2.0 console to create a streaming URL in this scenario.

Walkthrough

This post shows you to perform the following tasks:

  • Create an SSL certificate through AWS Certificate Manager (ACM)
  • Create and configure a CloudFront distribution
  • Create DNS records
  • Test your configuration by navigating to your domain and subdomain URLs
  • Test your configuration by using an AppStream 2.0 streaming URL
  • Optional: Create custom streaming URLs automatically

Prerequisites

  • A domain name that you manage through a DNS service provider such as Amazon Route 53.
  • An AppStream 2.0 environment that includes an image, stack, and fleet. The image must have at least one application installed. For more information, see the following topics in the AppStream 2.0 Administration Guide:

Request an SSL certificate through AWS Certificate Manager (ACM)

Before you can create a CloudFront distribution, you must acquire an SSL certificate for the distribution. Complete the following steps to request an SSL certificate through AWS Certificate Manager.

  1. Open the ACM console at https://console.aws.amazon.com/acm.
  2. You must use the US East (N. Virginia) Region, because CloudFront requires ACM Certificates to be stored in that Region for use with a distribution.
  3. Do one of the following:
    • If you are new to using AWS Certificate Manager with this AWS account, the AWS Certificate Manager overview page opens, displaying two options: Provision certificates and Private certificate authority. Under Provision certificates, choose Get started.
    • If you have used AWS Certificate Manager before with this AWS account, proceed to the next step.
  4. On the Request a certificate page, choose Request a public certificate, and then choose Request a certificate.
  5. On the Add domain names page, under Domain name, type the domain name that you want to use for the CloudFront distribution (for example, as2.example.com).
    • If you plan to use your custom domain for embedded AppStream 2.0 streaming sessions, choose Add another name to this certificate, and type a wildcard entry for the subdomain (for example, *.as2.example.com).
    • For more information, see Configuration Requirements for Using Custom Domains in the Amazon AppStream 2.0 Administration Guide.
  6. Choose Next.
  7. On the Select validation method page, choose how you want ACM to validate your certificate request:
  8. Choose Review.
  9. Verify that the settings are correct, and then choose Confirm and request.

Create and Configure a CloudFront Distribution

Now that you have your SSL certificate, you can create your CloudFront distribution. The origin for your CloudFront distribution will be one of the regional AppStream 2.0 streaming gateways. Complete the following steps to create and configure a CloudFront distribution.

  1. Open the CloudFront AWS console at https://console.aws.amazon.com/cloudfront.
  2. Choose Create Distribution.
  3. On the Select a delivery method for your content page, in the Web section, choose Get Started.
  4. On the Create Distribution page, under Origin Settings, do the following:
    • Origin Domain Name — Type the DNS domain name of the domain of the AppStream 2.0 endpoint for the applicable Region (for example, appstream2.us-east-1.aws.amazon.com).
      • The Region must be the same Region in which your AppStream 2.0 stack and fleet are located. For the list of available endpoints, Allowed Domains in the AppStream 2.0 Administration Guide.
    • Origin Path – Keep the default setting (leave this field empty).
    • Origin ID – Keep the default setting or optionally, specify your own ID.
    • Minimum Origin SSL Protocol – Keep the default setting, TLSv1.
      • This setting displays only after you specify the Origin Domain Name.
    • Origin Protocol Policy — choose HTTPS Only.
      • This setting displays only after you specify the Origin Domain Name.
    • Origin Response Timeout – Keep the default settings, 30.
    • Origin Keep-alive Timeout – Keep the default setting, 5.
    • HTTPS Port – Keep the default setting, 443.
    • Header Name and Header Value:
      • Header name: appstream-custom-url-domain
      • Header Value: Your custom domain (for example, as2.example.com)
  5. Under Default Cache Behavior Settings, do the following:
    • Viewer Protocol Policy – Choose Redirect HTTP to HTTPS.
    • Allowed HTTP Methods – GET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE.
    • Field-level Encryption Config – Keep the default setting (leave this field empty).
    • Cached HTTP Methods – Keep the default setting, GET, HEAD (Cached by default).
    • Cache Based on Selected Request Headers – Keep the default setting, None (Improves Caching).
    • Object Caching – Keep the default setting, Use Origin Cache Headers.
    • Forward Cookies— Choose All.
    • Query String Forwarding and Caching — Choose Forward all, cache based on all.
    • Smooth streaming – Keep the default setting, No.
    • Restrict Viewer Access – Keep the default setting, No.
    • Compress Objects Automatically – Keep the default setting, No.
    • CloudFront Event and Lambda Function ARN – Keep the default settings (leave both fields empty).
  6. Under Distribution Settings, do the following:
    • Price Class – Keep the default setting, Use All Edge Locations.
    • AWS WAF Web ACL – Keep the default setting, None.
    • Alternate Domain Names (CNAMEs) — The values must match the domain names that you specified in step 5 of the previous procedure, “Create an SSL certificate through AWS Certificate Manager (ACM).” This includes the wildcard entry. For example: as2.example.com, *.as2.example.com.
    • SSL Certificate — Choose Custom SSL Certificate, and select the certificate that you created in the previous procedure, “Create an SSL certificate through AWS Certificate Manager (ACM).”
  7. Keep the default values for the remaining settings.
  8. Choose Create Distribution.

Create DNS Records

Now that you’ve created your CloudFront distribution, you must configure your DNS provider to route traffic for your domain to the distribution. The following steps describe how to do so by using Route 53.

  1. Open the Amazon Route 53 console at https://console.aws.amazon.com/route53.
  2. Do one of the following:
    • If you are new to using Route 53 with this AWS account, the Amazon Route 53 overview page opens, displaying four options: DNS management, Traffic management, Availability monitoring, and Domain registration. Under DNS management, choose Get started now.
    • If this you have used Route 53 before with this AWS account, proceed to the next step.
  3. In the navigation pane, choose Hosted zones.
  4. If you already have a hosted zone for your domain, skip to step 5. If you don’t, perform the applicable procedure to create a hosted zone:
  5. On the Hosted Zones page, choose the name of the hosted zone that you want to administer.
  6. Choose Create Record Set.
  7.  Create two entries for your domain and your wildcard subdomain (for example, as2.example.com, *.as2.example.com). Specify the following settings:
    • Type: A – IPv4 address
    • Alias: Yes
    • Alias Target: CloudFront Distribution URL
  8. Keep the default values for all other settings.

Note

If you are not using Route 53 to manage DNS for your domain, use your DNS service provider and add two DNS entries that point to your domain and wildcard subdomain to the URL of your CloudFront distribution.

Test your configuration by navigating to your domain and subdomain URLs

To test your configuration, open a web browser and navigate to the URL for your custom domain (for example, as2.example.com). If the test is successful, a 404 error page displays. Also, test the wildcard DNS entry for the subdomain. When you navigate to the URL for any subdomain (for example, xyz.as2.example.com), if the test is successful, the same 404 error page displays.

Test your configuration by using an AppStream 2.0 streaming URL

  1. Open the AppStream 2.0 AWS console at https://console.aws.amazon.com/appstream2.
    • Make sure that you use the same Region as the Region for your CloudFront distribution’s origin domain.
  2. In the left navigation pane, choose Stacks, and select the stack that you want to test.
  3. Choose Actions, Create streaming URL.
  4. In the Streaming URL dialog box, type a User id, choose a time for URL Expiration, and choose Get URL.
  5. After the streaming URL is generated, choose Copy Link and paste the streaming URL into a text editor.
  6. In the text editor, find the AppStream 2.0 endpoint URL (for example, appstream2.us-east-1.aws.amazon.com) and replace it with your domain URL (for example, as2.example.com).
  7. Open a web browser and copy and paste the modified streaming URL into the address bar.
  8. If the test is successful, the AppStream 2.0 application catalog for the stack displays. Verify that the domain that displays is your custom domain, not the default appstream2.region.aws.amazon.com domain.
  9. On the application catalog page, open an application. After the application streaming session starts, verify that your custom domain still displays.

Optional: Create custom streaming URLs automatically

You can use the following PowerShell script or AWS Lambda function to create custom streaming URLs automatically. You can use the Lambda function to enhance a try it now or SaaS experience with AppStream 2.0, which lets you provide a seamless and familiar experience for your customers. For more information, see the AppStream 2.0 ISV Workshop series.

AWS PowerShell Tools Script

$as2domain = "AS2-ENDPOINT-URL" #Should match the origin domain for your CF distribution
$customdomain = "CUSTOM-URL" #Your custom domain
$useridlength = 16
$userid = Write-Output ( -join ((0x30..0x39) + ( 0x41..0x5A) + ( 0x61..0x7A) | Get-Random -Count $useridlength  | ForEach-Object {[char]$_}) )
$as2url = (New-APSStreamingURL -StackName 'AS2-STACK-NAME' -FleetName 'AS2-FLEET-NAME' -Region 'REGION' -UserId "$userid"  -Validity 300 -Force).StreamingURL
If ("$as2url" | Select-String -Pattern "$as2domain") {
    $as2url = $as2url.replace($as2domain, $customdomain)
}
Write-Output $as2url

Node.js Lambda Function

const AWS = require('aws-sdk');
const appstream = new AWS.AppStream;
const crypto = require('crypto');

exports.handler = (event, context, callback) => {

 var length = 16;
 var username = crypto.randomBytes(Math.ceil(length / 2)).toString('hex').slice(0, length);

 console.log("username: " + username);

 var params = {
 FleetName: '<Fleet-Name>',
 StackName: '<Stack-Name>',
 UserId: username,
 Validity: 300

 };

 createas2streamingurl(params, callback);

};

function errorResponse(errorMessage, callback) {
 callback(null, {
 statusCode: 500,
 body: JSON.stringify({
 Error: errorMessage
 }),
 headers: {
 'Access-Control-Allow-Origin': '*',
 },
 });
}

function createas2streamingurl(params, callback) {
 var request = appstream.createStreamingURL(params);
 request.
 on('success', function (response) {
 console.log("Success! AS2 Streaming URL created.");
 var as2domain = "<AS2-ENDPOINT-URL>"; //Should match the origin domain for your CF distribution
 var customdomain = "<CUSTOM-URL>"; //Your custom domain
 var output = response.data;
 var url;
 if (output.StreamingURL.match(as2domain)){
 url = output.StreamingURL.replace(as2domain, customdomain);
 console.log("custom url:" + url);
 }
 else {
 url = output.StreamingURL;
 }
 callback(null, {
 statusCode: 201,
 body: JSON.stringify({
 Message: url
 }),
 headers: {
 'Access-Control-Allow-Origin': '*',
 },
 });
 }).
 on('error', function (response) {
 console.log("error: " + JSON.stringify(response.message));
 errorResponse('Error creating AS2 streaming URL.', callback);

 }).
 send();
}

Conclusion

And that’s it! You now have a CloudFront distribution that you can use for streaming sessions, rather than the AppStream 2.0 default domain. In addition, you have example PowerShell and Lambda scripts to integrate with your AppStream 2.0 implementation.