Set up SAML SSO

Single sign-on (SSO) is a faster, easier, and more secure way for users to log in to the Dscout platform. SSO works by establishing a connection between a service provider (SP)—in this case, Dscout—and an identity provider (IdP) like Okta, OneLogin, or Google. Once configured, Dscout can rely on your IdP to authenticate users rather than requiring users to enter a standard set of credentials like an email and password.

If you have any issues or feedback, our support team is always happy to help at support@dscout.com.

Dscout supports the following methods of SSO:

• SAML 2.0 (both SP-initiated and IdP-initiated).
• Google Sign-In (Google OAuth).
• Okta.

This article walks you through enabling SSO in Dscout using SAML 2.0. If you want to enable another method of SSO, use the links above to view their specific instructions.

Contents

• Enable SAML SSO.
  • Configure your IdP.
  • Configure SSO in Dscout.
  • Test your SSO configuration.
  • Enable SSO in Dscout.
• Disable SAML SSO.
• Troubleshooting SAML SSO.

Enable SAML SSO

Setting up SAML SSO requires configuration in both your IdP and Dscout. The following process will have you start by entering details about Dscout into your IdP. Then, you’ll do the same in reverse, entering details about your IdP into Dscout. Finally, you’ll test the configuration and turn it on for your Dscout users.

Configure your IdP

Common IdPs your organization might be using include OneLogin and ADFS, but there are plenty of other possibilities too. On top of that, every IdP is different when it comes to configuration. (Remember, it’s not too late to loop in your organization’s IT expert!) With that said, here are the specific items you must configure in your IdP before you can enable SSO in Dscout:

• Dscout entity ID: https://dscoutapp.com/auth/saml
• ACS URL: https://auth.dscout.com/sso/sp/consume/<account_id>
• Binding type: POST
• Default relay state (for IdP-initiated SSO only): https://app.dscout.com/efflux/home/<account_id>
• Mapping attribute: Either add your attribute name or confirm you have a mapping attribute with the name email that maps to the user’s email address.

You’ll know configuration is complete when your IdP provides you with an XML metadata file. You’ll need this metadata in the next section, so save it in place where you can easily access it. Once you’ve done that, proceed to the next section.

Configure SSO in Dscout

Now that you’ve configured your IdP and have your metadata file, you’ll configure SSO in Dscout. In this section, you’ll set up SSO in Test mode so you can ensure it’s working properly. Later, you’ll test your configuration and enable it.

To configure SAML SSO:

1. In the sidebar navigation, click your Dscout account name. A drop-down opens displaying the accounts you belong to.
2. Click the Settings icon beside the account where you want to enable SSO. The Account management page is displayed.
   
   
3. Select the Settings tab.
4. Select SSO in the sidebar.
5. Click Edit.
   
   
6. Select SAML from the Authentication type drop-down.
7. Select Test mode from the Status drop-down.
   
   
8. Under SSO enforcement select which users to require SSO to log in. You have the following options:
   • Only require users with specified email domain to use SSO. (Recommended if your Dscout account is accessed by users outside of your organization. For example, contractors or consultants.)
   • Force everyone regardless of email domain to use SSO. (Recommended if your Dscout account is only accessed by users inside of your organization.)
9. (If applicable) Enter the SSO domain you want to require SSO when logging in. For example, domain.com.
   
   
10. Enter email in the Mapping attribute field. This is the piece of data Dscout looks for in your IdP to associate a user with their Dscout account. The attribute must match the mapping attribute as set up in your IdP in the previous section.
11. Copy and paste the metadata from your IdP into the Metadata (XML) text box.
12. Click Save.

Now, your SSO configuration has been saved in Test mode. The means that users can still sign in using their standard email and password, but they also have the option of using SSO. Next, you’ll test your configuration to ensure it’s working properly, then enforce it.

Test your SSO configuration

With SSO in Test mode, have one of your Dscout users attempt to log in using SSO. This user should be someone with your company’s domain to ensure the test is accurate. If the user runs into any issues, revisit the steps for configuring both your IdP and Dscout to ensure all settings are correct. Once the user is able to log in using SSO without any problems, proceed to the next section.

Enable SSO in Dscout

Once you’ve tested your SSO configuration and have verified it’s working as expected, the next step is to enable it for all users. Once SSO is enabled, it will be enforced for either all users or all users with your company domain (depending on your SSO enforcement selection).

To enable SSO:

1. On the SSO settings page, click Edit beside your SSO configuration.
2. Select Enabled from the Status drop-down.
   
   
3. Click Save.

Now, you’re brought back to the SSO settings page where you’ll see that SSO is set to Enabled. Users currently logged in to Dscout will not be logged out, but users will be prompted to use SSO the next time they log in to the platform.

Disable SAML SSO

If you no longer wish to use SSO on your Dscout account, you can disable it from the SSO page of your account settings.

To disable SSO:

1. In the sidebar navigation, click your Dscout account name. A drop-down opens displaying the accounts you belong to.
2. Click the Settings icon beside the account where you want to disable SSO. The Account management page is displayed.
3. Select the Settings tab.
4. Select SSO in the sidebar. The SSO page appears showing your current SSO configuration.
5. Click Edit.
6. Select Disabled from the Status drop-down.
   
   
7. Click Save.

Now, SSO is disabled for your Dscout account. Users currently logged in will not be logged out, however they will be prompted to use their standard email and password credentials the next time they log in to the platform. If you want to turn SSO back on, simply set the Status to Enabled again, but be sure your IdP details are still the same. If your IdP details have changed, complete the configuration like new.

Troubleshooting SAML SSO

If you encounter any errors while setting up SAML SSO, use the following troubleshooting tips to resolve them.

Why do users have to go to the non-SSO screen and click on the “Sign in with SSO” link?

Please bookmark https://app.dscout.com/auth/sign_in/sso instead of https://app.dscout.com/sign_in. It will users directly to the SSO page.

Users belonging to multiple Dscout accounts

It’s possible for a single user to belong to multiple Dscout accounts. However, a single user account can only be associated with one Dscout account where SAML SSO is enabled. You have two options to resolve this issue:

• Work with the listed user(s) to identify any of your organization’s Dscout projects they need to maintain access to. Then, have the user create a new account using a different email address that you can grant access to your Dscout account as well as the necessary projects. (In the case of contractors, third-party consultants, or similar, consider providing them with an email address with your domain.) Finally, delete the user’s old account from your Dscout account. Once all conflicts have been resolved, you will no longer see this error and can proceed with enabling SSO.
• If the listed user(s) would rather keep their current account associated with your Dscout account, or if they don’t know which other Dscout account they might be associated with, have them reach out to support@dscout.com. Our support team will then help remove their access from any accounts causing the conflicts. Once all conflicts have been resolved, you will no longer see this error and can proceed with enabling SSO.

This is likely caused by a difference in email on the SSO and non-SSO accounts. For example, the non-SSO account could be for j.doe@acme.com and that account will have all the missions. But that email could be an alias and the canonical address is jane.doe@acme.com. That is the email that would be “used” by the SSO.

To fix this, please change the email on the non-SSO account to the canonical email address. The customer can change the email associated with the customer's non-SSO Dscout login to the canonical email in their IdP.

SAML artifact resolution requests issued by the SP signed with RSA/SHA2

If you are looking for SAML artifact resolution requests issued by the SP to be signed using an RSA/SHA2 algorithm, Dscout does not support this. We do not support request signing, which is optional under SAML spec, because we already use TLS/SSL.

IdP signature not present on the assertion

During an SSO flow, the IdP will relay a signature to Dscout's ACS URL in one of two ways: attached to the response or attached to the assertion. Dscout requires the IdP's signature be attached to the assertion. Most IdPs are configured this way by default, but some (PingFederate, for example) are not. If you run into issues with SSO, verify that your IdP is configured in this way, then try again.

OneLogin IdP details

Please set the Audience value to match the Entity ID.

"Unsupported NameIDFormat" or "access_denied {:saml_error..." error

Dscout's implementation of SAML 2.0 does not support multiple NameIDFormat elements in the metadata.xml. The official SAML spec does allow for this but this is not something Dscout's SSO implementation supports at the moment.

The fix is simple - please remove all but one NameIDFormat element. The remaining one should be the unspecified value. Eg, urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified.

"access_denied {:saml_error..." error

Another potential reason for this error is that the user has not been added to the Dscout account. Please make sure the user email, as it appears in your IdP, has been added to Dscout first.

"access_denied {:saml_error,  ..., "Signature required" error

You are are likely missing <saml:AttributeStatement> for the email mapping.

"access denied: bad_audience" error while attempting to log in

Please ensure that the Entity ID configured in your IdP is correct. It should be https://dscoutapp.com/auth/saml . Note that it is different from our domain name.

"unknown IdP" error while attempting to log in

This typically means that you have configured the ACS URL incorrectly. Our documentation lists the ACS URL as https://auth.dscout.com/sso/sp/consume/ , please make sure to replace with your Dscout account ID in your configuration.

"bad_digest" error while attempting to log in

This error usually indicates that something went wrong with the SAML assertion signature. Please confirm that your IdP is set up to sign the assertion being sent to Dscout.

"bad_match" error while attempting to log in

Your SAML assertion in the response from your IdP does not contain the KeyInfo and X509Certificate elements. Dscout requires this information to validate against your account’s configuration on our end. Please update your configuration to include that information.

"Found an unexpected number of Signature Element" error

This error is usually due to setting up a Redirect instead of POST binding. Please ensure you have configured POST in your IdP.

invalid_cert error

The certificate included in your SAML response is not the same as the certificate you configured in metadata.xml within Dscout. Please ensure the certificates are the same.

access_denied :invalid_target_url

You have a misconfigured ACS URL for the IdP initiated sign in.