This documentation relates to SharePoint Connector 1.9
If you are using an earlier version, please view the previous versions of the SharePoint Connector documentation and select the relevant version.

Skip to end of metadata
Go to start of metadata

This page is part of the installation guide for the Confluence SharePoint Connector. It tells you how to configure access to SharePoint using basic authentication and SSL via an alternative access URL in SharePoint. These instructions apply to SharePoint 2007.

On this page:

Overview

In this configuration, client browsers authenticate against SharePoint using Integrated Windows Authentication (NTLM or Kerberos). Confluence however, authenticates against SharePoint on a separate port that is configured to use basic authentication over Secure Sockets Layer (SSL). This is accomplished using SharePoint's capability to extend a site collection over multiple web applications. Using alternative access mappings in SharePoint, all hyperlinks in the SharePoint content direct users back to the primary SharePoint site.

This configuration method offers a greater level of security than the method that accesses SharePoint using Integrated Windows Authentication (NTLM Only). The configuration procedure is, however, more complex. You should review the security measures of your internal network before deciding which method is most appropriate for your environment.

Use this Configuration when...
  • Confluence is not running on a Windows server.
  • Your corporate security policy prohibits the use of NTLM(v1) authentication, which is necessary for the NTLM configuration.
  • Your SharePoint site(s) is/are not configured to use Secure HTTP (HTTPS) and you are concerned about the possibility of packet sniffing or eavesdropping.

If you have not already seen our guide to planning your environment, you can refer to it for information that will help you select the best configuration for your environment.

Caveats

Server Certificate

Enabling SSL requires the installation of a certificate on the SharePoint server. Depending on the way in which you source the certificate, this could involve either an additional financial cost or a number of additional configuration steps.

Installation Instructions

Configuring SharePoint

Use IE7+ when Configuring SharePoint

We recommend that you use Internet Explorer 7 or later to perform the configuration steps described on this page. You may experience unusual behaviour if you use FireFox or other browsers on some SharePoint administrative pages.

Configure all SharePoint Top-Level Sites used by Confluence

You will need to perform these configuration steps for each SharePoint top-level site that is exposed to Confluence.

Step 1: Extend the SharePoint Site to Another IIS Web Site

  1. Log in to SharePoint Central Administration and select the 'Application Management' portal.
  2. In the 'SharePoint Web Application Management' section, select 'Create or extend Web application'.
  3. Select 'Extend an existing Web application'.
  4. Set the 'Web Application' field to the IIS web application that is hosting the SharePoint site you wish to extend.
  5. Fill out the details of the new web application:
    • Ensure that the IIS web site is assigned a unique port that is not currently in use on your SharePoint server.
    • Ensure that 'Allow Anonymous' is set to 'No'.
    • Ensure that 'Use Secure Sockets Layer (SSL)' is set to 'Yes'.
    • Make a note of the 'Zone' that is set for the 'Load Balanced URL'. You will need to know this zone in step 2 below.
  6. Click 'OK'.

Screenshot: Extending the SharePoint site to another IIS web site

Step 2: Configure the IIS Authentication Providers

  1. Go back to SharePoint Central Administation and select the 'Application Management' portal.
  2. In the 'Application Security' section, select 'Authentication providers'.
  3. Click the Zone that you used to extend the SharePoint site in step 1 above.
  4. In the 'IIS Authentication Settings' section, ensure that 'Integrated Windows authentication' is not selected and 'Basic authentication (password is sent in clear text)' is selected.
  5. Click 'Save'.

SSL will secure the password information

Because this endpoint will be using Secure Sockets Layer (SSL), the password will not be sent in clear text even though basic authentication is used.

Screenshot: Editing the IIS authentication settings

Step 3: Configure the Alternate Access Mappings

In this step you will remove the default public URL that SharePoint created during the previous step and replace it with an internal URL mapping.

  1. Go back to SharePoint Central Administration and select the 'Operations' portal.
  2. In the 'Global Configuration' section, select 'Alternate Access Mappings'.
  3. Locate the 'Internal URL' that represents the newly-created IIS web site defined in step 1 above and click the link.
  4. Click the 'Delete' link to remove this mapping.

    Screenshot: Deleting the alternate access mapping



  5. Click 'Add Internal URLs'.
  6. Select the 'Alternate Access Mapping Collection' that represents the root SharePoint site that you are extending.
  7. Set the 'URL protocol, host and port' to the URL that directs to the newly-created IIS web site defined in step 1 above.
  8. Click 'Save'.

    Screenshot: Adding the alternate access mapping

