59.8 Integrating With Microsoft SharePoint Server Configured With LDAP Membership Provider

In this scenario, Access Manager gets integrated with SharePoint Server using SharePoint Security Token Service (STS). This includes the ISAPI WebGate installation on IIS, as well as Access Manager configuration and steps needed to achieve the HeaderVar integration.

Note:

Only 64-bit ISAPI WebGates are supported for this integration.

The following overview introduces the tasks that you must perform for this integration, including prerequisites, and where to find the information you need for each task.

Task overview: Integrating with Microsoft SharePoint Server Configured with LDAP Membership Provider

Preparing for this integration:
1. Install "Required Microsoft Components", as described.
2. Create a SharePoint Web site, as described in "Creating a New Web Application in Microsoft SharePoint Server".
3. Configure the SharePoint site collection, as described in "Creating a New Site Collection for Microsoft SharePoint Server".
4. Configure the created Web site with LDAP directory using Claim-Based Authentication type (which uses the LDAP Membership Provider), as described in your SharePoint documentation.
5. Ensure that users who are present in the LDAP directory can log in to the SharePoint Web site and get proper roles.
6. Test the configuration to ensure that users who are present in the LDAP directory can log in to the SharePoint Web site and get proper roles, as described in your SharePoint documentation.
Perform all tasks described in "Installing Access Manager for Microsoft SharePoint Server Configured With LDAP Membership Provider".

This task includes installing a 10g WebGate for IIS and configuring a WebGate.dll for the individual SharePoint Web site.
Add an authentication scheme for this integration, as described in "Configuring an Authentication Scheme for Use With LDAP Membership Provider".
Update the Application Domain that protects the SharePoint Web Site, as described in "Updating the Application Domain Protecting the SharePoint Web Site".
In the new Application Domain, create an authorization rule for this integration, as described in "Creating an Authorization Response for Header Variable SP_SSO_UID".
Perform all steps in "Creating an Authorization Response for the OAMAuthCookie".
Perform all steps in "Configuring and Deploying OAMCustomMembershipProvider".
Synchronize directory servers, if needed, as described in "Ensuring Directory Servers are Synchronized".
Configure single-sign-on for office documents as described in "Configuring Single Sign-On for Office Documents".
Configure single sign-off, as described in "Configuring Single Sign-off for Microsoft SharePoint Server".
Finish by testing your integration to ensure it operates without problem, as described in "Testing the Integration".

59.8.1 About Integrating With Microsoft SharePoint Server Configured With LDAP Membership Provider

The previous scenario, "Integrating With Microsoft SharePoint Server", describes how to use Windows authentication. In that scenario, authentication and authorization are performed for users residing in Active Directory. Access Manager used Windows impersonation for integration.

For the integration described in this section, support for the LDAP Membership Provider is achieved by using a HeaderVar-based integration. The ISAPI WebGate filter intercepts HTTP requests for Web resources and works with the OAM Server to authenticate the user who made the request. When authentication is successful, WebGate creates an ObSSOCookie and sends it to the user's browser to facilitate single sign-on (SSO). The WebGate also sets SP_SSO_UID as a HeaderVar action for this user session. The Oracle Custom Membership provider in SharePoint validates the ObSSOCookie using the HTTP validation method, whereby the Access Manager Custom Membership Provider makes an HTTP/HTTPS request to a protected resource. Access Manager then validates and compares the user login returned on Authorization success with SP_SSO_UID.

See Also:

"Introduction to Integrating With the SharePoint Server" for a look at processing differences between this integration and the other integrations described in this chapter.

Requirements: This integration requires that Microsoft SharePoint Server:

Must be integrated with the LDAP Membership ProviderMust not use Windows authentication
Must not have IISImpersonationModule.dll configured at the Web site using Claim Based Authentication

See Also:

"Integration Requirements"

59.8.2 Installing Access Manager for Microsoft SharePoint Server Configured With LDAP Membership Provider

You can prepare your installation for integration with Microsoft SharePoint Server Configured with LDAP Membership Provider.

Prerequisites

Perform Step 1 of the previous "About Integrating With Microsoft SharePoint Server Configured With LDAP Membership Provider".

To prepare your deployment for integration that includes LDAP Membership Provider

