Setting Up Single Sign-On

Overview

You can configure single sign‑on (SSO) for Outcomes using your institution’s existing SAML‑based identity provider (e.g., Azure AD, Okta, Keycloak, or another SAML provider).

Review the guidance below to learn how to:

• prepare your account
• enter your SSO settings
• test your connection
• enable SSO

Getting Started with SSO

To get started with this setup process, you'll need to:

• be familiar with your insitition's SSO or identity-provider (IdP) configuration or have assistance from your IT or identity management team. 
• have admin access to Outcomes and your SSO provider.
• have the Manage SSO permission enabled for your Outcomes role.

You also should obtain the following from your SSO provider:

• The Metadata URL or Issuer URL for your SAML identity provider.
• The attribute name your IdP uses to send a unique user identifier (e.g., a username or email) in SAML assertions.
• The ability to register Outcomes as a new SAML service provider in your IdP.

Step 1: Open SSO Settings in Outcomes

1. Sign in to Outcomes using an account with the Manage SSO permission.
2. Go to Organization Settings and select SSO.
3. From here, you can work with your SSO configuration.

Step 2: Configure SAML Identity Provider Settings

1. Provide a name for the SSO configuration.
2. Update the SAML Identity Provider section by following these steps:
   • In your SSO provider’s settings, locate the Metadata URL (often labeled as Issuer URL, IdP metadata, or SAML metadata endpoint).
   • Copy the Metadata/Issuer URL.
   • In Outcomes, paste this URL into the SAML Identity Provider field.
   • Select the appropriate Entity ID from the dropdown, based on the metadata you just entered.
3. Complete the Options section as follows:
   • Enable the Sign Authentication Request option.
   • Leave Force Authentication disabled unless you want your IdP to prompt users to log in again when accessing Outcomes, even if they are already signed in to the IdP.
4. Complete the Attributes section that appears in Outcomes by following these steps:
   • Identify the attribute that contains each user’s unique ID in your SSO provider's configuration (e.g., NameID, email, etc.)
   • Enter the Unique ID Attribute that the SSO provider will use to send this unique name.
5. Click Add to add this SSO provider to Outcomes.

Step 3: Register Outcomes in Your SSO Provider

After you save your initial SSO settings, Outcomes generates service provider metadata that you'll need to register in your IdP. This is displayed in the Summary section of the SSO settings page.

1. In Outcomes, after adding an SSO provider, you can copy the SP Metadata XML file from the SSO settings page. This file contains the SAML service provider information.
2. In your SSO provider admin console, create or edit a SAML application for Outcomes.
3. Use the Outcomes SP Metadata XML to register Outcomes as a trusted service provider in your recepient settings. Typically, this information goes into the Service Provider or Relying Party section.
4. Copy the ACS/Callback URL from the Outcomes and paste it into the corresponding field in your SSO provider configuration.
5. Save these changes in your SSO provider, then return to the Outcomes SSO settings page.

Step 4: Test Your SSO Configuration

Testing verifies that Outcomes and your IdP can communicate successfully before you turn SSO on for users.

1. At the top of the SSO settings page, click Run Test. 
2. Outcomes will attempt a test connection to your SSO provider using the credentials and URLs you configured.
3. If there is a problem, Outcomes displays an error message indicating which field or setting prevented a successful connection. In that case, return to your SSO settings (either in Outcomes or in your IdP), correct the issue, and run the test again.
4. When the test succeeds, you'll see a message at the top of the SSO settings page that the connection worked, along with a button to commit these changes. SSO is still not enabled for your users until you commit the changes and enable it.

Step 5: Commit Changes and Enable SSO

Before enabling SSO, it's important to communicate the upcoming change to Outcomes users, including what they'll need to do the first time they sign in with SSO. See the next section for more details. Once you're ready to proceeed:

1. If you haven't already, after a successful test in Outcomes, click Commit Changes.
2. Click Enable SSO at the top of the settings page. An Enabled icon appears to indicate that this was successful.

Logging in with SSO for the First Time

If you are an existing Outcomes user (whose account was created before SSO was enabled), you'll need to:

1. Go to the Outcomes login page. The option to log in with your SSO provider appears.
2. Sign in using your SSO provider credentials. This brings you back to the Outcomes login page.
3. Enter your existing Outcomes username and password, then submit. This step links your SSO identity to your existing Outcomes account.
4. After linking once, you can sign in to Outcomes using SSO.

If your account was created after SSO was enabled, you'll sign in using your SSO provider credentials following your institution’s standard SSO login process.

Tips and Best Practices

As you get ready to implement SSO at your institution, consider doing the following:

• Plan a communication to users before enabling SSO to reduce confusion and support requests.
• Coordinate with your IT team to confirm the correct SAML attribute for unique user ID and any requirements for signed or forced-authentication requests.
• Enable SSO during a low-traffic period so you can monitor the rollout and assist users who need help linking accounts.