Step 4: Import the SSL Certificate into IIS

In this step you will ensure that your IIS web site is configured for SSL and import an SSL certificate into the IIS web site.

Step 4.1: Make Sure the IIS Web Site is Configured for SSL
  1. Log in to your SharePoint server with a Windows account that has permission to administer IIS.
  2. Run the 'Internet Information Services (IIS) Manager'.
  3. Expand the 'Web Sites' folder and locate the IIS web site that you created in step 1 above. You can identify this web site by looking at the 'Description' field.
  4. Right-click the target web site and select 'Properties'.
  5. Select the 'Directory Security' tab.
  6. In the 'Secure communications' section, click 'Edit...'.
  7. Ensure that the 'Require secure channel (SSL)' and 'Require 128-bit encryption' fields are both selected.

    Screenshot: Requiring SSL



  8. Click 'OK'.
Step 4.2: Obtain or Create a Certificate

SharePoint already accepting SSL?

If your SharePoint Server already accepts SSL traffic, then you already have a certificate installed on your SharePoint server. If this is the case, please skip ahead to step 4.3 below.

You need an X.509 certificate that you can import into IIS. IIS will use the certificate to encrypt the SSL channel and prove the server's identity to clients. In the table below are the two ways of obtaining a certificate.

Disclaimer

Atlassian does not endorse or represent any of the example certificate issuers listed below.

Atlassian cannot accept responsibility for the veracity of any digital certificate issued by a third party. You should ensure that any certificate you use is from a provider that you trust.

Option

Example Provider

Benefit

Drawback

Obtain a certificate from a trusted certificate authority

Thawte Consulting
Verisign

Most major certificate authorities are automatically trusted by most modern operating systems, so no configuration is required on the client to trust your certificate.

The certificate authority may charge a fee for issuing the certificate and/or an annual renewal fee.

Generate your own certificate

x509Builder
Java keytool

Free

Client computers may require configuration to trust your certificate's authenticity.

Step 4.3 Import the Certificate into IIS

Once you have generated or obtained a certificate, you will usually receive:

  • The certificate stored in a file format such as pfx.
  • A password that encrypts the file.

Follow these instructions to import the certificate into IIS:

  1. Copy the certificate file to your SharePoint server.
  2. Log in to your SharePoint server with a Windows account that has permission to administer IIS.
  3. Run the 'Internet Information Services (IIS) Manager'.
  4. Expand the 'Web Sites' folder and locate the IIS web site that you created in step 1 above. You can identify this web site by looking at the 'Description' field.
  5. Right-click the target web site and select 'Properties'.
  6. Select the 'Directory Security' tab.
  7. Click 'Server Certificate...'. The 'Web Server Certificate Wizard' opens:

    Screenshot: Web server certificate wizard



  8. Click 'Next'.
  9. Select 'Import a certificate from a .pfx file' and click 'Next'.
  10. Click 'Browse...' to locate your certificate file and select it.
  11. Click 'Next'.
  12. Enter the 'Password' for your certificate and click 'Next'.
  13. Ensure the 'SSL port' matches the port you selected in step 1 above.
  14. Click 'Next'.
  15. Click 'Next'.
  16. Click 'Finish'.
  17. Go to the SSL-secured web site in your web browser and ensure that it is accessible.

Step 5: Restrict the IIS Web Site to Confluence

As an additional layer of security, you should configure your SSL-secured web site to allow access from the Confluence server only.

Confluence must have a static IP address or DHCP lease reservation

You will only be able to perform this step if your Confluence server has a static IP address. If your Confluence server has a dynamic IP address, then speak to your network administrator about adding a static IP address or a DHCP lease reservation for the Confluence server.

  1. Note the IP address of your Confluence server.
  2. Log in to your SharePoint server with a Windows account that has permission to administer IIS.
  3. Run the 'Internet Information Services (IIS) Manager'.
  4. Expand the 'Web Sites' folder and locate the IIS web site that you created in step 1 above. You can identify this web site by looking at the 'Description' field.
  5. Right-click the target web site and select 'Properties'.
  6. In the 'IP address and domain name restrictions' section, click 'Edit...'.
  7. Ensure that by default, all computers will be 'Denied access'.
  8. Click 'Add...'.
  9. Select the 'Single computer' option.
  10. Enter the IP address of your Confluence server in the 'IP address' field.
  11. Click 'OK'.
  12. Click 'OK'.

