An Introduction to Bamboo Single Sign-On (SSO) with MashPoint

Summary: Understand the benefits and challenges of using Single Sign-On in a SharePoint environment.  Learn how to install and configure Bamboo Single Sign-On with MashPoint to view data from the AdventureWorks sample database in a Web Part.

(Note: If you prefer, you may download a .PDF version of this article.)

With the introduction of MashPoint, organizations that use SharePoint can now connect to line-of-business data (e.g. accounting, CRM, inventory management, point-of-sale systems) through a standard platform that is compatible with Microsoft's Business Data Catalog (BDC).  Unlike the BDC, however, you can use MashPoint to retrieve data while running in a Windows SharePoint Services (WSS) or Microsoft Office SharePoint Server (MOSS) Standard environment.  This article presents one of the major capabilities that makes MashPoint more useful in an enterprise multi-server deployment: Bamboo Single Sign-On.

For organizations that use SharePoint as a platform for collaboration, the need to access line-of-business data is often a primary reason why SharePoint is deployed in the first place.  In fact, one of our polls indicates that this is the number one reason our customers have adopted SharePoint.  The typical scenario is to allow users to access and view critical business data necessary to make day-to-day business decisions.  At Bamboo, our intranet portals aggregate data from other business applications such as lists of customers and contacts from our CRM system, or Sales and Downloads from our online e-commerce system.  This information is typically summary data presented as charts and graphs providing a snapshot of our operations.

Each of our line-of-business systems has a different method of accessing data.  Some systems can be accessed via Web Services; some can be accessed directly via a SQL table or view.  We use MashPoint to standardize the access to our back-end data, significantly reducing the development cost of having to design and build different interfaces to line-of-business systems.

Bamboo Single Sign-On is a feature in SharePoint that provides storage and mapping of credentials such as account names and passwords so that applications can retrieve information from line-of-business applications and back-end systems.

Why Single Sign-On?

Connecting our SharePoint portal to line-of-business data presents two unique challenges:

• Since we want to trim data based on the level of access of each end user, we need a way to pass each credentials to the LOB application.  Some of our LOB applications have their own user authentication (yes - we do run non-Microsoft applications) method, and even using Active Directory or Kerberos does not allow us to authenticate users directly to the LOB system. In other words, my Windows network domain authentication does not allow me to access our e-commerce system.
• Since our LOB application runs on different servers than the SharePoint portal, we also have to deal with "double-hop" security issues.

Double-hopping is a fairly common occurrence for organizations that implement a distributed server environment.  In our situation, our SharePoint portal is running on one server.  Our CRM and e-commerce applications are running on different servers, and our SQL database also runs on its own server (see figure 2).  Since we are using NTLM (aka, Integrated Windows) authentication scheme in our network, when our users access the SharePoint portal, they are automatically authenticated to that server.  The problem with this architecture is that when the program on the SharePoint portal tries to access data on the e-commerce server, NTLM cannot pass the credentials of the same user to another server.

Technically, what happens is that the code on the SharePoint portal is running within the security context of the IIS server on that box (which is the credential of the access account specified in the Application Pool for the Web site).  In order to access another server using the credentials of currently logged on users, the program accesses external data using "impersonate" mode (meaning the code is trying to access external data using your own credentials instead of its IIS security credentials).  NTLM does not allow impersonation access to a remote server (the second hop) due to security risk where a rogue program can collect your credentials on a server and start accessing data throughout your enterprise.

Bamboo Single Sign-On is used in this situation to map user credentials, allowing them to authenticate to the server in the "second hop."  This is shown in the green lines in Figure 1 above, where IIS accesses SSO to get the user credentials and then passes the credentials on to the server in the second hop. 

Note that the program running within the IIS security context can access LOB data using the access account specified in the Web site's App Pool account (denoted by the orange line in figure 2 above), once access is granted by the LOB system.  This "trusted" access method is useful in some situations, but not when you need to trim the data based on each user's access profile, since the data returned from the LOB system will be filtered only by the credentials of the App Pool access account.

The IIS server can also access LOB data by using a delegate security scheme such as Kerberos,  In this case, you solve the double-hop problem, but you still cannot automatically log in to our e-commerce system.  Single Sign-On solves both problems.

What is Bamboo Single Sign-On ?