Install Oracle Identity Management and Access Manager.
Provision and install an ISAPI WebGate.
Configure Webgate.dll at the SharePoint Web site that you want to protect. For example:
1. Start the Internet Information Services (IIS) Manager: Click Start, Programs, Administrative Tools, Internet Information Services (IIS) Manager
2. Under Web Sites, double click the name of the SharePoint Web site to protect.
3. In the Middle pane, double click ISAPI Filters and click Add in the right pane.
4. Enter the filter name as Oracle WebGate.
5. Enter the following path to the Webgate.dll file.
```
WebGate_install_dir/access/oblix/apps/Webgate/bin/Webgate.dll
```
6. Save and apply these changes.
7. Double click Authentication in the middle pane.
8. Verify that the following Internet Information Services settings are correct: Anonymous Authentication and Forms Authentication is enabled, and Windows Authentication is disabled.
  
  Note:
  
  For Claim-based Authentication to work with Access Manager, Windows Authentication for the SharePoint Site must be disabled.
9. Save and Apply these changes.
Go to the Web sites level to protect and create an /access application that points to the newly installed WebGate_install_dir. For instance:
1. Under Web Sites, right-click the name of the Web site to be protected.
2. Select Add application named with the alias "access" that points to the appropriate WebGate_install_dir\access.
3. Under Access Permissions, check Read, Run Scripts, and Execute.
4. Save and apply these changes.
Proceed to "Configuring an Authentication Scheme for Use With LDAP Membership Provider".

59.8.3 Configuring an Authentication Scheme for Use With LDAP Membership Provider

When your integration includes the LDAP Membership Provider, only three Access Manager authentication methods are supported.

To configure an authentication scheme for SharePoint with LDAP Membership Provider:

In the Oracle Access Management Console, click Application Security at the top of the window.
In the Launch Pad tab, select Create Authentication Scheme from the Create (+) drop-down menu the Access Manager section.
On the Authentication Scheme page, fill in the:

Name: Enter a unique name for this scheme. For example: SharePoint w/LDAP-MP

Description: Optional
Authentication Level: Choose a level of security for the scheme.
Choose a Challenge Method:

Basic Authentication for SharePoint Web site root (/)

Form Authentication with Challenge Redirect for SharePoint Web site root (/)

Client Certificate Authentication for SharePoint Web site root (/)
Challenge Redirect: Enter your challenge redirect value, if required.
Choose an Authentication Module from those listed.
Challenge Parameters: Enter your challenge parameter values, if required.
Challenge URL: The URL the credential collector will redirect to for credential collection.
Click Apply to submit the new scheme, review details in the Confirmation window.
Optional: Click the Set as Default button to automatically use this with new Application Domains, then close the Confirmation window.
In the navigation tree, confirm the new scheme is listed, and then close the page.
Proceed with "Updating the Application Domain Protecting the SharePoint Web Site".

Note:

If the SharePoint resource is protected with an Access Manager client-cert authentication scheme, you might need to add to the PATH environment variable C:\Program Files\Microsoft Office Servers\14.0\Bin;C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\14\BIN.

59.8.4 Updating the Application Domain Protecting the SharePoint Web Site

The Application Domain was created when you provisioned the IIS WebGate to protect the Microsoft SharePoint Server Web site for the integration scenario with LDAP Membership Provider.

Within an Application Domain, resource definitions exist as a flat collection of objects. Each resource is defined as a specific type, and the URL prefix that identifies a document or entity stored on a server and available for access by a large audience. The location is specified using an existing shared Host Identifier.

Note:

For this integration, leave empty the URL Prefix. Do not enter a region to be appended to the URL prefix.

You need to use the authentication scheme that you created earlier. To validate the ObSSOCookie, you must create another policy for a resource protected by a WebGate; for example: /ValidateCookie. This resource should be deployed on a Web server protected by a WebGate and you should be able to access it after providing correct Access Manager credentials: http(s)://host:port/ValidateCookie

This example uses SharePoint w/LDAP-MP as the Application Domain name. Your environment will be different.

Note:

Step 4 includes an alternative Authentication Scheme to protect the SharePoint Web site with a Form authentication scheme.

To update the Application Domain protecting the root SharePoint Web site