Screenshot: IP restriction on IIS web site

Configuring Confluence

Step 1: Trust SharePoint's SSL Certificate

Skip all of step 1 if you obtained a certificate from a trusted CA

If you purchased a certificate from a trusted certificate authority, then your certificate is already trusted by the Confluence server and you can skip this step. Go to step 2 below. If you generated your own certificate or obtained one from a less well-known certificate authority, please follow the steps below.

To configure Confluence to trust the certificate on your SharePoint server, you must add the certificate's public key to the Java runtime's Certificate Authority keystore as described below.

Step 1.1: Create a .cer File

Skip step 1.1 if you already have a .cer file

The certificate's public key must be imported into the Java keystore as a certificate file in .cer file format. If you already have a .cer file you can skip this step and go to step 1.2 below. If you only have a .pfx file and need to create the .cer file, read on!

A simple way to create the required file is to import and export the certificate in and out of the Windows certificate store. This works because the export operation allows you to choose the export format.

The first step is to import the certificate into Windows:

  1. Using a Windows computer, open the Microsoft Management Console by clicking the 'Start' button, selecting 'Run' and then running the command 'mmc.exe'.
  2. In the Microsoft Management Console, select 'Add/Remove Snap-in...' from the 'File' menu.
  3. Click ''Add....
  4. Highlight the 'Certificates' snap-in from the list and click 'Add'.
  5. Ensure that 'My user account' is selected and then click 'Finish'.
  6. Click 'Close'.
  7. Click 'OK'.
  8. Expand the tree from 'Console Root' to 'Certificates - Current User' to 'Personal'.
  9. Right-click 'Personal' and select 'Import...' from the 'All Tasks' menu.
  10. When the 'Certificate Import Wizard' is displayed, click 'Next'.

    Screenshot: The certificate import wizard



  11. Click 'Browse...' and select the .pfx certificate file. (You may need to set the 'Files of type' filter to 'Personal Information Exchange (.pfx, *.p12)*'.
  12. Click 'Next'.
  13. Enter the 'Password' for the certificate.
  14. Ensure that the 'Mark this key as exportable' option is selected.
  15. Click 'Next'.
  16. Click 'Next'.
  17. Click 'Finish'.

At this point, your certificate should appear in the 'Personal' folder of the 'Certificates' snap-in.

Screenshot: Personal certificates

Now you can export the certificate in the desired .cer format:

  1. Right-click the certificate and select 'Export...' from the 'All Tasks' menu.
  2. When the Certificate Export Wizard opens, click 'Next'.
  3. Ensure that the 'No, do not export the private key' option is selected.
  4. Click 'Next'.
  5. Ensure that the 'DER encoded binary X.509 (.CER)' option is selected.
  6. Click 'Next'.
  7. Enter a 'File name' for the exported certificate (such as '{{}}C:\cert.cer').
  8. Click 'Next'.
  9. Click 'Finish'.

Step 1.2: Import the .cer File onto the Confluence Server

We have provided a batch script (see below) for Windows environments. If you are running Confluence on UNIX, please perform the import manually. The batch script uses the Java runtime's keytool command to import the certificate into the required location on the Confluence server. The script will add the certificate to the root Java Secure Sockets Extensions keystore, which is located in your Java Runtime Enviroment's (JRE's) lib\security directory with the name jssecacerts. This is the required location in order for the certificate to be trusted by Confluence.

Requirements

This script assumes the following about your environment:

  • You are using a Confluence stand-alone installation running on the Sun JVM.
  • Your %JAVA_HOME% environment variable has been set correctly.
  • You have copied the .cer file created in step 1.1 above to the C: drive of your Confluence server.

Copy and execute this batch script (Windows) to add the certificate to the keystore:

Step 2: Configure the Alternative URL in Confluence

The final step is to configure your Confluence server to communicate via the new URL you have set up.

  • No labels