How it Works
Surescripts federated sign‑in requires an identity provider that supports the SAML 2.0 protocol. After confirming SAML 2.0 support, configure a small set of federation settings in Workbench, validate the integration in Test mode, and then enable Require SSO to move all users to federated sign‑in.
For sites with both Staging and Production environments, Surescripts strongly recommends completing this process in Staging first before moving to Production.
This configuration applies to Workbench, the Specialty Medication Gateway, and the Prior Authorization Portal.
Step 1: Identify your Federation Admin and request the role
Choose the person at your organization who will own federation configuration. This is typically a member of your identity, security, or IT team.
Open a Surescripts Support case to request the Federation Attributes Edit role for that user. Surescripts makes the Workbench accounts available to your organization based on your contracted entitlements.
Step 2: Gather prerequisites from your identity provider
Before configuring federation, confirm that your identity provider supports the SAML 2.0 protocol, publishes a public metadata endpoint secured with TLS, signs SAML assertions, and supports service‑provider‑initiated authentication. You’ll also need to identify the SAML attribute names your identity provider sends for the user’s email address, first name, and last name.
Step 3: Configure federation in Workbench (Staging first)
Sign in to Workbench and go to Administration > User Management. Under Identity Providers, select Create, then select Integrate with Surescripts Single Sign‑On. The Identity Provider field is automatically populated (but can be changed), and available accounts are populated here as described in step 1 above.
Complete the on‑screen configuration by entering the allowed email domains and SAML settings. Ensure the public metadata URL is correct and publicly accessible.
Step 4: Validate in Test mode
Important! You must complete this step and confirm successful validation before proceeding to Step 5. Skipping this step may result in unexpected login behavior after SSO is enabled, including the login page not appearing as expected.
From the Identity Provider Management page, under Enable, select Test Mode. In this mode, federated sign‑in runs alongside username‑and‑password authentication. Have a small group of users sign in using Sign in with corporate email and confirm success.
If sign‑in fails:
- Review the SAML assertion using your identity provider’s logs or a standard SAML tracing tool.
- Verify attribute mappings and ensure assertions are properly signed.
- Common issues include mismatched attribute names or unsigned assertions.
New user behavior (authentication‑only)
- Users authenticate successfully through your identity provider.
- New users are not automatically created in Workbench.
- User accounts must be provisioned by Surescripts Support before access is granted.
If a user’s email address matches multiple existing Workbench users, the user is prompted to select the correct account during first sign‑in. This selection is reused for future logins.
Step 5: Switch to Require SSO and repeat in Production
After testing is complete and the staging environment behaves as expected, enable Require SSO in Workbench.
Enabling Require SSO disables username‑and‑password sign‑in and requires all users in the selected environment to authenticate through your identity provider. The direct login URL is available on the Basic Configuration page.
Repeat the same configuration and validation steps in Production.