FAQ for Troubleshooting Single Sign-on (SSO)

To find answers to frequently asked questions about troubleshooting SSO, select a question to jump to its answer. If you don't see your question here, check the FAQs for getting started and setting up SSO.

How Do I Regain Access after My User Profile Changes?

When a username or email address changes in your identity provider (IdP), the user may lose access to Blackbaud resources, such as Support and Blackbaud solutions. Admins have two options to restore access:

  • Contact Blackbaud Support and provide the username or email address that changed.

  • Create a new Blackbaud ID for the updated email address. Invite the email address as a new Blackbaud user with all necessary application rights, and then mark the previous user inactive. The new user isn't associated with any existing Support cases or application settings for the old user, and the user may need to be granted rights separately to Blackbaud solutions.

Why Can't Users Change Blackbaud ID Email Addresses?

When organizations use SSO, users can't change email addresses through their Blackbaud ID accounts because those email addresses are managed through the organization's IdP. For login assistance, they need to see the organization's network administrator.

What Do I Do If I Lock Out Everyone During SSO Setup?

If you set up your connection incorrectly, you may inadvertently lock out everyone on your claimed domains, including organization admins. To prevent this, Blackbaud recommends the precaution of creating a backup organization admin with a Blackbaud ID email address that is outside of your claimed email domains before you set up SSO.

If you don't have this backup organization admin account, follow the steps below for how to access SSO settings when all users are locked out.

How Do Organization Admins Access SSO Settings When All Users Are Locked Out?

During SSO setup, Blackbaud recommends creating a backup organization admin with a Blackbaud ID email address that is outside of your claimed email domains. If you created this organization admin, you can use it to sign in even if you are locked out due to issues with your IdP or SSO.

If your organization admins can't sign in and you didn't create an organization admin with a Blackbaud ID email address outside of your claimed email domains, follow these steps to have one added for you:

  1. Select an email address to use that is outside your organization's claimed email domains. If you don't already have one, create one with your preferred email service or provider. For example, you can use [your-organization-name-here]admin@gmail.com.

  2. On the Blackbaud ID sign-in page, select Continue with Email.

  3. In the Email address field, enter the email address you selected.

  4. Select Continue.

  5. On the sign-up page, select Send confirmation code to send a code to your email address.

  6. Check for the confirmation email that we send to the email address, and select the button in the email to complete the Blackbaud ID sign-up process.

  7. Check your inbox for the confirmation email and copy the code.

  8. Return to the sign-up page, and in the Confirm code field, enter the confirmation code. The code expires after 10 minutes, but you can select Send new code to get a new one.

  9. Only an organization admin can authorize another organization admin, so an organization admin must contact Blackbaud Support and provide the following information:

    • KB number 190311

    • The outside domain email address to grant admin access to

    • The name for the outside domain admin account

  10. Support contacts the organization admin to confirm that the outside domain email should be granted admin access.

  11. After the authorization is confirmed, Support submits a request to add the Blackbaud ID account with the outside domain email as an organization admin.

  12. Support contacts you when this is complete.

Why Doesn't My Claimed Domain Redirect Users?

To properly recognize and redirect users to your IdP when they sign in, you need to claim the email domains, such as @your.org or @your.edu, that your organization uses. If a claimed domain fails verification or Blackbaud IDs with a claimed domain aren't redirected to your sign-in:

  • If you recently started the verification process, be patient. It may take up to two days for Blackbaud to verify ownership. Look for an email from Blackbaud — including in your SPAM or Junk folder — when verification completes.

  • To verify that you updated the correct DNS, visit ICANN WHOIS, enter the email domain, and confirm the service provider in the Name server field.

  • Follow the domain service provider's instructions to add the TXT record to the DNS.

    • Your DNS provider may support '@' as a shortcut to the root domain. Otherwise, enter the root domain, such as your.org or your.edu.

    • If your DNS already includes a record for the root domain, try to add quotes around its TXT value or append it to the end of the existing record.

Why Can't Users Sign In through a New SAML Connection?

