SAML 2.0 Setup
Note: This help topic describes new single sign-on (SSO) setup options for SAML 2.0. To enhance security and stability, Blackbaud has switched to a new SSO authentication service. Organizations that already use SSO will now see a New single sign-on tab on the Authentication settings page in Security and must set up new SSO connections by Oct. 31.
Tip: Don't want to manage certificates for your SSO connection? Then leave SAML behind and set up your connection through OpenID Connect instead. For details, see OpenID Connect (OIDC) Setup.
Security Assertion Markup Language (SAML) 2.0 is a standard protocol to exchange authentication data between security domains. To set up an SSO connection for users to sign in to Blackbaud solutions through a SAML 2.0 IdP, such as Google Workspace, OneLogin, Shibboleth, and Central Authentication Service (CAS), an organization admin (or another user with the necessary admin rights) must claim the organization's email domains, create a SAML 2.0 connection and configure its settings, test the connection, and then turn on SSO.
To prevent inadvertent lockouts, make sure to:
-
Complete the setup during a maintenance window for your organization's network.
-
Create a Blackbaud ID outside of your claimed domains with access to the Authentication settings page in Security.
Tip: If you are migrating an existing SSO connection to connect through SAML, we already pulled over any domains you previously claimed from your existing connection. This means you can proceed directly to configure your connection and then test that your organization can use your IdP to sign in to Blackbaud solutions.
When migrating an existing SSO connection, you don't need to claim your email domains because the new connection inherits the existing settings.
-
In Security, select Authentication.
-
Under New single sign-on (SSO) on the Authentication settings page, select Manage SSO settings.
If you are migrating an existing SSO connection, this option appears on the New single sign-on tab. Before you migrate, you can mange your existing connection on the Active single sign-on tab. After you migrate, the tabs no longer appear and you can no longer manage the old connection.
-
On the Single sign-on page, select SAML 2.0.
-
Under Claim your email domains, select Claim domains or Edit claimed domains to identify the email domains that your organization uses. This allows you to properly recognize and redirect members to your IdP when they sign in. For instructions, see Claimed Email Domains.
-
In a different browser tab, go to your IdP portal to register a new application or select an existing one on your domain.
-
In Assertion Consumer Service URL or Application Callback URL, add "https://id.blackbaud.com/bbid.onmicrosoft.com/B2C_1A_TrustFrameworkBase/samlp/sso/assertionconsumer" as the redirect URL.
Warning: For an existing application, don't overwrite existing redirect URLs. If you remove the redirect URLs when you add the provided redirect URL, it can disrupt your existing SSO connection.
-
In Audience or Entity, enter "https://id.blackbaud.com/bbid.onmicrosoft.com/B2C_1A_TrustFrameworkBase" as the entity ID.
-
-
Return to Blackbaud's the Authentication settings page, and under Configure your connection, select Get started or Edit connection.
-
Under Enter your connection details on the Connection tab of the Configure SAML 2.0 connection screen, enter details for your organization's connection.
-
In the Connection name field, enter a name to uniquely identity your connection. You can use this for the SSO shortcut if you opt to skip Blackbaud's sign-in page.
-
In the Metadata type field, select whether to provide a URL for the location of your SAML connection's metadata or to provide the actual metadata in XML format.
-
If you select "Metadata URL," enter the URL in the Metadata URL field where you store your metadata in XML format.
-
If you select "Metadata XML," paste the metadata directly in the Metadata field.
-
-
To sign requests from Blackbaud's platform to your IdP with a private key, select Sign SAML requests.
-
For a new connection:
-
Select Choose file and then select the Personal Information Exchange (.pfx) file for your SAML 2.0 connection.
Tip: The .pfx certificate file includes a private key to sign requests from Blackbaud's SSO platform to the IdP and provides a secure, stable connection. The .pfx file is stored securely and isn't accessible to anyone at Blackbaud.
-
In the Certificates private key field, enter the private key for your signing certificate.
-
-
For an existing connection, use the radio buttons to select whether to change the signing certificate and private key or use the existing values.
-
-
-
Under Confirm how your IdP identifies the following, specify where you store the data that your IdP uses to identify your organization's users. Enter field names or unique identifiers — as attribute names, not friendly names.
-
In the NameID field, specify where you store the unique IDs that your IdP uses to identify your users. The field for this data varies depending on your IdP, but the values are typically not email addresses or employee IDs. Instead, the values should be unique IDs that your IdP creates to distinguish users across all accounts.
Warning: We recommend against using email addresses to identify users. If you identify users by email address and need to change a user's email address, then you must re-invite the user at the new email address, which means you lose all history associated with the original one.
-
In the Email address field, specify where you store user email addresses.
Note: For successful connections, email addresses must be unique.
-
In the First name field, specify where you store first names.
-
In the Last name field, specify where you store last names.
-
-
Select I acknowledge these changes can take up to 30 minutes to take effect. We recommend waiting 30 minutes before you proceed to the Configure IdP tab and test your SSO connection.
-
Select Save and continue.
-
On the Configure IdP tab, select Open metadata to access an XML document with metadata about your SAML connection. Use this metadata to provide any additional information that your IdP requires to connect to Blackbaud's secure authentication service.
Tip: Your metadata is hosted through a direct link, but the metadata file is not available until you configure your SAML 2.0 connection in the previous steps. Keep in mind that it takes up to 30 minutes for the metadata to be ready.
-
Select Finish.
When you save your configuration settings, test mode is turned on automatically. At least one user must successfully sign in using test mode before you can enable your SSO connection.
To verify that your organization can use your identity provider (IdP) to sign in to Blackbaud solutions, select Learn about testing SSO under Test connection. Copy the URL under Blackbaud ID redirect and then test your connection in a in a private or incognito browser. For more information, see Test Mode.
Note: If a consent screen appears in test mode, then that means your IdP is configured to require admin approval before users authenticate. This consent screen is for the Blackbaud SSO application and is not requesting new permissions or access. It is seeking read-access to the user information that you already configured as part of your SSO setup. To proceed, follow the instructions on your IdP's consent screen.
To complete the connection to your IdP, select Turn on SSO under Turn on. Then on the Connect your SAML 2.0 SSO screen, select Connect with SAML 2.0.
After you turn on SSO, users are redirected to your IdP when they sign in to their Blackbaud ID with one of your claimed domains. After they authenticate through your IdP, their Blackbaud IDs:
-
Automatically redirect them to your organization's login for future sign-ins.
After users sign in through your organization's login, they are redirected to their Blackbaud ID profile unless you edit the redirect to specify a Blackbaud solution. For more information, see Redirect Settings.
-
Use your IdP for password updates, lockouts, and other authentication management.
Note: After you enable SSO, resend any pending invitations.
After you save your SSO configuration settings and turn off test mode, an Erase all single sign-on settings option appears after the SSO configuration steps. This option allows you to clear your configuration settings and start over. For example, you can select Erase all single sign-on settings if you need to select a different connection method or start over after you troubleshoot an issue. The option is only available after you save your configuration settings in step 2 and turn off test mode in step 3. When you turn on SSO, the option is no longer available, but you can turn off SSO to make it available again. For more information, see Single Sign-on Setup
Tip: For a visual reference of the SAML 2.0 setup that uses Okta as the IdP, see SAML 2.0 setup.