Sharepoint 2013 Integration

Features

The Sharepoint 2013 integration allows users to use the Grape Search to link to items in Sharepoint Site Collections. Grape uses a High Trust SharePoint App to sync the content of sharepoint lists. After the initial sync process it will search for changes in the site collections on a regular (configurable) basis. The Grape Server uses the REST API of Sharepoint. This requires a certificate to be installed at the Sharepoint server. The Grape server will be in possession of the private key of this certificate to be able to sign requests to the API. As the certificate is only used internally between Grape and Sharepoint it is sufficent to use a self signed certificate.

Requirements

Sharepoint Setup

Create a self-signed certificate

  1. Connect to SharePoint Server and start your Internet Information Services (IIS) Manager.

  2. Click on your Servername in the left pane and then click into the Server Certificates on the right side.

    Screenshot Sharepoint Cert 1

    Screenshot Sharepoint Cert 2

  3. In the action pane on the right click “Create Self-Signed Certificate…”

    Screenshot Sharepoint Cert 3

  4. Specify a name for your new Self-Signed Certificate (for example grape)

    Screenshot Sharepoint Cert 4

  5. Doubleclick your newly created Self-Signed Certificate go to the details tab and click “Copy to File…“ and follow the Wizard steps as in the screenshots below

    Screenshot Sharepoint Cert 5

    Screenshot Sharepoint Cert 6

    Screenshot Sharepoint Cert 7

    Screenshot Sharepoint Cert 8

    Screenshot Sharepoint Cert 9

  6. Go Back to your Certificate and right click your newly created Certificate and do an Export (Please note the Password for your grape Administrator)

    Screenshot Sharepoint Cert 10

    Screenshot Sharepoint Cert 11

Create Token Issuer and Root Authority

  1. Make sure the certificate file is on the SharePoint server. Copy it there if necessary.
  2. Download the Installation Script and open it in a PowerShell ISE on the Sharepont Server.
  3. Change $PublicCertPath to the destination of your .cer file.
  4. Change $spurl to any SharePoint SiteCollections (this is only for getting the Context)
  5. Run the Script! (Warning: IISRESET will be performed during Script)
  6. Send the output of the script together with the certificate file and its password to the Grape Administrator.

The Installation Script:

Add-PSSnapin microsoft.sharepoint.powershell -ErrorAction Continue

# Please set the path to the .cer file
$PublicCertPath = "C:\grape\grape.cer"
# Please change the url to point to any SharePoint SiteCollection
$spurl = "https://yoursharepointurl.com"

##############################################################################
$issuerId = ([Guid]"11111111-1111-1111-1111-111111111111").ToString()
$spweb = Get-SPWeb $spurl
$sc = Get-SPServiceContext $spweb.site
$realm = Get-SPAuthenticationRealm -ServiceContext $sc
$certificate = Get-PfxCertificate $publicCertPath
#check if issuerId1 is used
$securitytokenissuers = Get-SPTrustedSecurityTokenIssuer
foreach ($securitytokenissuer in $securitytokenissuers){
    if ($securitytokenissuer.Name -like $issuerId){

        Write-Host "A token issuer with the id $issuerId already exists. Please enter a valid GUID for this token issuer."
        $issuerId  = Read-Host "issuerId"
        break
    }
}

$fullIssuerIdentifier = $issuerId + '@' + $realm

New-SPTrustedSecurityTokenIssuer -Name $issuerId -Certificate $certificate -RegisteredIssuerName $fullIssuerIdentifier -IsTrustBroker

$traexist = Get-SPTrustedRootAuthority -Identity "$($certificate.Subject)_$($certificate.Thumbprint)"
if ($traexist -eq $null){
    New-SPTrustedRootAuthority -Name "$($certificate.Subject)_$($certificate.Thumbprint)" -Certificate $certificate
    iisreset
}
else
{
    Write-host "Information: Trusted Root Authority already exist"
}


Write-Host "Successfully: Created Token Issuer and Root Authority for Grape!" -ForegroundColor Green
Write-Host "Please provide the Grape Administrator with the certificate file and the following variables:" -ForegroundColor Magenta
Write-Host
Write-Host "INTEGRATIONS_SHAREPOINT_2013_REALM: $realm" -ForegroundColor Cyan
Write-Host "INTEGRATIONS_SHAREPOINT_2013_ISSUER_ID: $issuerId" -ForegroundColor Cyan

Please provide the Grape administrator with the certificat and the values mentioned in the script output. Grape will need the values to create access tokens to use for REST API requests to Sharepoint. The tokens will be signed with the privte key in the certificate.

Deploying the Grape App to a Site Collection

In order for Grape to be able to use the REST API of a Site Collection the Grape must be registered within the Site Collection.

  1. Open the Deploy Script in a PowerShell ISE on the Sharepoint Server.
  2. Change the $spurl to the url of the Sharepoint Collection.
  3. Run the script.

Deploy Script:

Add-PSSnapin microsoft.sharepoint.powershell

