SWAY Single Sign-On (SSO) — SAML Guidance & Configuration

SWAY's Single Sign-On (SSO) features are built on SAML 2.0 and will function with most SAML-based Identity Providers (IdP). SWAY acts as the Service Provider (SP), using a standard SP-initiated authentication flow, which includes the following steps:

All provider users MUST have the same email domain for SSO to be successful. If you have providers with mixed email domains, the SSO integration will not work.

1. A user visits the SWAY login page and selects to sign in via SSO (or is automatically directed based on their email domain).
2. The user is redirected to the login page for their configured Identity Provider (IdP).
3. The user authenticates using whatever means is required by their IdP.
4. The Identity Provider generates a signed SAML assertion (response) and posts it back to SWAY's Assertion Consumer Service (ACS) URL.
5. SWAY validates the signature on the assertion using the IdP's public X.509 certificate, and confirms the assertion has not expired or been tampered with.
6. SWAY validates that the user account identified in the assertion (via email or NameID) is a valid, active account within the SWAY platform. If so, the login process completes, and the user is granted access to SWAY.

Important Considerations

Here are some important considerations when exploring the viability of SAML SSO with your SWAY usage.

First, SWAY leverages this SSO process only for user authentication, not authorization. User roles, permissions, and feature access are managed within the SWAY platform. These user accounts must first be provisioned within the SWAY system.

Second, accounts must share the same email address (or matching NameID identifier) between both the SWAY system and the IdP.

Third — and unlike Healthy Roster's OAuth2 setup — SWAY's SAML integration currently requires backend development work on our end before it can go live for a given account. This means SAML configuration is not self-service; each customer's rollout will need to be scheduled and built out before testing can begin.

Fourth, once SSO is configured and deployed, both username/password and SSO sign-on options remain available by default. Once SSO has been tested and confirmed working, you can choose to either require users to sign on via SSO only, or continue offering both as viable sign-on options.

Configuration

To support Single Sign-On, customers will be required to configure their IdP as a SAML 2.0-based Identity Provider. NOTE: SWAY does not support OAuth2-based configuration at this time.

Your IdP configuration should include the following:

• The Assertion Consumer Service (ACS) URL for a successful login is:
  • https://portal.swaymedical.com/api/SAML/AssertionConsumerService
  • Binding: HTTP-POST
• The Entity ID (Audience URI) identifying SWAY as the service provider is:
  • https://swaymedical.com
• The Single Logout (SLO) Service URL is:
  • https://portal.swaymedical.com/api/SAML/SingleLogoutService
  • Supports both HTTP-Redirect and HTTP-POST bindings
• Requests and assertions must be signed. SWAY's configuration requires AuthnRequestsSigned="true" and WantAssertionsSigned="true" — your IdP must sign both AuthnRequests it sends and the assertions it returns.
• The inclusion of an email claim/attribute for the user is required. SWAY requests this as:
  • Friendly name: mail
  • Attribute name: urn:oid:0.9.2342.19200300.100.1.3
  • Name format: urn:oasis:names:tc:SAML:2.0:attrname-format:uri

For SWAY to complete SAML configuration for your account, we will require the following information from you:

• Your IdP's SAML metadata file (preferred), or alternatively:
  • Your IdP's SSO/Login URL
  • Your IdP's Entity ID
  • Your IdP's X.509 signing certificate
• Confirmation of the email attribute/claim used in your IdP's assertion (mapped to the mail attribute above)

In turn, we will provide our SWAY SAML metadata so you can configure SWAY as a relying party within your IdP. This includes SWAY's Entity ID, ACS URL, and signing certificate — the certificate is embedded in SWAY's metadata file and should be shared as that file rather than pasted inline, to avoid transcription errors.

Guidance and Configuration — Testing Process

Because SWAY's SAML SSO requires backend development work before it can go live, the recommended process is:

1. Exchange metadata. You provide your IdP's SAML metadata (or the manual equivalent), and we provide SWAY's SAML metadata for the portal.
2. Backend configuration. Our team performs the required backend development work to enable SAML for your account in the sandbox environment.
3. Schedule a testing call. Once sandbox configuration is complete, we'll schedule a call to activate and test your SSO settings together, troubleshoot any issues, and confirm the login flow works end-to-end. It's helpful to have a user who is already set up in SWAY join this call, so we can confirm the login flow with an active account and rule out any additional backend permission changes.
4. Move to production. After successful sandbox testing, we move the configuration to production.
5. Choose your sign-on policy. Once production SSO is confirmed working, you can decide whether to require SSO only, or continue to allow both username/password and SSO sign-on.

FAQ

What information do I need to activate Single Sign-On for SWAY? You'll need your IdP's SAML metadata (or the SSO URL, Entity ID, and signing certificate individually), along with confirmation of which attribute carries the user's email address.

Does SWAY support OAuth2 like Healthy Roster? No. SWAY's SSO is SAML 2.0-based only, while Healthy Roster's SSO is OAuth2-based. The two platforms are configured separately.

Will backend development be required? Yes. Unlike Healthy Roster's OAuth2 setup, SWAY's SAML integration requires backend development work on our end before it can go live for your account.

Will users still be able to log in with a username and password after SSO is enabled? Yes. Both sign-on options remain available after go-live. Once SSO has been tested and confirmed working, you can choose to require SSO only or keep both options active.

How does it work when I invite new users? Users will need an active, provisioned account in SWAY with an email address matching their IdP account before SSO login will work for them.

If we deactivate SSO, will our users lose access to SWAY? No. If SAML SSO is deactivated, users would instead use their username and password to log in.