If users can't sign in through a new SAML 2.0 application:

  • Check your field mapping. When you set up a SAML 2.0 connection, you enter the field names or unique identifiers that your IdP uses to permanently identify users and their email addresses and names. To ensure that you set up these fields correctly, check your connection on the Authentication settings page in Security.

    • Verify that fields appear exactly as in your IdP. Make sure you used attribute names, not friendly names, and check for typographical or syntax errors.

    • Make sure you mapped the NameID field to the attribute that your IdP uses to identify users when they sign in. You must include this attribute in your SAML response.

    • Ensure that each user's email address is unique.

  • Check your certificate. When you set up your connection, you download a SAML 2.0 certificate from your IdP and upload it on the Authentication settings page in Security.

    • Verify that the certificate you uploaded is from the IdP associated with the connection.

    • Make sure the certificate is a Personal Information Exchange (PFX) file.

Why Are Users No Longer Able to Sign In through an Existing SAML Connection?

For security, the certificate for your SAML 2.0 connection expires periodically. Under Single sign-on on the Authentication settings page in Security, you can view when your certificate expires. If your certificate expired, download a new one from your IdP and then select Upload new certificate.

Can't Authenticate because Name ID Isn't Mapped?

When admins configure SAML 2.0 connections, they specify where they store the data that IdPs use to identify their organization's users, including the name ID that stores unique IDs for users. If admins don't map the name ID, user authentication will fail because the response from the IdP requires the name ID to identify users when they sign in. If this happens, admins can return to the configuration screen for the SAML connection and specify the name ID.

To use a name ID that is in the subject of the SAML response instead of the attribute statement, admins must follow these special rules for how to reference the name ID in their SSO configuration:

  • If the name ID in the subject has a SPNameQualifier attribute, then map the name ID to the SPNameQualifier value, such as http://your-idp.com/unique-identifier-spnq.

    <saml:NameID SPNameQualifier="http://your-idp.com/unique-identifier-spnq" Format="urn:oasis:names:tc:SAML:2.0:nameid-format:transient">user@your-idp.com</saml:NameID>

  • If the name ID in the subject has a NameQualifier attribute, then map the name ID to the NameQualifier value, such as http://your-idp.com/unique-identifier-nq.

    <saml:NameID NameQualifier="http://your-idp.com/unique-identifier-nq" Format="urn:oasis:names:tc:SAML:2.0:nameid-format:transient">user@your-idp.com</saml:NameID>

  • If the name ID in the subject doesn't have either the SPNameQualifier or NameQualifier attribute, map the name ID to assertionSubjectName.

    <saml:NameID Format="urn:oasis:names:tc:SAML:2.0:nameid-format:transient">user@your-idp.com</saml:NameID>

Regardless of which attributes are present for the name ID in the subject, NameID must be the first value in the assertion XML. If not, it won't be captured, and authentication will fail.

How Can I Avoid Duplicate Users?

To avoid duplicate users, we recommend against reusing email addresses. If duplicates exist among the users who sign in through your IdP, then those users can't access their Blackbaud solutions.

You can avoid duplicate users by never reusing email addresses. For example, when Blackbaud ID users leave your organization, don't delete their accounts with your IdP. Instead, mark the accounts inactive so that you can reactivate the accounts if those users return and so that the IdP can't create new accounts for those email addresses. Creating multiple accounts with the same email address causes downstream consumers, such as Blackbaud, to see two unique IDs tied to the email address. This prevents users from signing in because multiple accounts can't be tied to the same Blackbaud ID email address.

If you reuse email addresses, they can cause duplicate users in two ways:

  • The IdP may create a new profile for existing Blackbaud ID users. For example, if a student with a Blackbaud ID withdraws from a school and later returns, then the IdP may create a new profile on their return even if you re-assigned the previous email address.

  • A user at your organization could be assigned an email address that someone else previously used for a Blackbaud ID. For example, if a new user's name is similar to a former employee's name, then the new user may be assigned the same email address that the former employee used.