Single sign-on from Microsoft Office SharePoint Server to applications

A solution using Tivoli Access Manager for e-Business

Microsoft® Office SharePoint® Server (MOSS) provides a single sign-on capability for applications whose content is retrieved for rendering via MOSS. Microsoft provides an interface through which other credential providers can be integrated. In this article, an approach to integrate IBM® Tivoli® Access Manager for e-Business with Microsoft Office SharePoint Server for downstream single sign-on is introduced. Sample code is also provided to demonstrate the integration approach described in this article.

Share:

Neil Readshaw (readshaw@au1.ibm.com), Senior Certified IT Specialist, IBM Australia Development Lab

Readshaw, NeilNeil Readshaw is a Senior Certified IT Specialist in the Tivoli Advanced Technology team. Based in the IBM Australia Development Lab, Neil works with customers to define solutions using the Tivoli Security software suite, and works in an enablement role with IBM Business Partners and the IBM technical sales team in the Asia Pacific region.


developerWorks Contributing author
        level

29 September 2008

Introduction

When discussing single sign-on (SSO) in a portal environment, four different realms of SSO are usually discussed. These are shown in Figure 1. Of interest in this article is the Portal SSO realm, where authentication is required to obtain portal content from other IT systems. SSO simplifies the user experience by having the portal provide credentials to the other IT systems on behalf of the user accessing the portal.

Figure 1. SSO realms in a portal environment
SSO realms

In a Microsoft Office SharePoint Server (MOSS) environment, an interface is provided so that MOSS can retrieve user credentials from a third-party credential store. Those credentials can then be used for SSO in the portal realm. In this article, the MOSS SSO interface is exploited with a new software module that uses the Tivoli Access Manager (TAM) Global Sign-on (GSO) capability as the credential store for username/password credentials. An existing solution from IBM that provides access to TAM from a Microsoft .NET environment is used to accelerate the solution's implementation.


Solution design

Figure 2 depicts the solution architecture for the SSO module to be developed.

Figure 2. Architecture overview
Architecture overview

When a user accesses portal content that requires credentials for SSO, the solution works as follows:

  1. The user authenticates to MOSS and accesses a site that has content requiring credentials to retrieve data from the enterprise information system.
  2. An attempt is made by MOSS or the web part to obtain credentials through the SSO provider interface.
  3. The TAM SSO provider (when configured) will use a TAM administration API to request SSO credentials from the TAM Policy Server.
  4. The TAM Policy Server will obtain SSO credentials stored in the TAM directory and return them to the TAM SSO provider.
  5. The TAM SSO provider will return the SSO credentials to the requestor in MOSS.
  6. The MOSS content will use the credentials as required to interface with the enterprise information system.

Aspects of the solution design are now described in more detail.

MOSS SSO provider interface

MOSS provides an external interface so that other systems can be integrated to provide SSO credential services. Microsoft provides an article that describes how to exploit this interface to implement a pluggable SSO provider. Only a single SSO provider can be configured at any time, so configuring a custom SSO provider replaces the default SSO provider in MOSS. The solution described in this article implements the Microsoft.SharePoint.Portal.SingleSignon.ISsoProvider interface.

TAM Global Sign-On capability

TAM Global Sign-On (GSO) capability stores username/password credentials in the TAM directory on behalf of TAM users. Each application or system that is a SSO target is defines as a resource in TAM GSO. GSO resource names are case-insensitive. There is no theoretical limit on the number of GSO resources defined in TAM. Resource credentials are the user-specific credentials stored in the TAM directory. A resource credential is composed of a username and password, though the data fields can be used in any way that a consumer chooses. Data in resource credentials is case-sensitive and is encrypted in the TAM directory.

By default, a TAM user cannot have GSO resource credentials added. There is an attribute of a TAM user entry that specifies if they can have GSO resource credentials. An example of how to create a user with the GSO privilege is shown in Listing 8 in the Testing the Solution section of this article.

GSO resources and resource credentials are managed using the standard TAM methods - command line, Web Portal Manager or APIs. Consult the TAM InfoCenter for more information on administering TAM GSO resources. TAM GSO resource credentials can also be managed from Tivoli Identity Manager using the TAM Combo adapter. Using Tivoli Identity Manager allows for application/system credentials and the corresponding GSO credentials to be managed in a more integrated way. This can simplify the password synchronization challenges that can arise with solutions of this nature.

