Prepare your environment for the Business Connectivity Services hybrid scenario

Article
01/25/2023

APPLIES TO: yes-img-13 2013 yes-img-16 2016 yes-img-19 2019 yes-img-se Subscription Edition yes-img-sop SharePoint in Microsoft 365

This example of the Microsoft Business Connectivity Services (BCS) hybrid scenario shows you how to use standard Windows domain security to control access to the on-premises OData service endpoint. You configure one domain account with which to access the OData service endpoint, and one global security group for your federated user accounts. Then, you map the group to the account by using a Secure Store Service target application.

To prepare on-premises security for the BCS hybrid scenario

Identify all the user accounts in your on-premises domain that need to use the BCS hybrid solution and make sure that they are federated accounts. You will add these accounts to a domain global security group later in this procedure.
In your on-premises domain, create a service account that will access the OData service endpoint. These procedures use an account named ODataAccount.
In your on-premises domain, create a global security group. These procedures use a group named ODataGroup.
Add the accounts that you identified in step 1 to the ODataGroup group.

Create and configure a Secure Store target application

In this procedure, you link the ODataGroup to the ODataAccount by using a Secure Store target application. This way, users in the ODataGroup access the OData service endpoint through only one account, the ODataAccount.

In this procedure, you create and configure the on-premises Secure Store target application named ODataApp for the BCS hybrid scenario. (You can choose a different name if you want.)

To create a target application

On the Central Administration home page, in the Application Management section, select Manage service applications.
Select the Secure Store service application.
In the Manage Target Applications group, select New.
In the Target Application ID box, enter a text string. For example, ODataApp.
In the Display Name box, enter a name for the target application. For example, ODataApp.
In the Contact Email box, enter a contact email.
In the Target Application Type dropdown, select Group. This indicates the mapping of many user credentials or a security group to one credential. In this case, the Target Application Page URL is not needed and automatically selects None. Select Next.
On the Create New Secure Store Target Application page, for both Field Name and Field Type, accept the default values of Windows User Name and Windows Password. Select Next.
In the Target Application Administrators field, add the Farm Administrators account and an account that has farm administrator rights. In the Members field, add the domain security group you are using to control access to the BCS hybrid scenario solution; for example, ODataGroup.
Select OK.

Next, we need to add the credentials that we'll be using.

To set credentials for a target application

In the target application list, point at the target application that you just created, select the arrow that appears, and then, in the menu, select Set credentials.

If the target application is of type Group, enter the credentials for the external data source. Depending on the information that is required by the external data source, the fields for setting credentials will vary.

If the target application is of type Individual, enter the user name of the individual who will be mapped to this set of credentials on the external data source, and type the credentials for the external data source. Depending on the information that is required by the external data source, the fields for setting credentials will vary.
In the Windows User Name box, enter the account name for the account that will have access to the OData service endpoint in domain\username format; for example, Adventureworks\ODataAccount.
Enter and confirm the password for that account, and then select OK.

Create and configure the OData service endpoint

The BCS hybrid scenario supports connecting only to an OData source. If your external data already has an OData service endpoint, then you can skip the creating an OData service endpoint portions of this procedure. You will still need to configure permissions on the service endpoint for the ODataAccount. For the purposes of these procedures, we use the SQL Server Adventureworks sample database and the AdventureWorks 2012 LT sample data as the data source and create an OData service endpoint to make the data available to the BCS hybrid solution. You use Visual Studio 2012 to create and configure the OData service.

To create and configure the OData service endpoint, perform the procedures in How to: Create an OData data service that sends notifications to BCS in SharePoint 2013 in the MSDN Library. You will need the ODataAccount account to secure the service endpoint in Internet Information Services (IIS) 7.0.

Prepare the SharePoint in Microsoft 365 site and App Catalog

The BCS hybrid scenario publishes on-premises data to select users of SharePoint in Microsoft 365. You can present the data either through a SharePoint in Microsoft 365 external list or through an app for SharePoint in Microsoft 365. In either case, you must identify or create a site in SharePoint in Microsoft 365 through which the data will be offered. If you choose to use an app for SharePoint in Microsoft 365, you must also have a SharePoint in Microsoft 365 App Catalog configured.

To prepare the SharePoint in Microsoft 365 site and App Catalog

Identify or create a site in SharePoint in Microsoft 365 for your external list or app for SharePoint in Microsoft 365. Ensure that all the federated users who will be using the BCS hybrid solution are added to the Members group for access to the site. (The easiest way to do this is to add your ODataGroup as a Member.)
If you're going to be using a app for SharePoint in Microsoft 365, you must enable the App Catalog.

Note

This scenario shows you how to directly deploy your app for SharePoint in Microsoft 365 into the site you have prepared. It is also possible to deploy your app for SharePoint in Microsoft 365 into the App Catalog.

Set permissions on the BDC Metadata Store in SharePoint in Microsoft 365

The Business Data Connectivity service (BDC) Metadata Store holds external content types, external systems, and BDC model definitions for the BDC Service Application. In this procedure, you configure administrative permissions on the Metadata Store and everything that it will contain. Later in this scenario, if you are using the manual import of the external content type method, you will be using the BDC Metadata Store. This external content type will be available across SharePoint in Microsoft 365. If you will only be using the automated deployment of an app for SharePoint in Microsoft 365, then you will not use the BDC Metadata Store, and the external content type is scoped to the app only.