$spurl = "https://yoursharepointurl.com"

##############################################################################
$spsite = Get-SPsite $spurl
$realm = Get-SPAuthenticationRealm -ServiceContext $spsite
$clientId = "b781cbb2-9054-db12-f88f-08c6e161c199"
$fullIssuerIdentifier = $clientId + "@" + $realm

Register-SPAppPrincipal -Site $spurl -NameIdentifier $fullIssuerIdentifier -DisplayName "Grape"
$appPrincipal = Get-SPAppPrincipal -Site $spurl -NameIdentifier $fullIssuerIdentifier
Set-SPAppPrincipalPermission -Site $spurl -AppPrincipal $appPrincipal  -Scope SiteCollection -Right Read
Write-Host "Successfully: Registered Grape in $url"

Grape Setup

After creating a Token Issuer and Root Authority in Sharepoint you can configure the sharepoint integration by using the Grape django admin interface.

Adding a certificate

Click the Add Certificate button on the Certificate Overview. Screenshot Sharepoint Add Certificate

  • Certificate file: Choose the .pfx Certificate file
  • Certificate password: enter the password for the certificate

You can leave the rest of the fields blank and press Save.

After converting the certificate with the password a new password will be generated to safely store the private key.

Configuring the sharepoint connection

After the certificate you need to create a “sharepoint setup”.

Click the Add SharepointSetup button on the SharepointSetup Overview Screenshot Sharepoint Add SharepointSetup

The following variables need to be set to create access tokens for accessing the Sharepoint REST API.

  • Name: A verbose name for the setup.
  • Certificate: Use the magnifier icon to select the previously installed certificate.
  • Token realm: In single-tenancy mode this is the SharePoint farm ID.
  • Token client id: The Id of the Sharepoint Grape App. defaults to "b781cbb2-9054-db12-f88f-08c6e161c199"
  • Token issuer id: The Id of the Security Token Issuer created with the certificate. - default: "11111111-1111-1111-1111-111111111111"
  • Token lifetime: Lifespan of Grapes access tokens. defaults to 3600seconds
  • Client trust env: Trust environment settings for proxy configuration, default authentication and similar. default: False
  • Client verify: Verify SSL certificates. default: True
  • Client read timeout: Time to wait for the Sharepoint Server to return data. default: 30 seconds.
  • Client connection timeout: Time to wait for the Sharepoint Server to accept the request. default 10 seconds* Client http proxy: optional proxy server for http connections
  • Client https proxy: optioanl proxy server for https connections

At the bottom of the page you have to add hostnames. Users will only be able to create integrations for site collections on those hosts. Screenshot Host inlineform

Further configuration

There are several other variables that can be configured by using the grape configure command:

  • INTEGRATIONS_SHAREPOINT_2013_SYNC_BEAT: Interval in which Sharepoint is checked for changes. default: 60 seconds
  • INTEGRATIONS_SHAREPOINT_2013_RECOVER_BEAT: Interval in which the server tries to recover deactivated site collections. (see Site Collection Recovery) default: 43200 seconds (12h)

There is an additional list of Sharepoint Site Collection URLs and their hosts. Items are added automatically when a user creates an integration and the hostname in the user-supplied url contains an allowed hostname. Item need to be added to this list manually for hostnamed site collections where the hostname is not in the url. This has to be maintained manually.

Site Collection Recovery

When a Sharepoint site collection is not reachable for 100 consecutive sync tasks it will be disabled for further syncs. However, the content of the site collection will still be available in the Grape search. The INTEGRATIONS_SHAREPOINT_2013_RECOVER_BEAT defines an interval in which Grape tests all disabled site collections to see if they are reachable again. If a site collection is not reachable by the recovery task its content will be deleted from the Grape search database (e.g. a Site Collection has been deleted at Sharepoint). All site collections that are available again will be re-enabled for further syncing (e.g. after a longer Sharepoint server maintenance)

User Setup

In order for a User to integrate a Sharepoint Site Collection Grape needs to get her SID from Active Directory. This is why only Users imported from AD can use the Sharepoint Integration.

You can test if Grape can access a Site Collection with your SID by calling this url on your Grape domain. /integrations/sharepoint_2013/authorizations/test/?realm=http://url_to_your_sitecollection

Create a Sharepoint Integration

  • Go to Sharepoint on the Service-Integrations Screen and click “Create a new Integration”.

  • For the first integration of a specific Site Collection you need use the “Connect another account” Button to add the Site Collection. The Url to a Site Collction doesn’t container any _layout or Home.aspx. If you are not sure about the correct url please ask your Sharepoint Administrator.

    Screentshot Sharepoint User1

With an existing account you will see a list of available lists that can be subscribed. Grape supports the most common type of lists such Document lists, Wikis, Calendars, Todo lists, Blogs and Issue Tracker. As Sharepoint lists can be very much customized new list types cannot be integrated automatically. If you miss a list you would like to integrate please report this.