Tivoli Access Manager for Microsoft .NET

The Tivoli Access Manager integration with Microsoft .NET (AMNET) is a supported solution available from the IBM Support Site. In a Microsoft .NET environment, AMNET provides:

  • Access to the Tivoli Access Manager (TAM) Authorization API;
  • Access to the TAM Administration API;
  • Evaluation of role based access control decisions by TAM; and
  • A Web single sign-on solution for ASP.NET environments.

Implementation

The source code for a Microsoft Visual Studio® 2005 solution is available in the Downloads section of this article. This project requires the following libraries so that it can be built:

  • Tivoli Access Manager for Microsoft .NET assemblies
    • IBM.Tivoli.AccessManager.Core.dll
    • IBM.Tivoli.AccessManager.Admin.dll
  • Microsoft Office SharePoint Server assemblies
    • Microsoft.SharePoint.Portal.SingleSignon.dll

GetCredentials() is the method in the ISsoProvider interface that is invoked to retrieve credentials. Listing 1 shows the implementation of the GetCredentials() method.

Listing 1. GetCredentials() implementation
/// <summary>
/// Retrieves credentials from TAM GSO.
/// </summary>
/// <param name="AppID">Application identifier</param>
/// <returns>Username/password credentials.</returns>
public SsoCredentials GetCredentials(string AppID)
{
  AMTrace.Trace(AMTrace.APPLICATION, TraceLevel.Verbose, 
        "GetCredentials(): entry (" + AppID + ")");
  SsoCredentials creds = new SsoCredentials();

  AdminContextPoolElt elt = ctxtPool.GrabContext();
  AdminContext ctxt = elt.Context;
  try
  {
    // get current user
    string currentUser = System.Threading.Thread.CurrentPrincipal.Identity.Name;
    AMTrace.Trace(AMTrace.APPLICATION, TraceLevel.Verbose,
    "GetCredentials(): Local username is " + currentUser);

    // username may be of the form DOMAIN\user.  If so, strip off the Windows
    // domain name to make it TAM-ready
    // TODO: this could be configurable in the future
    int slashIdx = currentUser.IndexOf('\\');
    if (slashIdx >= 0)
    {
      currentUser = currentUser.Substring(slashIdx + 1);
    }
    AMTrace.Trace(AMTrace.APPLICATION, TraceLevel.Verbose,
    "GetCredentials(): SSO credential username is " + currentUser);

    // check if user exists
    User user = null;
    try
    {
      user = new User(ctxt, currentUser);
    }
    catch (AdminException ae)
    {
      AMTrace.Trace(AMTrace.APPLICATION, TraceLevel.Error, ae.ToString());
      throw new SingleSignonException(SSOReturnCodes.SSO_E_CREDS_NOT_FOUND, ae);
    }

    if (!user.IsSsoUser(ctxt))
    {
      AMTrace.Trace(AMTrace.APPLICATION, TraceLevel.Error, "User is not a GSO user.");
      throw new SingleSignonException(SSOReturnCodes.SSO_E_CREDS_NOT_FOUND);
    }

    // find their credentials in TAM GSO
    SsoCred tamCreds = null;
    try
    {
      tamCreds = new SsoCred(ctxt, AppID, currentUser);
    }
    catch (AdminException ae2)
    {
      AMTrace.Trace(AMTrace.APPLICATION, TraceLevel.Error, ae2.ToString());
      throw new SingleSignonException(SSOReturnCodes.SSO_E_CREDS_NOT_FOUND, ae2);
    }

    // build return structure
    creds.Evidence = new System.Security.SecureString[2];

    string ssoUser = tamCreds.GetSsoUser(ctxt);
    string ssoPassword = tamCreds.GetSsoPassword(ctxt);

    // extract credentials from TAM result
    creds.Evidence[0] = CreateSecureString(ssoUser);
    creds.Evidence[1] = CreateSecureString(ssoPassword);

    // put into specific properties of the SSO credentials as well
    creds.UserName = creds.Evidence[0];
    creds.Password = creds.Evidence[1];
  }
  catch (Exception ex)
  {
    AMTrace.Trace(AMTrace.APPLICATION, TraceLevel.Error, ex.ToString());
    throw new SingleSignonException(SSOReturnCodes.SSO_E_EXCEPTION, ex);
  }
  finally
  {
    ctxtPool.ReturnContext(elt);
  }

  AMTrace.Trace(AMTrace.APPLICATION, TraceLevel.Verbose, "GetCredentials(): exit");
  return creds;
}

