Gebruik van SharePoint gegevens

Om onze functionaliteiten te kunnen bieden, heeft Lynk toegang nodig tot de gebruikers en documenten op een afgesloten SharePoint site van uw bedrijf. Dit doen we door tijdens de technische onboarding samen met u deze koppeling op te zetten. Hierin geeft u aan Lynk’s Microsoft applicatie toestemming om toegang te krijgen tot een SharePoint site, waarop Lynk alle documenten kan bewaren. Na deze koppeling is Lynk klaar voor gebruik en zal vervolgens Microsoft’s Graph API gebruikt worden om alle functionaliteiten van Lynk te kunnen bieden. De volgende permissies worden tijdens het koppelen gevraagd.

email, openid, profile en Read worden gebruikt om authenticatie van gebruikers via Microsoft mogelijk te maken.
Selected wordt gebruikt om toegang te krijgen tot een specifieke SharePoint site. Deze site wordt geselecteerd door uzelf, via de methode hieronder beschreven in “Opzetten koppeling SharePoint en Lynk”. In de geselecteerde site kan informatie over bestanden worden gesynchroniseerd tussen Lynk en SharePoint. Gebruikers kunnen in Lynk bestanden uploaden, verplaatsen, hernoemen en verwijderen, en deze permissie is nodig om al die operaties automatisch ook in SharePoint toe te passen.

Zie ook deze link voor Microsoft’s complete permissieoverzicht: https://learn.microsoft.com/en-us/graph/permissions-reference

Opslag van SharePoint gegevens

Lynk slaat een aantal zaken op in haar eigen databases om het platform te laten werken. Deze zijn, in het kort:

Een selecte hoeveelheid persoonsgegevens. Dit zijn de namen en emailadressen van gebruikers voor de koppeling met het Microsoft-account.
Naam en locatie van de SharePoint Site om synchronisatie met Lynk te voorzien.
Namen, locaties en aanpassingen van de bestanden in de gekoppelde SharePoint Site, om bestandsbeheer mogelijk te maken vanuit Lynk.
Bestandsinhoud om AI-functionaliteiten te faciliteren.

Opzetten koppeling SharePoint en Lynk

Lynk synchroniseert alle bestanden met een SharePoint site die bij u in de organisatie bestaat. Dit wordt mogelijk gemaakt door de volgende stappen uit te voeren:

Voorbereiding: U maakt een nieuwe, afgeschermde SharePoint site aan in uw organisatie.
Administrator app: U zorgt ervoor dat er in uw Microsoft-organisatie een app is die toestemming aan Lynk kan gegeven tot deze specifieke site.
Koppeling: U geeft met deze app toestemming aan Lynk om bestanden te synchroniseren naar uw SharePoint site.

Deze stappen staan hieronder uitgebreid beschreven, en tijdens de technische onboarding lopen we met u door deze stappen heen.

1. Voorbereiding

Om het opzetten zo makkelijk mogelijk te maken, willen we u vragen om de volgende punten voor te bereiden.

Voor het opzetten heeft u een administrator account nodig van de Microsoft omgeving. Met dit administrator account maakt u een Microsoft Office 365-Groep aan. Het administrator account moet Site Admin zijn van deze groep, verder heeft deze groep geen leden nodig en mag deze Privé zijn. Na het doorlopen van de stappen in dit document, zal Lynk toegang hebben tot de SharePoint site die bij deze groep hoort en deze gebruiken om bestanden mee te synchroniseren. Noteer de URL van de SharePoint site die hoort bij de Microsoft Groep die u heeft aangemaakt. Deze is in de vorm: “https://mijn-organisatie.nl/sites/voorbeeld-site”
U krijgt van ons een PowerShell script aangeleverd waarmee u makkelijk toestemming kunt geven aan Lynk tot de SharePoint site. Om het script te kunnen uitvoeren is PowerShell 7 nodig. Let op, de meeste Windows computers komen met PowerShell 5, met deze versie kunt u de technische koppeling niet voltooien. Om te controleren welke versie van PowerShell u heeft, kunt u PowerShell openen en het volgende commando uitvoeren:

$PSVersionTable.PSVersion

Onder “Major” moet “7” staan. Is dit niet het geval, dan kunt u PowerShell 7 installeren door de instructies hier te volgen: https://learn.microsoft.com/nl-nl/powershell/scripting/install/installing-powershell-on-windows?view=powershell-7.4 en de stappen met “winget” te volgen. PowerShell 5.1 en PowerShell 7 bestaan naast elkaar, u bent hiermee dus niet uw bestaande PowerShell installatie aan het verwijderen of aanpassen. Na het installeren van PowerShell 7, sluit u PowerShell, start u PowerShell 7 op, en kunt u de geïnstalleerde versie nogmaals controleren met het commando hierboven. In PowerShell moet de module “PnP.PowerShell” geïnstalleerd zijn. Wanneer dat niet het geval is, kunt u deze installeren door:

Install-Module –Name PnP.PowerShell

Het PowerShell script dat in stap 3 wordt gebruikt is hier te vinden

param (
    # Site Url, in the form `https://*.sharepoint.com/sites/*`
    [string]$Site,
    # App ID, the ID of the Lynk App registration
    [string]$AppId="30259137-bd24-44f9-982d-a753b897686a",
    # PnP Entra ID App For Interactive Login with Sites.FullControl permissions
    [string]$FullControlAppId
)