As mentioned above, Bamboo Single Sign-On allows you to manage user account credentials in the appropriate security context.  Using our example, SSO allows the IIS code on the Web server to switch to the end user identity before performing a second hop to the database server. The use of SSO functionality allows users to store their credentials in a central place and use that storage to authenticate themselves to other business applications and systems.

Bamboo Single Sign-On provides a database maintaining a mapping between a user -or group of users- and the credentials (user name and password) needed to access a data source on the network. When the SharePoint logic, such as a Web Part, needs to access a remote data source, it calls the Bamboo Single Sign-On API to retrieve the necessary credentials for the given resources. If they happen to be Windows credentials, the Web Part temporarily "logs in" with those credentials, and then attempts to connect to the data source. This means the Windows credentials are only making one hop -from the Web server to the database server- and not two.

For each LOB system that SharePoint connects to, Bamboo Single Sign-On relies on an enterprise application definition (EAD) having been configured by the SharePoint administrator. The EAD is used by a Bamboo Web Part or MashPoint to "talk" to the LOB system. The EAD defines how the credentials for a particular LOB system are stored and mapped. The code within the Web Part and MashPoint uses the EAD to retrieve credentials, then log in and authenticate with the LOB application.

There are two types of EAD that are supported in this release, and are configured by the portal admin:

• Individual: where the logon users know and can manage their own credentials stored in the EAD.
• Group: where the logon user credentials are associated with a group account.

Bamboo SSO service stores credentials in a SQL database and the data are automatically encrypted using an encryption key.

Which products support Bamboo Single Sign-On ?

MashPoint Beta II provides built-in support for Single Sign-On.  With this release, you can use MashPoint to access data from remote LOB databases without worrying about double-hop issues.

In the future, the majority of Bamboo Web Parts, as well as other third party products, will provide support for Bamboo Single Sign-On technology.

How to install and configure Bamboo SSO

To install and configure SSO for use with MashPoint, download MashPoint here and follow the instructions according to whether you are installing SSO on MOSS or WSS.  Make sure to follow these steps:

1. If you are upgrading from a previous beta version, make sure to uninstall all beta Web Parts and MashPoint by following the procedure here.
2. Install MashPoint Beta II.
3. Install Bamboo SSO Services following the instructions in this article: MashPoint Single Sign-On (SSO) Installation.
4. Configure the SSO application definition (this guideline).

A Use Case for Using MashPoint SSO

In this use case, we will demonstrate how to use Bamboo SSO to access data from your SharePoint server to a SQL back-end database on a different server.  Normally, this configuration will result in a "double-hop" situation where your credentials cannot be used to authenticate on the remote database.

The sample configuration has a SharePoint site (Lam Vs Moss, in the above image) that needs to access data from a remote database server (Lam Pc).  The SharePoint server uses MashPoint and accesses data via a BDC Application Definition File (ADF).  The ADF file is created to retrieve data from a sample AdventureWorks database.  We will configure an SSO database on the Lam Vs Moss SharePoint server so that it can use the appropriate credentials to access the AdventureWorks data on the remote Lam Pc server.

Note that this use could be MOSS or WSS since MashPoint and Bamboo Single Sign-On work with both.

Getting Started

Once you have followed the instructions to install MashPoint and Bamboo Single Sign-On, make sure the Bamboo SSO service is started and running:

• On the server, click Start, Control Panel, Administrative Tools, and then click Computer Management.
• In the Computer Management console, expand Services and Applications, and then click Services.
• Right-click Microsoft Single Sign-On Service, and then choose Properties.
• On the General tab, change the Startup type to Automatic.
• On the General tab, under Service Status, click Start.
• Click OK to save your changes and close the Properties window.
• Repeat steps 1 through 6 for each applicable server in the farm.

Configure Bamboo Single Sign-On for SharePoint

Step 1. Verify SSO Installation

Make sure that you have installed and configured the appropriate access account for the SSO database as detailed in the installation instructions.

Step 2. Setup Encryption Key

1. Go to the Central Admin site, select Operations tab, and click on Mange settings for Bamboo single sign-on.

You should see the following options for setting up the SSO:

Follow the instructions in the Installation guide to set up your SSO server settings.  NOTE: If you received an "Access Denied" error message, be sure to log in with the account that you defined in the SSO management page (Server Settings page).

2.  Click on Mange encryption key, then click on Create Encryption Key.