Other notable aspects of this implementation include:

  • Because the AMNET and SharePoint assemblies will be referenced from the Global Assembly Cache (GAC) at runtime, they have the "Copy Local" property set to "False" in the project definition.
  • The configuration properties required by the module are read from a file called sps-sso-provider.xml in the AMNET_HOME\etc subdirectory. Instructions on using the configuration file are found in the Installation and Configuration section of this article.
  • The SharePoint SSO provider interface supports arbitrary credential fields, rather than just username and password. In this implementation, username and password fields are the only credential data supported, consistent with the TAM GSO data model.

In this initial implementation, the following methods are not implemented:

  • GetCredentialManagementURL()
  • GetCredentialsUsingTicket()
  • GetTicket()
  • PutIdentityOnRequest()
  • PutIdentityOnRequestUsingTicket()

These could be implemented in the future.


Installation and configuration

The IT environment into which the SSO solution will be deployed must meet these requirements:

  • Microsoft Office SharePoint Server 2007 is installed and configured.
  • The Microsoft .NET Framework 2.0 Software Development Kit is installed on the system where MOSS is installed.
  • A Tivoli Access Manager domain has been installed and configured. The systems on which the TAM Policy Server and directory are configured should be accessible from the MOSS system. The SSO solution is independent of the directory configuration chosen for the TAM environment.

Given these pre-requisites, deploying this SSO solution involves a number of steps:

  • Install and configure Tivoli Access Manager Runtime
  • Install Tivoli Access Manager for Microsoft .NET
  • Install TAM SSO Provider for Microsoft Office SharePoint Server
  • Add Assemblies to Global Assembly Cache
  • Specify SSO Provider for Microsoft Office SharePoint Server
  • Configure TAM SSO Provider for Microsoft Office SharePoint Server
  • Update TAM Access Control for GSO Credentials

Install and configure Tivoli Access Manager Runtime

The SSO solution described in this article requires that the Tivoli Access Manager Runtime be installed and configured on the MOSS system. Consult the Tivoli Access Manager InfoCenter for instructions on installing and configuration these TAM components.

Install Tivoli Access Manager for Microsoft .NET

Install the same version of Tivoli Access Manager for Microsoft .NET integration on the MOSS system as was used on the development system described in the Implementation section.

Install TAM SSO Provider for Microsoft Office SharePoint Server

Obtain the assembly IBM.Tivoli.AccessManager.SharePoint.dll from the Visual Studio 2005 project in the Downloads section of this article. Copy this assembly to any directory on the MOSS server.

Add Assemblies to Global Assembly Cache

A requirement of MOSS SSO providers is that they be installed in the .NET 2.0 Global Assembly Cache (GAC). Because of this, the Tivoli Access Manager for Microsoft .NET assemblies must also be loaded into the GAC also. The gacutil utility is used to manage the GAC.

On the MOSS system, open a .NET SDK command prompt. This can be accessed from the "Start" - "All Programs" - "Microsoft .NET Framework SDK v2.0" - "SDK Command Prompt" menu item. Run the following commands to install the assemblies into the GAC, ensuring that the output from the commands resembles what is shown in Listing 2. Specify the full path of the assemblies when using this command.

Listing 2. Installing assemblies into the GAC
C:\>gacutil /i c:\progra~1\tivoli\amnet\bin\IBM.Tivoli.AccessManager.Core.DLL
Microsoft (R) .NET Global Assembly Cache Utility.  Version 2.0.50727.42
Copyright (c) Microsoft Corporation.  All rights reserved.

Assembly successfully added to the cache

C:\>gacutil /i c:\progra~1\tivoli\amnet\bin\IBM.Tivoli.AccessManager.Admin.DLL
Microsoft (R) .NET Global Assembly Cache Utility.  Version 2.0.50727.42
Copyright (c) Microsoft Corporation.  All rights reserved.

Assembly successfully added to the cache

