Setup a custom domain (Optional)

By default, Sandbox Studio is deployed behind an AWS CloudFront distribution. Users can access it using the CloudFront distribution URL that is output from the SandboxStudio-API stack.

However, in most organisations you will want to provide a more user-friendly, branded domain name (e.g. sandbox.example.com). This requires setting up a custom domain in CloudFront and updating your DNS provider to route traffic to Sandbox Studio.

1. Retrieve CloudFront distribution details

• Go to the AWS Console in the Hub account.

• Navigate to CloudFront.

• Find the distribution created by the SandboxStudio-API stack.

• From the stack outputs, note:

  • CloudFrontDistributionUrl (e.g. d12345abcdef.cloudfront.net)

  • CloudFrontDistributionId (used if you need to update settings later)

2. Choose your custom domain

Decide on the domain name that will be used for Sandbox Studio. Examples:

• sandbox.yourcompany.com

• studiosandbox.example.org

Make sure this domain is one you control in your DNS provider (such as Route 53, Cloudflare, or another registrar).

3. Update CloudFront distribution with Alternate Domain Name (CNAME)

• In the CloudFront distribution settings, add your chosen domain under Alternate Domain Names (CNAMEs).

• If you’re using the AWS Console:

  1. Open your distribution → Settings → General → Alternate Domain Names.

  2. Click Edit and add your custom domain name.

CloudFront requires an SSL/TLS certificate for custom domains.

4. Provision an SSL/TLS certificate in ACM

• Go to the AWS Certificate Manager (ACM) in the us-east-1 region (required for CloudFront).

• Request a certificate for your custom domain (e.g. sandbox.example.com).

• Validate the certificate using DNS (preferred) or email validation.

• Once validated, return to your CloudFront distribution and attach this ACM certificate under Custom SSL Certificate.

5. Update your DNS provider

• In your DNS provider (e.g. Route 53), create a CNAME record:

  • Name: your custom domain (e.g. sandbox.example.com)

  • Value: the CloudFront distribution URL (e.g. d12345abcdef.cloudfront.net)

• Save the record.

It may take up to 30 minutes (or more depending on TTL settings) for DNS changes to propagate.

6. Update the ACS URL in Identity Center

Since the login flow depends on the correct Assertion Consumer Service (ACS) URL, you must update the Identity Center SAML application configuration:

• Open IAM Identity Center in the management account.

• Find the Sandbox Studio custom application.

• Update the ACS URL to:
  https://<your-custom-domain>/api/auth/login/callback

7. Update the Web App URL in Sandbox Studio

In your Sandbox Studio environment:

• Go to "Settings" > "Advanced Settings" and scroll to "Authentication Settings"
• Update the "Web App URL" value to your new domain (With no trailing slash)

Why This Matters

• Using a custom domain makes Sandbox Studio easier for users to remember and access.

• It allows branding (e.g., using your company’s domain).

• Ensures smoother authentication flows by aligning the SAML ACS URL with the URL that users actually log in through.