Scroll Sites SAML Cutover Guide

Confirm admin access and assign meeting roles

Goal: make sure the right people are in the room before anyone changes production settings.

• Driver: one person shares screen and performs changes.
• Scroll Sites admin: can open Confluence → Apps → Scroll Sites → Domains & Security.
• DNS admin: can open Squarespace → Amalga.health → DNS → DNS Settings → Custom records.
• Entra admin: can manage Enterprise Applications, groups, SAML, Conditional Access, and sign-in logs.
• Tester: has assigned internal, assigned guest, and unassigned test users ready.
• Recorder: captures screenshots, timestamps, generated values, and decisions.

Stop if admin access is missing. Use the meeting to name owners and blockers only.

Freeze the current Squarespace DNS state

Open:

Squarespace
  → Amalga.health
  → DNS
  → DNS Settings
  → Custom records

Take screenshots of:

• Domains list.
• DNS page.
• DNS Settings.
• Custom records.
• Security or CAA records, if visible.

Do not touch: Microsoft 365 mail, Atlassian, DKIM, SPF, DMARC, Google verification, or autodiscover records.

Success: you have rollback screenshots and no existing record conflict has been ignored.

First setup action: start custom-domain setup in Scroll Sites

Open:

Confluence
  → Apps
  → Scroll Sites
  → Domains & Security
  → Set up a custom domain

Enter: documentation.amalga.health

Copy the two generated CNAME records:

• Domain validation CNAME: proves control of the subdomain.
• Certificate validation CNAME: lets AWS Certificate Manager issue HTTPS certificate.

Do not: use the root domain, invent a CNAME target, include https://, include a trailing slash, create an A record, use URL forwarding, or change nameservers.

Success: exact generated CNAME names and values are saved in the meeting notes.

Then add the generated CNAME records in Squarespace

Open: DNS Settings → Custom records → Add record.

Name conversion:

• documentation.amalga.health becomes documentation.
• _e71979def27c6d6ea0e7bab7b1042658.documentation.amalga.health becomes _e71979def27c6d6ea0e7bab7b1042658.documentation.
• Remove a trailing dot if Scroll Sites shows one.

Use these exact Squarespace values. Do not type the full domain in the Name field, and do not edit any existing Microsoft 365, Atlassian, DMARC, Google, or autodiscover records.

Success: both CNAME records are saved, and existing business-critical DNS records are unchanged.

Check CAA and DNS propagation

Run these lookups:

dig +short CAA amalga.health
dig +short CAA documentation.amalga.health
dig +short CNAME documentation.amalga.health
dig +short CNAME _e71979def27c6d6ea0e7bab7b1042658.documentation.amalga.health

• No CAA result usually means no CAA restriction.
• A restrictive CAA result must allow AWS Certificate Manager.
• Use the actual generated certificate record name, not the placeholder above.

Stop rule: no Active custom domain in Scroll Sites means no production SAML cutover tomorrow.

Create or verify the Entra access group

Create security group: SG-ScrollSites-Documentation-Users

Description:

Controls access to the Scroll Sites product documentation site at documentation.amalga.health. Contains approved internal users and B2B guest users only.

Add direct members:

• One assigned internal test user.
• One assigned B2B guest test user.

Do not rely on nested groups.

Success: assigned users are direct members, and the unassigned test user is not a member.

Create or verify the Entra Enterprise Application

Open:

Microsoft Entra ID
  → Enterprise applications
  → New application
  → Create your own application

Create non-gallery app: Scroll Sites - Documentation

• Set Assignment required = Yes.
• Assign only SG-ScrollSites-Documentation-Users.
• Do not assign individual users directly unless it is a documented emergency exception.

Success: only the access group is assigned and there are no unintended direct user assignments.

Prepare B2B guest access

Open:

Microsoft Entra ID
  → Users
  → New user
  → Invite external user

• Invite one known customer test user.
• Add that guest user to SG-ScrollSites-Documentation-Users.
• Ask the guest to redeem the invitation before cutover if possible.

Beginner note: guest UPNs can contain #EXT#, so validate the SAML email claim with the guest account during testing.

Prepare Conditional Access MFA

Create policy: CA - Scroll Sites Documentation - Require MFA

Do not turn this policy On until SAML assigned-user and guest-user tests pass.

Current Entra setup completed

Confirmed from the screenshots:

• Enterprise Application was created as Scroll Sites - Documentation.
• Single sign-on method is SAML.
• Basic SAML Configuration has been saved.
• SAML certificate is Active.
• Federation Metadata XML is available for download.

Current state: Entra is staged. The remaining work is mostly in Scroll Sites plus access testing.

Verify the saved Basic SAML values

In Entra, confirm these values remain exactly as saved:

Success: Entra now knows where to send the SAML response for this Scroll Sites domain.

Confirm attributes and claims

The screenshots show these default claims are present:

Guest-user note: B2B guest UPNs can contain #EXT#, so validate the email behavior with the assigned guest test user before calling this complete.

Download the Entra metadata XML

Open:

Microsoft Entra ID
  → Enterprise applications
  → Scroll Sites - Documentation
  → Single sign-on
  → SAML
  → SAML Certificates
  → Federation Metadata XML
  → Download

Then: open the downloaded XML file locally and copy the XML contents from the file.

Use the downloaded Federation Metadata XML file. Do not copy from a browser-rendered XML view if it omits parts of the file.

Configure SAML in Scroll Sites with IdP metadata XML

1. Log into Confluence as an admin who has access to Scroll Sites.
2. Go to Apps → Scroll Sites.
3. In the left sidebar, click Domains & Security.
4. Click on your domain: documentation.amalga.health.
5. Under Site access, you will see the current setting is Protected: Token access.
6. Click the button Set up single sign-on.
7. On the SAML setup screen, look for the field labeled Paste IdP metadata XML.
8. Open the Federation Metadata XML file you downloaded from Microsoft Entra ID.
9. Copy the entire content of the XML file and paste it into the field in Scroll Sites.
10. Click the Set up button.
11. After it processes successfully, change the access method from Protected: Token access to Protected: Single sign-on.
12. Click Confirm.
13. Finally, click Publish changes.

Success: Scroll Sites is now configured for SAML single sign-on with Microsoft Entra ID.

Do not delete the old token yet. Keep rollback available until all access tests pass.

Assign the access group in Entra

Confirm before testing:

• Assignment required = Yes for the Enterprise Application.
• SG-ScrollSites-Documentation-Users is assigned to the app.
• Assigned internal test user is in the group.
• Assigned B2B guest test user is in the group.
• Unassigned internal test user is not in the group.

Do not assign broad groups like All Users. Keep access scoped to the Scroll Sites documentation group.

Run access tests before tightening controls

• Assigned internal user should authenticate and load documentation.
• Assigned B2B guest user should authenticate and load documentation.
• Unassigned internal user should be denied.
• Direct article URL should require SAML before content loads.
• Entra sign-in logs should show success and denial results.

Only after these tests pass should you turn Conditional Access MFA On and remove the old token.