C:\>gacutil /i c:\projects\tamgso-ssoprovider\IBM.Tivoli.AccessManager.SharePoint.dll
Microsoft (R) .NET Global Assembly Cache Utility.  Version 2.0.50727.42
Copyright (c) Microsoft Corporation.  All rights reserved.

Assembly successfully added to the cache

Specify SSO Provider for Microsoft Office SharePoint Server

MOSS can now be configured to use the TAM based SSO provider. This is achieved using the ProviderAdmin tool. The ProviderAdmin tool takes as input the fully qualified description of the assembly contained the SSO provider, and the class name of the SSO provider. To obtain the fully qualified assembly name use the gacutil tool from a .NET SDK command prompt, as shown in Listing 3.

Listing 3. Fully qualified assembly name for TAM SSO provider
C:\>gacutil /l | find "IBM.Tivoli.AccessManager.SharePoint"
IBM.Tivoli.AccessManager.SharePoint, Version=1.0.0.0, Culture=neutral, PublicKeyToken
=974f6ef985f20748, processorArchitecture=x86

Now invoke the ProviderAdmin tool as shown in Listing 4. Line breaks are inserted for the formatting of this article. You should enter the command all on one line.

Listing 4. Registering the SSO Provider
C:\>"C:\Program Files\Microsoft Office Servers\12.0\Bin\Microsoft.SharePoint.Portal.
SingleSignon.ProviderAdmin.exe" "IBM.Tivoli.AccessManager.SharePoint, Version=1.0.0.0,
Culture=neutral, PublicKeyToken=974f6ef985f20748, processorArchitecture=x86" IBM.Tivoli.
AccessManager.SharePoint.SSOProvider
SSO Provider information was successfully installed

Verify that the SSO provider was successfully installed by looking for the "SSO Provider information was successfully installed" message as shown in Listing 4.

The Windows Service "Microsoft Single Sign-on Service", which is used by the default SharePoint SSO provider, is no longer required, so it can be stopped and set for manual start.

Configure TAM SSO Provider for Microsoft Office SharePoint Server

The TAM SSO Provider requires a privileged TAM user for accessing the TAM GSO data. Rather than using sec_master, a new user should be created, as shown in Listing 5. You may need to adapt this command based on the TAM configuration in your environment.

Listing 5. Creating a privileged user to access TAM GSO credentials
pdadmin> user create spsadmin cn=spsadmin,o=ibm,c=au "SPS Admin" Admin passw0rd
pdadmin> user modify spsadmin account-valid yes

Obtain the file sps-sso-provider.xml from the Downloads section of this article. Copy the file into the AMNET_HOME\etc directory. If AMNET is installed in the default location, this will be C:\Program Files\Tivoli\AMNET\etc.

Open the sps-sso-provider.xml file in a text editor. Using the comments in the file in conjunction with the notes in Table 1, set the values of the configuration parameters.

Table 1. Configuration parameters for TAM SSO Provider
ParameterDescriptionExample Value
adminContextPoolSizeThe number of TAM administration contexts to create when the SSO provider is initialized. The purpose of the administration context pool is to make access to the GSO credential data more efficient by reducing the number of computationally expensive administration contexts that need to be created. Requests for GSO credentials will block until a context becomes available.1
adminUserUser name of a TAM user with permission to access GSO credentials. The user name is encrypted using the CryptTool that comes with AMNET.spsadmin
adminPasswordPassword of a TAM user with permission to access GSO credentials. The password is encrypted using the CryptTool that comes with AMNET.passw0rd
traceFileA file where logging and trace information is written.c:\temp\sps-sso-provider.trace
coreTraceLevelThe granularity of trace data to be written from the IBM.Tivoli.AccessManager.Core assembly. The range of acceptable values are 0 (disabled) through 4 (verbose).1
adminTraceLevelThe granularity of trace data to be written from the IBM.Tivoli.AccessManager.Admin assembly. The range of acceptable values are 0 (disabled) through 4 (verbose).1
applicationTraceLevelThe granularity of trace data to be written from the IBM.Tivoli.AccessManager.SharePoint assembly. The range of acceptable values are 0 (disabled) through 4 (verbose).4

Save the configuration file and exit the text editor.