To set permissions on the BDC Metadata Store in SharePoint in Microsoft 365

Go to More features in the SharePoint admin center, and sign in with an account that has admin permissions in Microsoft 365.
Under BCS, select Open.
Select Manage BDC Models and External Content Types.
Select Set Metadata Store Permissions, and add All Authenticated Users with at least Execute permissions. This will allow all users who authenticate to your SharePoint in Microsoft 365 tenancy to use the external content types stored in the Metadata Store.
Select the Propagate permissions to all BCS Models, External Systems and External Content Types in the BDC Metadata Store. Doing so will overwrite existing permissions check box.
Select OK.

Validate external access to reverse proxy published URL

At this point in deploying the BCS hybrid scenario, you should confirm that you can access your on-premises SharePoint Server farm that has been configured to receive hybrid calls from SharePoint in Microsoft 365. This site was already configured in the SharePoint Server 2016 hybrid configuration roadmaps procedures. Its URL is the one you published through your reverse proxy.

Before you begin this procedure, make sure you have the following:

The external URL, for example, if your on-premises farm web application was configured with an alternate access mapping of "hybridexternal.sharepoint.com" and you published out "https://hybridexternal.sharepoint.com" through the reverse proxy, you will use "https://hybridexternal.sharepoint.com" for this procedure.
A computer to browse from that is in the extranet. For example, use a computer that is not on your corporate network and is not a member of your corporate domain.
The Secure Channel certificate that is stored in the SharePoint in Microsoft 365 Secure Store Service target application. This target application was configured in the SharePoint Server 2016 hybrid configuration roadmaps procedures. In the example it was named SecureChannelTargetApp. You will need the password for the certificate as well.
The credentials of a federated account.

To confirm access to external URL

Copy the certificate to your extranet computer, and then click the certificate. You will be prompted for the certificate password. This adds the certificate to your personal certificate store.
Open a web browser and browse to the externally published URL of your on-premises farm. You should be prompted for credentials. If not, check your browser settings and make sure that your logged on credentials are not being automatically passed.
Provide the credentials of the federated user. This log on must succeed and you should see the published site. If this does not work, contact the administrators who set up your hybrid infrastructure. Do not proceed any further with the BCS hybrid scenario until this issue is resolved.

Create and configure the connection settings object

Unlike BCS in SharePoint Server, BCS in SharePoint in Microsoft 365 requires that you configure a connection settings object, which contains additional information to establish the connection to the external system and the OData source.

Before you begin this procedure, make sure you have the following:

The URL or published service endpoint of the on-premises OData service that you configured.
The ID of the Secure Store target application that you configured.
The Internet-facing URL that Microsoft 365 uses to connect to the service address and that was published by the reverse proxy. This is the address that you used to browse to the external service in the last procedure, with the addition of /_vti_bin/client.svc.
The ID of the Secure Store target application for the Secure Channel certificate in Microsoft 365.

To configure the connection settings object for the BCS hybrid scenario

Go to More features in the SharePoint admin center, and sign in with an account that has admin permissions in Microsoft 365.
Under BCS, select Open.
Select Manage connections to on-premises services.
Select Add.
Give the connection settings object a name.

Important

Keep track of this name; you will use it when you create the external content type in the next procedure.
In the Service Address box, enter the URL of the OData service endpoint that you created.
For this scenario, select the Use credentials stored in SharePoint on-premises as the authentication option, and then enter the name of target application ID that holds the group to account mapping. In this scenario, it is ODataApp that you created.
In the Authentication Mode dropdown, select Impersonate Window's Identity.
In the Internet-facing URL box, enter the external URL with the /_vti_bin/client.svc extension. For example, https://hybridexternal.sharepoint.com/_vti_bin/client.svc.
In the Secure Store Target Application ID box, enter the ID of the target application that holds the Secure Channel certificate. For example, SecureChannelTargetApp.
Select Create.

Create and configure the external content type

In every BCS solution, the external content type defines the external data to SharePoint Server. It includes descriptions of how the data is structured, how it is secured, the specific portions of the external data that you want to interact with, and the permitted operations. When an external list or app for SharePoint in Microsoft 365 or business data Web Part makes a request for external data, the Business Data Connectivity service refers to the external content type for the list or app or Web Part to understand how to communicate with the external data source.

In the BCS hybrid scenario, only OData sources are supported and the preferred way to make an external content type for an OData source is to use Visual Studio 2012. Visual Studio 2012 simplifies the external content type creation process by directly connecting to the OData source, reading it, and building the external content type XML for you. Once created, you have to make some minor changes to the XML, such as inserting which connection settings object to use and removing some of the boilerplate code, before you can deploy it to SharePoint in Microsoft 365 for use in the BCS hybrid scenario.

Before you begin, make sure you have the following:

Visual Studio 2012 installed on a computer that on your corporate network.
The OData service endpoint URL
Microsoft Office Tools for Visual Studio 2012

After you have all of that, complete the steps in How to: Create an external content type from an OData source in SharePoint 2013 in the MSDN Library.

When you are done creating the external content type, deploy the hybrid scenario to an external list.