Click OK.  Note that the Re-encryption feature is not implemented in this release, and you will receive an error message if you try to re-encrypt the database.

After the encryption key is created, you should be able back it up on a removable disk drive which should be stored in a safe place.

Step 3. Manage Enterprise Application Definition.

For each LOB application that SharePoint connects to, a corresponding enterprise application definition needs to be configured.  To configure our definition file to access the remote sample database, we must:

1. Go to Central Administration, and click Operations. In the Security Configuration section, click Manage settings for Bamboo Single Sign-On. On the Manage Settings for Single Sign-On page, click Manage settings for enterprise application definitions.



2. Click New Item.
3. We will then see the New Enterprise Application form.  Fill in the required fields on the form:

• Display Name: What the users will see in the Central Admin UI.
• Application Name: What will appear in the connection string.



•  Account Type: Leave the default selection to Group.  You use group account type where every user or group of users can share the same information without security risks.  Otherwise, you are required to create each individual mapping to each LOB system.
• Authentication: Leave the default option to uncheck.



• Logon Fields: Create a Username and Password as shown, in the password field with Mask enabled.  For other systems, you might need to specify additional fields that can be used by other Web Parts or applications.  For example, some systems might require User Name, Password, and Database Name.

Click OK when done, and you should see the completed SSO Application Definition:

Step 4. Manage Account Information

Once the EAD is created, you can use the Manage Account to create, update and edit the logon account information associated with an EAD. If you are using a group to connect to the enterprise application, you need to provide account credentials for the group to use, but you cannot delete logon account information.  If individual users are connecting directly to the enterprise application, you can preset or reset user passwords, or you can delete users from the enterprise application definition.

To associate a logon account with an EAD, follow these steps:

• On the Manage Account Information for an Enterprise Application Definition page, select the application definition for which you want to manage account information.
• In the Group account name box, type the name of the group that is allowed access to the enterprise application. When group enterprise definition is used, the credentials for accessing the LOB applications will be provided to all members of a domain group.
• In the Enterprise Application Definition section, select one of the following:
  • Update account information: Enter credentials for the first time or update the credentials used to connect to the enterprise application.
  • Delete stored credentials for this account from this enterprise application definition: Delete the credentials currently used to connect to the enterprise application.  Only available for individual account type.
  • Delete stored credentials for this account from all enterprise application definitions: Delete the credentials currently used to connect the selected enterprise application from all enterprise application definitions. Deleting stored credentials deletes credentials only for individual accounts; it does not delete credentials for group accounts.

In our example, select the sample "AW on LamPC" application definition file, and enter the account name to use when making the database connection, then click on the Set button.

On the Provide Account Information page, in the Logon Information section, type a domain user name and password for the account that will be used to connect to the enterprise application. Click OK.

Note that if you are setting up a group account type, then any user who is a member of that group will access the LOB system using this logon credential. This process is transparent to the user.  As an admin, you will have to decide whether the entire group should be allowed to have the same access credentials.

Create and Install a MashPoint Application Definition File

In this next step, we need to create a MashPoint Application Definition file to access the remote sample AdventureWorks database.  We will be following the procedure described in this article to create and setup the ADF.

We need to modify the following sections of the ADF file to connect to the remote server.  Use Notepad or Visual Studio to open the sample AW ADF file, and modify the following:

Once the ADF is modified, go to the Central Admin site, and select the Bamboo Shared Services Admin tab:

Click on the BambooSharedServices link:

Click on the Import application definition, and then import your SSO application definition file:

If the application definition file is modified and loaded correctly, you should be able to view the entity structure.  Click on the AwLamPcSSO and expand the Customer entity:

Viewing MashPoint Data in SharePoint Web

Next, we will use the Bamboo Data-Viewer Web Part to view the data in our SharePoint site.  Again, we will be following the procedure described in this article to install the Web Part and connect to the remote AdventureWorks through MashPoint using SSO authentication.

Once you have installed the Data-Viewer Web Part, open the tool part setting and select the Business Data Catalog as your data source.

Click on the data source picker, and select the Customer entity from the ADF that we just modified:

Follow the procedure to select the columns and nested data setting as shown below:

Once these settings have been completed, select OK.  You should be able to view the AW data from the remote system.  This is an example of displaying the Customer table from the AdventureWorks database using MashPoint and Bamboo Single Sign-On  services.