As described in Table 1 above, the CryptTool utility is used to encrypt the TAM username and password fields in the sps-sso-provider.xml configuration file. Listing 6 shows sample usage. The output from the command has been line wrapped in Listing 6. When the data is copied into sps-sso-provider.xml, put the resultant data all on one line otherwise the data will not be able to be successfully decrypted.

Listing 6. Using CryptTool to encrypt configuration settings
C:\Program Files\Tivoli\amnet\bin>CryptTool -encrypt spsadmin
AQAAANCMnd8BFdERjHoAwE/Cl+sBAAAAjQLkghlsUEOBMGPnNcpI7AQAAAACAAAAAAADZgAAqAAAABAA
AAC4zgrJS3tTpZKLh43x6taXAAAAAASAAACgAAAAEAAAAKxmjv1jjvFNCPGgWLeZAe4QAAAAZLBzd29Y
ZzoKz63LBYajIBQAAAB6MAAVaAIjfaoR+nRQk8aGjYUf0w==

C:\Program Files\Tivoli\amnet\bin>CryptTool -encrypt passw0rd
AQAAANCMnd8BFdERjHoAwE/Cl+sBAAAAjQLkghlsUEOBMGPnNcpI7AQAAAACAAAAAAADZgAAqAAAABAA
AAB/p9PqKW7sabahzeVPyM5EAAAAAASAAACgAAAAEAAAABBSOXiK+bdJiNaRCbHBoeYQAAAAefGIx3qQ
bSZIafT9KrdobBQAAABZaanOqMdoto/kcXdRKYujo0QYpg==

Update TAM access control for GSO credentials

TAM uses its own access control system for controlling access to the GSO credential data. By default, the default-gso ACL controls access to that data. Listing 7 shows how to add GSO credential access for the spsadmin user created above.

Listing 7. Update the TAM access control for accessing GSO credentials
pdadmin sec_master> acl modify default-gso set unauthenticated
pdadmin sec_master> acl modify default-gso set any-other
pdadmin sec_master> acl modify default-gso set user spsadmin Tv
pdadmin sec_master> acl show default-gso
ACL Name: default-gso
Description: Default GSO ACL.
Entries:
Group iv-admin TcmdbvaBRN
Unauthenticated
Any-other
User spsadmin Tv

Create trace file

The trace file specified in sps-sso-provider.xml will be created if it does not exist. It will be created upon first use, and will have file permissions and ownership based upon the user identity under which the request to SharePoint is executing. An implication of this is that upon a restart of Microsoft IIS, the trace file may not be able to be opened for writing upon the first request. It is recommended to pre-create an empty trace file with permissions allowing all users who may need to access content to write to the file. Figures 3 and 4 show sample file permissions and ownership for the trace file when all users on a system may have access to the SharePoint site. Tighter controls may be required for a production environment.

Figure 3. Trace file permissions
Trace file permissions
Figure 4. Trace file ownership
Trace file ownership

Testing the solution

After completing the steps in the preceding section, the SSO solution is ready to be tested. A web part will be used to retrieve credentials from the SSO provider.

Test scenarios

The following test scenarios will be examined:

Table 2. Test scenarios
ScenarioTest users
The user exists in MOSS and TAM and has SSO credentials.spstest1, spstest2
The user exists in MOSS and TAM but is not a GSO user in TAM.spstest3
The user exists in MOSS and TAM but does not have SSO credentials for the application identifier accessed by the web part.spstest4
The user exists in MOSS but not in TAM.spstest5

Create test users

Create five test users in the user registry used by MOSS. Depending on how MOSS was configured, this might be the local Windows registry on the MOSS system, Microsoft Active Directory or another registry. The users should be named:

  • spstest1
  • spstest2
  • spstest3
  • spstest4
  • spstest5

Corresponding users now need to be created in TAM (except for spstest5). In the Download section of this article is a script called create_test_users.pdadmin to create the test data in TAM. Copy this script to the MOSS system. Open the script in a text editor and modify as follows:

  1. Change the passwords in the "user create" commands so that the passwords comply with the password policy in the TAM environment.
  2. Modify the distinguished name suffix in the "user create" commands so that they correspond to the directory environment used by TAM.

Execute the script as shown in Listing 8 to create the test users in TAM.

Listing 8. Create test users in TAM
C:\>pdadmin -a sec_master -p <sec_master-password> create_test_users.pdadmin
cmd> user create -gsouser spstest1 cn=spstest1,o=ibm,c=au "SPS Test1" "Test1" passw0rd
cmd> user modify spstest1 account-valid yes