From the Oracle Access Management Console, open the SharePoint w/LDAP-MP Application Domain.
Open the Resources tab, then click the New Resource button.
On the Resource Definition page, select or enter your details for a single resource and click Apply:
- Type: http
- Description (optional): Protecting SharePoint Website
- Host Identifier: Select the host identifier that you added earlier.
- Resource URL: Enter /ValidateCookie.
- Protection Level: Protected
- Authentication Policy (if level is Protected)
- Authorization Policy (if level is Protected and Authentication Policy is chosen)
In the Protected Resource Policy for Authentication, add a defined resource:
- Click the Resources tab on the Authentication Policy page.
- Click the Add button on the Resources tab.
- Locate and select the desired resource definition, then click Add Selected.
- Click Apply to add the resources.
- Repeat to add more resources.
Click the Responses tab, then click its Add button and:
- In the Name field, enter a unique name for this response (SP_SSO_UID).
- From the Type list, choose Header.
- In the Value field, enter a value for this response. For example: $user.userid.
- Click Apply.
Add a Policy: Add a policy for a resource used with the HTTP validation method, If selected.
Before you enable this Application Domain, proceed to "Creating an Authorization Response for Header Variable SP_SSO_UID"

59.8.5 Creating an Authorization Response for Header Variable SP_SSO_UID

You can add an Authorization Response for the integration configured with LDAP Membership Provider.

For this integration, you add the following Header Variable to the Application Domain as Responses for Authorization success:

     Type = Header
        Name = SP_SSO_UID
        Return Attribute = $user.userid

In this case:

The Return Attribute is the login attribute used in Login
This authorization rule protects the root SharePoint Web site "/ "

To create an authorization response for SharePoint with LDAP Membership Provider

From the Oracle Access Management Console, open the SharePoint w/LDAP-MP Authorization Policy: ProtectedResourcePolicy.
Click the Authorization Policy Responses tab, then click its Add button:
- In the Name field, enter a unique name for this response (SharePoint w/LDAP-MP).
- From the Type list, choose Header.
- In the Value field, enter a value for this response. For example: $user.userid.
- Click Apply.
- Repeat as needed.
Proceed to "Creating an Authorization Response for the OAMAuthCookie".

59.8.6 Creating an Authorization Response for the OAMAuthCookie

You can add the Header Variable named OAMAuthCookie to the Application Domain as Responses under Authorization success.

The Header Variable:

     Type = Cookie
        Name = OAMAuthCookie
        Return Attribute = $user.userid

To create a Application Domain to protect the validation URL

From the Oracle Access Management Console, open the SharePoint w/LDAP-MP Authorization Policy: Protected Resource Policy:
Click the Responses tab, then click its Add button and:
Redirection URL: Not required for this integration

Return
```
     Type = Cookie
        Name = OAMAuthCookie
        Return Attribute = $user.userid
```
- In the Name field, enter a unique name for this response (OAMAuthCookie).
- From the Type list, choose Cookie.
- In the Value field, enter a value for this response. For example: $user.userid.
- Click Apply to submit the response, then close the confirmation window.
- Repeat as needed.
Proceed to "Configuring and Deploying OAMCustomMembershipProvider."

59.8.7 Configuring and Deploying OAMCustomMembershipProvider

You can use the Access Manager Authentication Module to authenticate and authorize the user

You can specify a default login page bundled in this file:

WebGate_install_dir\access\oblix\apps\Webgate\ OAMCustomMembershipProvider\samples\Sample.Default.aspx

To configure SharePoint to use OAM authentication Module

Go to the physical location of the SharePoint Web site directory. For example:
```
C:\Inetpub\wwwroot\wss\VirtualDirectories\SharePoint website Name
```
From the folder_forms, copy the file Default.aspx as Default.ORIG.aspx.

Open Default.aspx, search for </asp:login>, add the following after the line, and then save the file:

<asp:HiddenField EnableViewState="false" ID="loginTracker" runat="server" Value="autoLogin" />

 <%bool autoLogin = loginTracker.Value == "autoLogin";%>

 <script runat="server">
    void Page_Load() 
    {

        signInControl.LoginError += new EventHandler(OnLoginError);
        NameValueCollection headers = Request.ServerVariables;
        NameValueCollection queryString = Request.QueryString;
        string loginasanotheruser = queryString.Get("loginasanotheruser");
        string username = Request.ServerVariables.Get("HTTP_SP_SSO_UID");
        HttpCookie ObSSOCookie = Request.Cookies["ObSSOCookie"];
        bool isOAMCredsPresent = username != null && username.Length > 0  && ObSSOCookie != null && ObSSOCookie.Value != null;
        bool signInAsDifferentUser = loginasanotheruser != null && loginasanotheruser.Contains("true");

        if (isOAMCredsPresent)
        {

            //Handling For UTF-8 Encoding in HeaderName
            if (username.StartsWith("=?UTF-8?B?") && username.EndsWith("?="))
            {
                username = username.Substring("=?UTF-8?B?".Length, username.Length - 12);
                byte[] decodedBytes = Convert.FromBase64String(username);
                username = Encoding.UTF8.GetString(decodedBytes);
            }
        }
       if (isOAMCredsPresent  && loginTracker.Value == "autoLogin" && !signInAsDifferentUser)
        {
           bool status=Microsoft.SharePoint.IdentityModel.SPClaimsUtility.AuthenticateFormsUser(new Uri(SPContext.Current.Site.Url),username,"ObSSOCookie:"+ObSSOCookie.Value);
        if(status){
                if (Context.Request.QueryString.Keys.Count > 1)
                {
                    Response.Redirect(Context.Request.QueryString["Source"].ToString());
                }
                else
                    Response.Redirect(Context.Request.QueryString["ReturnUrl"].ToString());
      }
         else{
                  loginTracker.Value = 
          }

        }
        else
        {

            // DO NOTHING
        }
    }
        void OnLoginError(object sender, EventArgs e)
    {
                  loginTracker.Value = "";
    }
 </script>

Go to IIS Manager and click the Plus icon (+) before Sites.
Click on the plus icon (+) before SharePoint Web Services.
Right -click SecurityTokenServiceApplication, then click Explore.
Create a backup copy of Web.config as Web.config.ORIG, then open Web.config.
In the membership provider entries for enabling the LDAP membership provider go to <membership>, <providers>, type, and then modify the type value as follows:
```
type = "Oracle.CustomMembershipProvider, OAMCustomMembershipProvider, Version=1.0.0.0, Culture=neutral, PublicKeyToken=52e6b93f6f0427a1
```

Add the following attribute at the end of the entry in Step 8 ValidationMode="OAMHttp" to indicate the ObSSOCookie validation method.

<add name="membership" 
             type = "Oracle.CustomMembershipProvider, OAMCustomMembershipProvider, Version=1.0.0.0, Culture=neutral, PublicKeyToken=52e6b93f6f0427a1"                                   
                     server="HOST1.COM"
             port="389" 
             useSSL="false" 
             userDNAttribute="distinguishedName"
             userNameAttribute="sAMAccountName"
             userContainer="cn=users,dc=bored,dc=com"
             userObjectClass="person" 
             userFilter="(&amp;(ObjectClass=person))" 
             scope="Subtree" 
             otherRequiredUserAttributes="sn,givenname,cn" 
                         ValidationURL="http(s)://host:port/ValidateCookie.html"
             OAMAuthUser="OAMAuthCookie
             ValidationMode="OAMHttp"
                         />

Note:

The resource configured for ValidationURL must be present on the Web server. Also, the value of the OAMAuthUser parameter should be configured as the authorization return action as described in Step 6.

Save the file.

Using command prompt go to the following directory:

C:\Program Files\Microsoft SDKs\Windows\v6.0A\Bin\gacutil.exe

Type:
```
gacutil -l OAMCustomMembershipProvider
```
Confirm that no results are returned.

Type the following.

gacutil -i <Webgate_install_dir>\access\oblix\apps\Webgate\OAMCustomMembershipProvider\OAMCustomMembershipProvider.dll

Type:

gacutil -l OAMCustomMembershipProvider

Confirm that one result is returned.
Restart the SharePoint Web site.
Proceed as follows:

59.8.8 Enabling Logging for CustomMemberShipProvider

If you want to enable logs for the Oracle Custom Membership Provider, you must configure the DebugFile parameter in the configuration file for the Oracle Custom Membership Provider.

For example: a sample entry for the DebugFile=Location_of_logs_file":

type = "Oracle.CustomMembershipProvider, OAMCustomMembershipProvider, Version=1.0.0.0, Culture=neutral, PublicKeyToken=52e6b93f6f0427a1" DebugFile="c:\Debug.txt"

59.8.9 Ensuring Directory Servers are Synchronized

Users in the directory server configured for Access Manager should be synchronized with the directory server used by SharePoint if these are different.

This is the same task that you perform for other integration scenarios in this chapter. When your SharePoint integration includes an LDAP Membership Provider, however, you can use a directory server that supports LDAP commands.

59.8.10 Testing the Integration

This is similar to the task you perform for other integration scenarios in this chapter. There are no differences when configured with LDAP Membership Provider.