PDDS Enabling ADFS/SSO Integration – Planet DDS

If the customer requesting SSO integration is already live, ADFS or Google SSO, either one - Account Management needs to generate an Apteryx Server Setup SKU quote. Then Sales Ops can create a test URL that we can use to enable integration with their ADFS/Google environment and validate the setup there before we apply it to production. After applied successfully to production for 2 weeks or so, we can delete the test URL used for this.

Ref ticket 611808 for the process we used on the fly.

Please note this process will need to be revisited after DentalOS is released because the process will likely be completely different.

In order to properly enable the integration, the below steps need to be completed.

The customer needs to follow instructions in this article to ensure their environment is properly configured to receive and manage the login requests from Apteryx. SSO/ADFS Customer Integration Steps
Using the same documentation, the customer needs to configure their ADFS claims properly for assigning permissions to users via user groups.
The customer needs to provide the appropriate information for us to enter in Sites Dash for their Apteryx URL.
1. For ADFS, it’s an ADFS Metadata URL.
  Note that browsing directly to the URL should download an XML file. Newer integrations may instead display an XML file in the browser. If nothing populates, the customer supplied an incorrect URL or it is broken on their side. Also, if using a test environment, the customer would need to set up both the test URL and production URL in their ADFS settings.
2. For Google SSO, it’s an XML document that can be provided to us that we import using Apteryx Sites Dash.
  Note: If using a test site, the customer may need to set up and produce a different XML file for the test URL than for the production URL.
For new customers, you can skip this step. For existing customers looking to enable SSO, the PlanetDDS Sales Operations team needs to create a test site for enabling and testing SSO with the customer’s provided information as to not interrupt their existing locations' workday.
1. Ensure that the customer’s IT knows that we will need them to set up a different Apteryx URL/Sitename for testing their SSO configuration without disrupting their business.
2. Once testing with the test site is complete, they will need to return to the instructions in step 1 and switch the URL back to their live site. It will not disrupt anything for them to do this until we enable the integration on our side in Sites Dash.
3. Ensure the test site is deleted from SiteDash before enabling SSO in the Production URL.
When PlanetDDS Implementations has coordinated with the customer and is ready to enable the integration for testing/validation, follow the appropriate steps depending on the integration below.
1. https://planetdds.atlassian.net/wiki/spaces/DIKB/pages/4916871199/PDDS+Enabling+ADFS+SSO+Integration#Enabling-ADFS-Integration
2. https://planetdds.atlassian.net/wiki/spaces/DIKB/pages/4916871199/PDDS+Enabling+ADFS+SSO+Integration#Enabling-Google-SSO-Integration
The customer needs to work with our Implementation team to ensure that all aspects of the integration are working as expected (ensure that the user can effectively perform the functions of all tasks requiring specific user permissions).
After testing/validation is successful and completed, Planet DDS Implementations needs to coordinate a Go-Live date for SSO and be prepared to disable the integration should anything unexpected occur on the day of Go-Live.
1. If this was an existing customer and we used a test site, we need to remind the customer to switch the URL in their configuration from the test site’s URL to their live site’s URL.
After a period of time with the customer confirming SSO is enabled and working (I’d arbitrarily say 2 weeks to start), Planet DDS Implementations needs to have the test site for this customer purged and deleted.

Supporting Materials:

Single Sign On (SSO)

SSO/ADFS Customer Integration Steps

SSO/ADFS Troubleshooting

Enabling ADFS Integration

Navigate to the customer’s site in Sites Dash>Site Administration
In the highlighted section below, enter the customer-supplied ADFS Metadata URL, click the checkbox, and hit save to enable.
At the time of writing this article (11/19/24), please be aware of the following information.
1. Our IdentityServer needs to reboot in order to enable ADFS integration.
2. Our IdentityServer reboots every night, so if you enable it on Tuesday, they will be prompted to log in with their ADFS credentials first thing in the morning on Wednesday for example.
3. Entering the metadata URL will cause Apteryx to attempt to use it immediately, even if the IdentityServer has not yet rebooted, which will cause all users to be unable to log in until the next day. The metadata URL should be entered after the practice’s business/production hours to prevent end user issues.
4. Our IdentityServer can be manually rebooted by the Engineering team if needed. This option should be avoided as much as possible, but there may be a special business need to do it.
5. Disabling ADFS integration takes place within about 5 minutes or so. It is not instant, but it does take effect very quickly.
6. There is planned work to allow the integration to be enabled within around 5 minutes in the future, rather than needing to wait for the nightly reboot or manual reboot.

Enabling Google SSO Integration

Navigate to the customer’s site in Sites Dash>Site Administration
In the highlighted section below, enter the customer-supplied Google metadata XML file and select “Upload and Enable Google SSO.”
At the time of writing this article (11/19/24), please be aware of the following information.
1. Enabling and disabling Google SSO integration takes place within about 5 minutes or so. It is not instant, but it does take effect very quickly.