cmd> user create -gsouser spstest2 cn=spstest2,o=ibm,c=au "SPS Test2" "Test2" passw0rd
cmd> user modify spstest2 account-valid yes

cmd> user create spstest3 cn=spstest3,o=ibm,c=au "SPS Test3" "Test3" passw0rd
cmd> user modify spstest3 account-valid yes

cmd> user create -gsouser spstest4 cn=spstest4,o=ibm,c=au "SPS Test4" "Test4" passw0rd
cmd> user modify spstest4 account-valid yes

cmd> rsrc create AdventureWorks -desc "SharePoint Sample"

cmd> rsrccred create AdventureWorks rsrcuser u1 rsrcpwd p1 rsrctype web user spstest1
cmd> rsrccred create AdventureWorks rsrcuser u2 rsrcpwd p2 rsrctype web user spstest2

Remember that the user "spstest5" is not created in TAM since this is one of the test scenarios to be examined.

If the TAM environment is sharing the same user registry as MOSS, the users may only need to be imported into TAM and the resource credentials created. Instructions for how to modify the pdadmin script to achieve this are not described in this article.

Install sample Web part

The sample content that will exercise the new SSO provider will be taken from the Microsoft Office SharePoint Server 2007 Software Development Kit (SDK). The SDK does not have to be installed on the MOSS server, but its files must be able to be copied to the MOSS server. If the SDK is installed in the default location, the full path to the Web part will be C:\Program Files\2007 Office System Developer Resources\Samples\Business Data Catalog\PluggableProvider\SSOSampleC#\SampleSSOWebPart\bin\Debug\SampleSSOWebPart.dll. Copy the Web part to the MOSS server.

Web parts must be loaded into the Global Assembly Cache to be trusted by MOSS. From a Microsoft .NET Framework SDK Command Prompt, load the sample Web part into the Global Assembly Cache as shown in Listing 9.

Listing 9. Load Web part in the Global Assembly Cache
C:\>gacutil /i c:\projects\tamgso-ssoprovider\SampleSSOWebPart.dll
Microsoft (R) .NET Global Assembly Cache Utility.  Version 2.0.50727.42
Copyright (c) Microsoft Corporation.  All rights reserved.

Assembly successfully added to the cache

Locate the sample Web part in the GAC as shown in Listing 10. Output from the command is all on one line, and has been wrapped in this article for formatting purposes only. This output will be needed in the next section.

Listing 10. Verify Web part is in the Global Assembly Cache
C:\projects\tamgso-ssoprovider>gacutil /l | find "SampleSSOWebPart"
SampleSSOWebPart, Version=1.0.0.0, Culture=neutral, PublicKeyToken=e447e624e7099fd1,
processorArchitecture=MSIL

The next step is to add this new Web part to the list of safe controls in the MOSS server configuration. In a default installation, that is done by editing the file C:\Inetpub\wwwroot\wss\VirtualDirectories\80\web.config.

Locate the SafeControls element of the configuration file and add a new SafeControl element for the sample Web part using the output shown in Listing 10. The new SafeControl definition should resemble Listing 11.

Listing 11. SafeControl definition for web.config
<SafeControl Assembly="SampleSSOWebPart, Version=1.0.0.0, Culture=neutral,
  PublicKeyToken=e447e624e7099fd1" Namespace="SampleSSOWebPart" TypeName="*"
  Safe="True"/>

Save the configuration file and exit the text editor.

The Microsoft IIS server must be restarted for the configuration changes to take effect. Use the iisreset command as shown in Listing 12.

Listing 12. Restarting IIS
C:\projects\tamgso-ssoprovider>iisreset

Attempting stop...
Internet services successfully stopped
Attempting start...
Internet services successfully restarted

Configure sample Web part

Open a Web browser and logon as an administrator to the MOSS where you wish to add the sample Web part.

From the "Site Actions" menu, choose the "Edit Page" option as shown in Figure 5.

Figure 5. Editing a page
Editing a page

Click on the "Add Web Part" button within any zone on the page. Click on the link for "Advanced Web Part gallery and options".

From the "Browse" menu, select the "Import" option as shown in Figure 6. This step is required because the sample Web part is not already in the gallery.

