# 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.

<p class="callout info">CloudFront requires an **SSL/TLS certificate** for custom domains.</p>

---

#### 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.

<p class="callout info">It may take up to 30 minutes (or more depending on TTL settings) for DNS changes to propagate.</p>

---

#### 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:<span class="hljs-regexp">//</span><your-custom-domain><span class="hljs-regexp">/api/au</span>th/login/callback`

<div class="contain-inline-size rounded-2xl relative bg-token-sidebar-surface-primary" id="bkmrk-https%3A%2F%2F%3Cyour-custom"><div class="overflow-y-auto p-4" dir="ltr">**Example:**</div></div><div class="contain-inline-size rounded-2xl relative bg-token-sidebar-surface-primary" id="bkmrk-https%3A%2F%2Fsandbox.exam"><div class="overflow-y-auto p-4" dir="ltr">`https:<span class="hljs-comment">//sandbox.example.com/api/auth/login/callback</span>`</div><div class="overflow-y-auto p-4" dir="ltr">  
</div><div class="overflow-y-auto p-4" dir="ltr">This ensures SAML assertions are posted to the correct URL.</div>---

</div>#### 7. Update the Web App URL in Sandbox Studio

In your **Sandbox Studio** environment:

- Go to "**Settings**" &gt; "**Advanced Settings**" and scroll to "**Authentication Settings**"
- Update the "**Web App URL**" value to your new domain (With no trailing slash)

<div class="contain-inline-size rounded-2xl relative bg-token-sidebar-surface-primary" id="bkmrk-example%3A"><div class="overflow-y-auto p-4" dir="ltr">**Example:**</div></div><div class="contain-inline-size rounded-2xl relative bg-token-sidebar-surface-primary" id="bkmrk-https%3A%2F%2Fsandbox.exam-1"><div class="overflow-y-auto p-4" dir="ltr">`https:<span class="hljs-comment">//sandbox.example.com</span>`</div></div><div class="contain-inline-size rounded-2xl relative bg-token-sidebar-surface-primary" id="bkmrk-you-should-now-be-ab"><div class="overflow-y-auto p-4" dir="ltr">- You should now be able to access (and login) to your Sandbox Studio using the new domain.

</div></div>---

#### 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.