OpenID Connect (OIDC) Setup for Entra ID

1. In Security, select Authentication.

2. Under New single sign-on (SSO) on the Authentication settings page, select Manage SSO settings.

3. On the Single sign-on page, select OIDC.

4. Under Claim your email domains, select Claim domains or Edit claimed domains and specify the email domains that your organization uses. This allows you to recognize and redirect members to your IdP when they sign in. For instructions, see Claimed Email Domains.

1. Under Configure your connection on the Authentication settings page, select Get started or Edit connection. The Configure OIDC application screen appears.

2. In a different browser tab, sign in to your Entra ID portal.

   Warning: These instructions include guidance for the Entra ID portal, but Blackbaud doesn't manage that portal. If the portal changes, we recommend checking Microsoft's official guidance in their Entra ID documentation.

   1. Under Azure services, select Microsoft Entra ID.

   2. In the menu on the left, select Overview.

   3. Under Basic information on the Overview tab, select the copy button beside the tenant ID for your Entra ID portal.

3. Return to Blackbaud's Configure OIDC application screen, and in the Connection name field, paste your organization's tenant ID.

4. To copy the redirect URL (https://id.blackbaud.com/bbid.onmicrosoft.com/oauth2/authresp), select Copy.

5. Return to the browser tab with your Entra ID portal to register a new application.

   1. In the menu on the left, select Manage and then App registrations.

   2. On the App registrations page, select New registration.

   3. In the Name field, enter a display name to identify your application.

      The display name appears at times such as during sign in, and you can edit it as necessary at any time. Multiple app registrations can share a display name because the automatically generated application (client) ID uniquely identifies each app within the identity platform.

   4. Under Supported account types, specify the users who can use your application (also known as the sign-in audience). We recommend Accounts in this organizational directory only.

   5. Under Redirect URI select Web as the platform and paste the reply URL that you copied on Blackbaud's Configure OIDC application screen (https://id.blackbaud.com/bbid.onmicrosoft.com/oauth2/authresp).

   6. Select Register. Entra ID creates the application.

   7. With Overview selected in the menu on the left, select Endpoints at the top of the page.

   8. In the list of endpoints that appears, select the copy icon under OpenID Connect metadata document.

6. Return to Blackbaud's Configure OIDC connection screen, and in the Metadata URL field, paste the URL for the OIDC metadata document that you just copied. This document contains information that is required during sign-in, such as the URLs to use and the location of the service's public signing keys. The metadata document is always located at an endpoint that ends in ".well-known/openid-configuration."

7. In the Response type field, select the "ID Token" response type that handles the generation of the client secret for SSO.

8. Return to the browser tab with your Entra ID portal with Overview still selected in the menu on the left, and under Essentials, select the copy button beside the application (client) ID.

9. Return to Blackbaud's Configure OIDC connection screen, and in the Client ID field, paste the client ID that you just copied for your Entra ID application.

10. In the fields under Confirm how your IdP identifies the following, specify where you store the data that your IdP uses to identify your organization's users. These values must match the mapping values in your the Entra ID application.

    Warning: You can only pass mapping fields if they are included under "claims_supported" in the OIDC metadata document that you provided in the Metadata URL field. That document, which ends in ".well-known/openid-configuration," contains information that is required during sign-in, such as the fields where you store data that identifies your users.

    1. In the NameID field, enter "sub." This is the default claim name that Entra ID uses to store the unique IDs that identify your users, and it can't be edited.

       We recommend against using a different value, such as 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.

    2. In the Email address field, specify where you store user email addresses. The common claim name for this field for Entra ID is "email." Alternately, to map this field to the user principle name (UPN), enter "preferred_username."

       For successful connections, email addresses must be unique.

    3. To map first and last names, return to the browser tab with your Entra ID portal.

       Tip: You only need to complete this step and the next two mapping steps if you want usernames from your IdP to show up in Blackbaud. If not, you can skip ahead to step 11.

       1. In the menu on the left, select Manage and then select Token configuration.

       2. On the Optional claims page, select Add optional claim.

       3. Under Add optional claim, select ID.

       4. In the Claim column, select family_name and given_name.

       5. Select Add.

    4. Add permissions for the first and last name mappings.

       1. In the menu on the left, select Manage and then select API permissions.

       2. Under Configured permissions on the API permissions page, select Add a permission.

       3. In the list of options that appears, select Microsoft Graph under Commonly used Microsoft APIs on the Microsoft APIs tab.

       4. Select Delegated permissions.

       5. In the Permission column, select profile.

       6. Select Add permissions.

    5. Return to Blackbaud's Configure OIDC connection screen to map the fields.

       1. In the First name field, enter "given_name" to specify where you store first names.

       2. In the Last name field, enter "family_name" to specify where you store first names.

11. Select the checkbox that acknowledges the need to wait before testing your SSO connection.

    • If you are setting up SSO for the first time, select I acknowledge these settings require 24 hours to take effect. A notification will let you know when your SSO connection is ready to test.

    • If you are editing an existing SSO connection, select I acknowledge these changes can take up to 30 minutes to take effect. We recommend waiting 30 minutes before you test the connection.

12. Select Save.

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 on the Authentication settings page. Copy the URL under Blackbaud ID redirect and then test your connection 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 on the Authentication settings page. Then on the Connect your OIDC SSO screen, select Connect with OIDC.

After you turn on SSO, users are redirected to your IdP when they sign in to their Blackbaud IDs 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 profiles unless you edit the redirect to specify a Blackbaud solution. For more information, see Redirect Settings.

  Tip: Don't forget that if your users use an app in your IdP's portal to connect to Blackbaud solutions, then you must configure that app to use the redirect URL for your live connection. For information about the redirect URL, see Redirect Settings.

• Use your IdP for password updates, lockouts, and other authentication management.

Note: After you enable SSO, resend any pending invitations.