Figure 6. Importing a Web part
Importing a Web Part

Click the "Browse" button and locate the SampleSSOWebPart.dwp file from the Microsoft Office SharePoint Server 2007 Software Development Kit (or a copy transferred to the MOSS machine), as shown in Figure 7.

Figure 7. Uploading the new Web part
Uploading the new Web Part

Click the "Upload" button. The Web part will be uploaded and should appear as in Figure 8.

Figure 8. Web part successfully uploaded
Web Part successfully uploaded

The new Web part can be added by using the "Add" button at the bottom of Figure 6.

Update file system permissions

File permissions need to be updated on the stash file for the key store used by the Tivoli Access Manager Runtime. The file in question is C:\Program Files\Tivoli\Policy Director\keytab\pd.sth. All users who will access the portal content must have read and execute permissions on this file. Figure 7 shows one example of appropriate file permissions for this file.

Figure 9. File permissions for pd.sth
File permissions for pd.sth

Exercising the test scenarios

When the Sample SSO Web part is accessed by the spstest1 user, the result is expected to be successful since the user is a valid TAM user and they have credentials for the AdventureWorks application. The output should resemble Figure 10.

Figure 10. Site output for spstest1
Site output for spstest1

An example of the trace written by the TAM SSO Provider module is shown in Listing 12. The first two lines are one-time initialization of the module, and confirm connectivity with the TAM Policy Server. Notice how the username presented to the module is prefixed with the Windows domain name. The TAM SSO Provider module will strip this off and use the short username when accessing the TAM directory.

Listing 12. SSO provider trace for spstest1
Info application Trace levels set.
Info application Administration context created.
Verbose application GetSsoProviderInfo(): entry
Verbose application GetSsoProviderInfo(): exit
Verbose application GetCredentials(): entry (AdventureWorks)
Verbose application GetCredentials(): Local username is SPS2007\spstest1
Verbose application GetCredentials(): SSO credential username is spstest1
Verbose application GetCredentials(): exit

The results when accessing the Sample SSO Web part as the spstest2 user are similar to spstest1. Notice though in Figure 11 that the credentials are different.

Figure 11. Site output for spstest2
Site output for spstest2

In Listing 13, notice that the one-time initialization steps are not performed. This also results in a significant performance improvement.

Listing 13. SSO provider trace for spstest2
Verbose application GetSsoProviderInfo(): entry
Verbose application GetSsoProviderInfo(): exit
Verbose application GetCredentials(): entry (AdventureWorks)
Verbose application GetCredentials(): Local username is SPS2007\spstest2
Verbose application GetCredentials(): SSO credential username is spstest2
Verbose application GetCredentials(): exit

User spstest3 is not a GSO user in TAM. The error returned by the provider is shown in Figure 12.

Figure 12. Site output for spstest3
Site output for spstest3

Notice the exception logged in Listing 14. For serviceability, an extra check is present in the code to check if a user is a GSO user. This is not required to retrieve the SSO credentials, but helps with troubleshooting.

Listing 14. SSO provider trace for spstest3
Verbose application GetSsoProviderInfo(): entry
Verbose application GetSsoProviderInfo(): exit
Verbose application GetCredentials(): entry (AdventureWorks)
Verbose application GetCredentials(): Local username is SPS2007\spstest3
Verbose application GetCredentials(): SSO credential username is spstest3
Error application User is not a GSO user.
Error application Microsoft.SharePoint.Portal.SingleSignon.SingleSignonException:
A call into SPS Single Sign-on failed. The error code returned was '-2140995583'.
at IBM.Tivoli.AccessManager.SharePoint.SSOProvider.GetCredentials(String AppID)

For user spstest4, who is a GSO user in TAM but does not have credentials, output when accessing the Sample SSO Web Part is shown in Figure 13.

Figure 13. Site output for spstest4
Site output for spstest4

The output from user spstest4 accessing the Sample SSO Web part in Listing 15 shows the error message returned from the TAM Policy Server.

