SSO Connection Troubleshooting

If you set up your connection incorrectly, you may inadvertently lock out everyone on your claimed domains. To prevent this, we recommend you have a backup organization admin with a Blackbaud ID email address outside of your claimed domains. If you don't have this backup organization admin account, work with Support to create one for your current organization admin.

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 entered the field names or unique identifiers that your IdP uses to permanently identify users and their email addresses and names. Check your connection in Authentication to ensure that you set up these fields correctly.

  • 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 addresses is unique.

• Check your certificate. When you set up your connection, you downloaded a certificate from your IdP and uploaded it in Authentication.

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

  • Make sure the certificate is a privacy-enhanced electronic mail (PEM) or certificate (CER) file.

  For more information, see SAML 2.0 Certificates.

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

• Check your attribute statements. When you set up an Okta application, you added the names and values that identify your users' email addresses and names as attribute statements. Check your application in your Okta account to ensure that you set up these attributes correctly.

  • For email, enter ${user.email}.

  • For given_name, enter ${user.firstName}.

  • For family_name, enter ${user.lastName}.

• Check your certificate. When you set up your application, you downloaded a certificate and upload it in Authentication. Verify that the certificate you uploaded is associated with the Okta application. For more information, see Okta Certificates.

For security reasons, your Azure AD application keys may expire every year or two. If users can no longer sign in through your Azure AD IdP, your application keys may have expired. To retain your SSO connection, refresh your keys when they expire. For more information, see Azure AD Application Keys.

For security, the certificate for your SAML 2.0 connection or Okta application expires periodically. Under Single sign-on, you can view when your certificate expires. If your certificate expired, download a new one from your IdP and then select Upload new certificate in Authentication. For more information, see SAML 2.0 Certificates or Okta Certificates.

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.

For more information, see Claimed Email Domains.

Several errors start with this message. For example, "Oops! Something went wrong. Have your admin verify the Email address of your SSO configuration" likely indicates that the email address information is not populated on the IdP profile and that an administrator needs to review the account in the IdP to ensure that email address fields are complete. For more information on this and similar errors, see the Troubleshooting FAQ on the Blackbaud Single Sign-On site.