# Stop on first command that returns an error
$ErrorActionPreference = "Stop"

# Check if we are running PowerShell 7
$Version = $PSVersionTable.PSVersion
if ($Version.Major -ne "7") {
    Write-Host -f Red "Detected PowerShell $($Version.Major).$($Version.Minor). Version 7 is required."
    Break
}

# Check if PnP.PowerShell is installed
$PnP = Get-InstalledModule -Name PnP.PowerShell
if ($PnP -eq $null) {
    Write-Host -f Red "Could not find PnP.PowerShell module. Make sure it is installed."
    Write-Host "Use `Get-InstalledModule -Name PnP.PowerShell` to check if it is installed."
    Break
}

# Read parameters from terminal prompt, if they are not passed to the script directly
if ($Site -eq "") {
    $Site = Read-Host -Prompt "Please enter the Site URL"
}
if ($FullControlAppId -eq "") {
    $FullControlAppId = Read-Host -Prompt "Please enter the Full Control App ID"
}

# Connect to the SharePoint site
Connect-PnPOnline -Url $Site -Interactive -ClientId $FullControlAppId

# Grant the Write permission to the App with id AppId
Grant-PnPAzureADAppSitePermission -AppId $AppId -DisplayName "Lynk" -Permissions Write

# Get Tenant info
$TenantId = Get-PnPTenantId
if ($TenantId -eq "") {
    Write-Host -f Red "Error: TenantId is empty!"
    Exit
}

# Parse the Tenant domain (<>.sharepoint.com)
$RootSiteUrl = $Site.split("https://")[1]
$TenantDomain = $RootSiteUrl.split("/")[0]
if ($TenantDomain -eq "") {
    Write-Host -f Red "Error: TenantDomain is empty! (tried to detect from '$Site')"
    Exit
}

# Get the Site ID for the SharePoint Site
$SiteObj = Get-PnPSite -Includes ID
if ($SiteObj.ID -eq "") {
    Write-Host -f Red "Error: SiteObj.ID is empty!"
    Exit
}

# Get the Web ID for the SharePoint Site
$WebObj = Get-PnPWeb -Includes ID
if ($WebObj.ID -eq "") {
    Write-Host -f Red "Error: WebObj.ID is empty!"
    Exit
}

# Generate the ID
$ID = $TenantDomain + "," + $SiteObj.ID + "," + $WebObj.ID

$Result = "siteId=" + $ID + "&tenantId=" + $TenantId

# Print the output
Write-Host -f Green "Successfully granted permission to Lynk!"
Write-Host -f Green "Copy this text below and paste it in the 'PowerShell output' field in the setup"
Write-Host -f Green "==================="
Write-Host ""
Write-Host $Result
Write-Host ""

2. Administrator app

Vervolgens verleent u toestemming aan de Lynk applicatie tot de geselecteerde site. Microsoft vereist dat dit gebeurt via een app in uw organisatie die permissies heeft om toegang tot sites te verlenen (AllSites.FullControl permissie scope). Als u zo'n app nog niet heeft, kunt u er gemakkelijk eentje aanmaken door dit commando uit voeren:

Register-PnPEntraIDAppForInteractiveLogin -ApplicationName "PnP Entra ID App For Interactive Login" -SharePointDelegatePermissions AllSites.FullControl -Tenant <primaryDomain>

Het <primaryDomain> gevonden kan worden in Entra.

3. Koppeling

Voor het koppelen navigeert u naar https://app.eu.lynk.so, logt u in met uw account en klikt u op de homepage op “Ga naar setup”. U voert daar de App ID van de administrator app uit stap 2 in, en de SharePoint site URL uit stap 1 (zie Figuur 1 en 2 in de bijlage).

Wanneer u doorklikt, wordt een PowerShell commando voor u gegenereerd. Met dit commando runt u het script dat u van ons hebt gekregen. Door dit script uit te voeren, geeft u via de administrator app toestemming aan de Lynk app om op de SharePoint site documenten te synchroniseren. Het kan zijn dat u een of meerdere keren om toestemming wordt gevraagd in een interactief Microsoft login scherm in uw browser. Het PowerShell script print output die u in het invoerveld weer moet invullen (zie Figuur 3 in de bijlage).

Wanneer u hierna doorklikt, komt u op een pagina waar belangrijke gegevens nogmaals samengevat staan, en waar u kunt klikken op “Koppel met Microsoft” (zie Figuur 4 in de bijlage). U wordt naar een Microsoft login geleidt en logt in met het administrator account. Nadat u bent ingelogd, wordt u gevraagd de hierboven genoemde permissies te verlenen aan Lynk (zie Figuur 5 in de bijlage). Wanneer dit mogelijk is, selecteer dan ook “Consent on behalf of your organisation”, zodat andere gebruikers dit niet nog los hoeven te doen. Zodra u dit heeft gedaan, is Lynk gekoppeld aan de SharePoint site.

Nadat dit alles succesvol is doorlopen, kunt u indien gewenst de administrator app “PnP Entra ID App For Interactive Login” die u hebt aangemaakt in stap 2 weer veilig verwijderen.

Troubleshooting

Connectie error naar SharePoint toe

Microsoft heeft vaak enkele uren nodig na het aanmaken van een nieuwe SharePoint groep of site om alles klaar te zetten. Wacht een tijd en probeer het daarna nogmaals.