Listing 15. SSO provider trace for spstest4
Verbose application GetSsoProviderInfo(): entry
Verbose application GetSsoProviderInfo(): exit
Verbose application GetCredentials(): entry (AdventureWorks)
Verbose application GetCredentials(): Local username is SPS2007\spstest4
Verbose application GetCredentials(): SSO credential username is spstest4
Verbose amnet.core IBM.Tivoli.AccessManager.Admin.AdminException ERROR:
HPDMG0917E   The specified GSO resource credential was not found. (348132245)
Verbose amnet.core IBM.Tivoli.AccessManager.Admin.AdminException SSO credential
does not exist (AdventureWorks,spstest4)
Error application IBM.Tivoli.AccessManager.Admin.AdminException: SSO credential
does not exist (AdventureWorks,spstest4)
at IBM.Tivoli.AccessManager.Admin.SsoCred..ctor(AdminContext ctxt, String target,
String userid)
at IBM.Tivoli.AccessManager.SharePoint.SSOProvider.GetCredentials(String AppID)
Error application Microsoft.SharePoint.Portal.SingleSignon.SingleSignonException:
A call into SPS Single Sign-on failed. The error code returned was '-2140995583'.
---> IBM.Tivoli.AccessManager.Admin.AdminException: SSO credential does not exist
(AdventureWorks,spstest4)
at IBM.Tivoli.AccessManager.Admin.SsoCred..ctor(AdminContext ctxt, String target,
String userid)
at IBM.Tivoli.AccessManager.SharePoint.SSOProvider.GetCredentials(String AppID)
--- End of inner exception stack trace ---
at IBM.Tivoli.AccessManager.SharePoint.SSOProvider.GetCredentials(String AppID)

User spstest5, who does not exist in TAM, generates similar output in the browser to spstest3 and spstest4 as shown in Figure 14.

Figure 14. Site output for spstest5
Site output for spstest5

The messages in Listing 16 show that the user is not a valid TAM user.

Listing 16. SSO provider trace for spstest5
Verbose application GetSsoProviderInfo(): entry
Verbose application GetSsoProviderInfo(): exit
Verbose application GetCredentials(): entry (AdventureWorks)
Verbose application GetCredentials(): Local username is SPS2007\spstest5
Verbose application GetCredentials(): SSO credential username is spstest5
Verbose amnet.core IBM.Tivoli.AccessManager.Admin.AdminException ERROR:
HPDMG0754W   The entry was not found. If a user or group is being created,
ensure that the Distinguished Name (DN) specified has the correct syntax
and is valid. (348132082)
Verbose amnet.core IBM.Tivoli.AccessManager.Admin.AdminException User does
not exist (spstest5).
Error application IBM.Tivoli.AccessManager.Admin.AdminException: User does
not exist (spstest5).
at IBM.Tivoli.AccessManager.Admin.User..ctor(AdminContext ctxt, String userid)
at IBM.Tivoli.AccessManager.SharePoint.SSOProvider.GetCredentials(String AppID)
Error application Microsoft.SharePoint.Portal.SingleSignon.SingleSignonException:
A call into SPS Single Sign-on failed. The error code returned was '-2140995583'.
---> IBM.Tivoli.AccessManager.Admin.AdminException: User does not exist (spstest5).
at IBM.Tivoli.AccessManager.Admin.User..ctor(AdminContext ctxt, String userid)
at IBM.Tivoli.AccessManager.SharePoint.SSOProvider.GetCredentials(String AppID)
--- End of inner exception stack trace ---
at IBM.Tivoli.AccessManager.SharePoint.SSOProvider.GetCredentials(String AppID)

Conclusion

The Portal SSO realm often involves the portal providing a user's credentials to an application in order to receive content. IBM Tivoli software provides a secure solution for storing users' credentials with Tivoli Access Manager, and managing the credential data with Tivoli Identity Manager. In this article, Tivoli Access Manager's Global Sign-on capability has been integrated with Microsoft Office SharePoint Server to provide a solution that can be integrated with broader security management within the enterprise.


Downloads

DescriptionNameSize
Visual Studio 2005 project for SSO ProviderIBM.Tivoli.AccessManager.SharePoint.zip57KB
Configuration filesps-sso-provider.xml3KB
TAM administration scriptcreate_test_users.pdadmin1KB
Configuration filedelete_test_users.pdadmin1KB

Resources

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Security on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Security, Tivoli (service management), Tivoli
ArticleID=338806
ArticleTitle=Single sign-on from Microsoft Office SharePoint Server to applications
publish-date=09292008