How to connect your Sharepoint?

This setup ensures secure and efficient integration with your SharePoint environment while offering flexible access control based on your organization’s compliance and data governance policies. Two connection options are provided: one for full-tenant access and another for scoped access to specific sites. 

Note: This guide reflects our early-stage configuration for pilot users. The process and required permissions may evolve as we continue to develop our system. 

 

Prerequisites 

Before proceeding, ensure you have: 

• Microsoft 365 with Sharepoint Online. 
• Global Administrator access to your Microsoft 365 tenant. 

Option 1: Full Access 

This is the simplest and quickest setup. Ravical will be granted access to all SharePoint sites in your tenant. However, we only sync content relevant to your use case, no unnecessary data is accessed or retained. 

1. Visit the following URL to grant tenant-wide consent

   https://login.microsoftonline.com/organizations/adminconsent?client_id=90ceb184-b121-481a-ac1b-c3a6956f7b09

   You will be redirected to a Microsoft consent page. 
2. Review the permissions requested by our application.  
3. Click Accept to grant admin consent.  

Note: After accepting, you may see this message: “AADSTS500113: No reply address is registered for the application.” This is expected behavior, consent has been granted correctly. 

Option 2: Scoped Access  

This method limits access to specific SharePoint sites only, offering more granular control. It requires a few extra steps and PowerShell setup. 

Install required modules: 

Install-Module Microsoft.Graph -Scope CurrentUser -Force 

Navigate to the following URL to grant initial consent for scoped access.  

https://login.microsoftonline.com/organizations/adminconsent?client_id=260385f9-c7b6-4af8-8959-b1b7481b1900 

Note: After accepting, you may see this message: AADSTS500113: No reply address is registered for the application. This is expected behavior and indicates that consent was successful.

At this point, Ravical has no access to any sites yet. 

To grant access to your knowledge base, you'll need to grant permissions on the necessary sites through the Microsoft Graph API. For your convenience we've automated these steps with a Powershell script. Follow these steps to grant access to specific sites:

1. The below PowerShell script automates all the steps to grant permissions on the necessary sites. Create a .ps1 file and paste in the full script provided. 

   <# The list of sites to grant access to, please update this list as needed #>
   $SiteNames = @(
     "KnowledgeBase"
   )
   $RavicalAppId = "260385f9-c7b6-4af8-8959-b1b7481b1900"
   
   function GrantAccessToSites() {
     AssertModuleInstalled "Microsoft.Graph" "Install-Module Microsoft.Graph -Scope CurrentUser -Force"
   
     Write-Host "Connecting to Microsoft Graph for tenant. Please log in to your admin account in the desired tenant through the browser."
     Connect-MgGraph -Scopes "Sites.Read.All", "Sites.FullControl.All" -ContextScope Process -NoWelcome
     $SiteDomain = (Get-MgSite -SiteId "root").webUrl.Replace("https://", "")
   
     AssertServicePrincipalExistsAndGetObjectId -appId $RavicalAppId -tenantId $(Get-MgContext).TenantId
   
     ## Loop through each site and grant access
     $grantedSites = @()
     foreach ($SiteName in $SiteNames) {
       Write-Host "Fetching details for ${SiteDomain}:/sites/${SiteName}"
       $Site = Get-MgSite -SiteId "${SiteDomain}:/sites/${SiteName}"
       if ($Site) {
         GrantAccessToSingleSite -siteId $Site.Id -appId $RavicalAppId
         $grantedSites += $Site.Id
       }
     }
   
     Write-Host ""
     Write-Host "✅ Script completed successfully. Ravical has been granted access to the following sites:" -ForegroundColor Green
     Write-Host ""
     foreach ($siteId in $grantedSites) {
       Write-Host "$siteId" -ForegroundColor Cyan
     }
     Write-Host ""
   }
   
   function AssertModuleInstalled($moduleName, $instructions) {
     $module = Get-Module -ListAvailable -Name $moduleName
     if ($null -eq $module) {
       Write-Error "
       Module $moduleName is not installed, please install it first by running:
         $instructions
       "
       exit 1
     }
   }
   
   function AssertServicePrincipalExistsAndGetObjectId($appId, $tenantId) {
     $servicePrincipal = Get-MgServicePrincipal -All -Filter "AppId eq '$appId'"
     if ($servicePrincipal.Count -eq 0) {
       Write-Error "
       Service principal $appId does not exist, please visit the following URL to grant access:
       https://login.microsoftonline.com/$tenantId/adminconsent?client_id=$appId&redirect_uri=https://api.prod.ravical.com/api/v1/health
       "
       exit 1
     }
     return $servicePrincipal.Id
   }
   
   function GrantAccessToSingleSite($siteId, $appId) {
     $existingPermissions = Get-MgSitePermission -SiteId $siteId | Where-Object { $_.GrantedToIdentitiesV2.Application.Id -eq $appId }
     if ($existingPermissions) {
       Write-Host "Permission already exists for $siteId"
       return
     }
   
     $params = @{
       roles               = @(
         "read"
       )
       grantedToIdentities = @(
         @{
           application = @{
             id          = $appId
             displayName = "Ravical"
           }
         }
       )
     }
   
     New-MgSitePermission -SiteId $siteId -BodyParameter $params
   }
   
   GrantAccessToSites

2. Edit the script to list the Sharepoint sites to which you want to grant access. 

   Adapt the part that says <# The list of sites to grant access to, please update this list as needed #> with the names of your sites.

   For example: 

   $SiteNames = @( 
   "Knowledge", 
   "SupportDocs"
   ) 

3. Run the script from PowerShell. You will be prompted to authenticate with your admin account. Your admin credentials will only be used in the context of this PowerShell script, they will not be linked to Ravical in any way.