Differences

This shows you the differences between two versions of the page.

--- 710:cms_sharepoint_online [2024/03/06 01:32] – created - external edit 127.0.0.1
+++ 710:cms_sharepoint_online [2024/09/26 09:35] (current) – Policnik, Florian
@@ Line 1: / Line 1: @@
 [[:710:cms_configuration|Back to CMS Configuration]]
-===== Sharepoint Online =====
+====== Sharepoint Online ======
-You are able to connect Stages with SharePoint Online. A typical URL to SharePoint Online looks like ''https://companyname.sharepoint.com/''
+You are able to connect Stages with SharePoint Online. A typical URL to SharePoint Online looks like:
-==== Example Configuration ====
+''%%https://companyname.sharepoint.com/%%''
+===== Example Configuration =====
 <code xml>
@@ Line 19: / Line 21: @@
     </cms-host>
 </cms-type>
 </code>
-==== Host Properties ====
+===== Host Properties =====
 These configuration properties affect the behavior of one SharePoint Online server.
-*** ** ''Required'' \\
+*** ** ''Required'' \\  Properties marked with ** * ** are required for the adapter to work.
-Properties marked with ** * ** are required for the adapter to work.
-**# ** ''Required but can also be set in web-application'' \\
+**# ** ''Required but can also be set in web-application'' \\  Properties marked with ** # ** are required but can also be set in the //File Management// section in the Stages web-application as well. The value entered in the web-application overrides the one from the config.xml.
-Properties marked with ** # ** are required but can also be set in the //File Management// section in the Stages web-application as well. The value entered in the web-application overrides the one from the config.xml.
-''Required but with default'' \\
+''Required but with default'' \\  Properties marked with are required, but there is a default value. This values can be overridden by configuring it in the config.xml.
-Properties marked with are required, but there is a default value. This values can be overridden by configuring it in the config.xml.
 > client.id ** * **
-   * Description: The client id of the stages application, which has to be registered at the Microsoft azure portal website.
+  * Description: The client id of the stages application, which has to be registered at the Microsoft azure portal website.
   * Links: [[https://portal.azure.com|Microsoft Azure Portal]]
@@ Line 53: / Line 50: @@
 > loginserver
-  * Default Value: <nowiki>https://login.microsoftonline.com/</nowiki>
+  * Default Value: %%https://login.microsoftonline.com/%%
   * Description: The URL to the login server used for OAuth2 authentication. Stages appends /oauth2/v2.0/authorize , to authorize the access. For receiving tokens, /oauth2/v2.0/token will be appended to the login server address.
   * Links: [[https://oauth.net/|More about OAuth]]
-> scope
-  * Default Value: offline_access User.Read Sites.ReadWrite.All
-  * Links: [[https://docs.microsoft.com/en-us/graph/permissions-reference|More about Scopes and Permissions]]
 > state.attribute.name
@@ Line 70: / Line 62: @@
   * Default Value: Document
   * Description: Name of the **document**  content type. Sharepoint supports multiple content types but stages only supports the default type for documents.
   * Since Stages 7.5.6.2, 7.6.2.4 and 7.7.0.0 it is possible to define multiple content types. Separate them with a #. For example:
 <code xml>
 <cms-property name="document.content.type.name" value="Document#MyDocument#RuleDocument" />
@@ Line 81: / Line 74: @@
   * Known Issue: Typo in Default Value. Has to be Link to a **D**ocument
   * Since Stages 7.5.6.2, 7.6.2.4 and 7.7.0.0 it is possible to define multiple link types. Separate them with a #. For example:
 <code xml>
 <cms-property name="link.content.type.name" value="Link to a document#My Link to a document#Rule Link to a document" />
@@ Line 90: / Line 84: @@
   * Description: When set to true, files will be downloaded using the system account.
-==== Azure Portal ====
+> sites.selected.scope (since Stages 7.10.7.0)
+  * Default Value: false
+  * Description: When set to true, Stages uses application permission Sites.Selected for system user and Sites.Selected delegated permission for Stages user. Please refer chapter "Application and delegated permission Sites.Selected" for detailed explanation.
+==== Proxy configuration (since Stages 7.10.10.0) ====
+Stages can communicate with SharePoint Online through a proxy. Fill in the ''proxy.scheme'', ''proxy.hostname'' and ''proxy.port'' host properties to use a proxy. Otherwise no proxy is used.
+> proxy.scheme
+  * Default value empty (no proxy)
+  * Possible values: http, https
+  * Description: The type of proxy to use.
+> proxy.hostname
+  * Default value empty (no proxy)
+  * Example values: proxy.example.com or 10.1.2.3
+  * Description: Which proxy host to use.
+> proxy.port
+  * Default value empty (no proxy)
+  * Example values: 3128
+  * Description: Which proxy port to use.
+> proxy.username
+  * Default value is empty (proxy doesn't require authentication).
+  * Example values: username
+  * Description: The username to use for authentication on the proxy.
+> proxy.password
+  * Default value is empty (proxy doesn't require authentication)
+  * Example values: secretPassword
+  * Description: The password to use for authentication on the proxy.
+===== Azure Portal =====
 The integration uses [[https://learn.microsoft.com/en-us/graph/overview|Microsoft Graph API]]. To be able to use the API it is required to [[https://learn.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app#register-an-application|register and configure Stages as Azure App]].
-=== Authentication ===
+{{ :710:azure_overview.png?direct }}
+  * Value of "Application (client) ID" is cms-property ''client.id''
+  * Value of "Directory (tenant) ID" is cms-property ''tenant.id''
+==== Authentication ====
 Every application registered at the Microsoft azure portal can register **Redirect URIs**  in the //Authentication//  section of the applications registration page shown in the picture below.
@@ Line 100: / Line 138: @@
 [[https://doc.stagesasaservice.com/lib/exe/detail.php?id=74:cms_sharepoint_online&media=cms:azure_portal_redirect_urls.png|{{:cms:azure_portal_redirect_urls.png}}]]
-For the authentication process to work, you have to add the following redirect for **Web**  to the list:<code>
+For the authentication process to work, you have to add the following redirect for **Web**  to the list:
+<code ->
 https://<stages-hostname>/stages/app/files/oauth_callback
 </code>
@@ Line 109: / Line 147: @@
   * Stages-hostname: Hostname of the server, users can access the Stages application. If Stages does not run on standard https port (443) you have to specify it.
-== Example ==
+=== Example ===
 If the link to your Stages looks like this
-<code>
+<code ->
 https://stages.example.com/stages/#/workspace/191/_vv/process/process/_h8ijENV8Enq3iqjRPK3spw
 </code>
 then your redirect URI is
-<code>
+<code ->
 https://stages.example.com/stages/app/files/oauth_callback
 </code>
+==== API Permissions ====
-=== API Permissions ===
+In addition to the Redirect URIs, the application needs [[https://docs.microsoft.com/en-us/graph/permissions-reference|permissions]] for file handling. Up to Stages version 7.10.6.1 we had the option to use delegated [[https://learn.microsoft.com/en-us/graph/permissions-reference#sitesreadwriteall|Sites.ReadWrite.All]] permission. Because of backward compatibility this is the default behavior. With Stages version 7.10.7.0 we added the option to use application and delegated permission [[https://learn.microsoft.com/en-us/graph/permissions-reference#sitesselected|Sites.Selected]]. This is the recommended option. There is a in detail explanation in [[https://learn.microsoft.com/en-us/sharepoint/dev/sp-add-ins-modernize/understanding-rsc-for-msgraph-and-sharepoint-online|Microsoft documentation]].
-In addition to the Redirect URIs, the application needs [[https://docs.microsoft.com/en-us/graph/permissions-reference|permissions]] for file handling in behalf of the user. The permissions are all of the type [[https://learn.microsoft.com/en-us/graph/permissions-overview?tabs=http#delegated-permissions|delegated]]:
+=== Default option: Delegated permission Sites.ReadWrite.All ===
+On this option Stages act in behalf of the user. The permissions are all of the type [[https://learn.microsoft.com/en-us/graph/permissions-overview?tabs=http#delegated-permissions|delegated]]:
   * offline_access (Microsoft Graph, type delegated)
-  * Sites.ReadWrite.All (Microsoft Graph, type delegated)
   * User.Read (Microsoft Graph, type delegated)
+  * Sites.ReadWrite.All (Microsoft Graph, type delegated)
 In some cases an **admin consent is required**. This can be done by a Global Administrator, an Application Administrator, or a Cloud Application Administrator. More information in [[https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/grant-admin-consent|Azure documentation]].
 The picture below shows, how this should look like:
-[[https://doc.stagesasaservice.com/lib/exe/detail.php?id=74:cms_sharepoint_online&media=cms:azure_permissions.png|{{:cms:azure_permissions.png}}]]
+{{ :cms:azure_permissions.png?direct }}
-=== Certificates & secrets ===
+=== Recommended option: Application and delegated permission Sites.Selected (Since Stages 7.10.7.0) ===
-It is required to generate a client secret for Stages. It's recommended to choose expire never or a long duration. If the secret expires it must be changed in Stages and all users have to re-authenticate.
+To active this option the setting ''sites.selected.scope'' has to be set to ''true'' in the xml host properties:
+<code xml>
+<cms-property name="sites.selected.scope" value="true" />
+</code>
+On this option Stages acts with Azure [[https://learn.microsoft.com/en-us/graph/permissions-overview?tabs=http#application-permissions|application permission]] in case it performs action like fill caches. In case a user performs e.g. a file upload action the Azure [[https://learn.microsoft.com/en-us/graph/permissions-overview?tabs=http#delegated-permissions|delegated permission]] for this user will be used. The used permission is in both cases [[https://learn.microsoft.com/en-us/graph/permissions-reference#sitesselected|Sites.Selected]].
+  * offline_access (Microsoft Graph, type delegated)
+  * User.Read (Microsoft Graph, type delegated)
+  * Sites.Selected (Microsoft Graph, type delegated)
+  * Sites.Selected (Microsoft Graph, type application)
+The picture below shows, how this should look like:
+{{ :710:azure_permissions_sites_selected.png?direct }}
+For this option an **admin consent is required**. This can be done by a Global Administrator, an Application Administrator, or a Cloud Application Administrator. More information in [[https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/grant-admin-consent|Azure documentation]].
+In addition for the ''Sites.Selected'' permissions an Global Administrator have to select the specific SharePoint sites and give "write" access. This can be done via PnP PowerShell or Microsoft Graph PowerShell SDK.
+== PnP PowerShell ==
+The PnP PowerShell offers a [[https://pnp.github.io/powershell/cmdlets/Grant-PnPAzureADAppSitePermission.html|command]] to grant the permission. [[https://pnp.github.io/powershell/articles/installation.html|PnP PowerShell]] must be installed. The user must be an Azure administrator. In this example we're granting access for Stages app with client ID ''11111111-1111-1111-1111-111111111111'' to SharePoint Online Site ''%%https://example.sharepoint.com/sites/steering%%''.
+<code powershell>
+Grant-PnPAzureADAppSitePermission -AppId "11111111-1111-1111-1111-111111111111" -DisplayName "Stages" -Permissions Write -Site "https://example.sharepoint.com/sites/steering"
+</code>
+== Microsoft Graph PowerShell SDK ==
+The [[https://learn.microsoft.com/en-us/powershell/microsoftgraph/installation?view=graph-powershell-1.0|Microsoft Graph PowerShell SDK]] must be installed. The user must be an Azure administrator. In this example we're granting access for Stages app with client ID ''11111111-1111-1111-1111-111111111111'' to SharePoint Online Site ''%%https://example.sharepoint.com/sites/steering%%''.
+Please notice that site ''%%https://example.sharepoint.com/sites/steering%%'' have to be separeted into ''example.sharepoint.com'' and ''/sites/steering'' and have to be combined again with '':'' as separator: ''%%example.sharepoint.com:/sites/steering%%''
+<code powershell>
+Import-Module Microsoft.Graph.Sites
+# Connect PowerShell to Azure
+Connect-MgGraph
+# Find SiteId
+$site = Get-MgSite -SiteId "example.sharepoint.com:/sites/steering"
+# Write permission for Stages app
+$params = @{
+    roles               = @("write")
+    grantedToIdentities = @(
+        @{application = @{
+                id          = "11111111-1111-1111-1111-111111111111"
+                displayName = "Stages"
+            }
+        }
+    )
+}
+New-MgSitePermission -SiteId $site.id -BodyParameter $params
+# Disconnect PowerShell from Azure
+Disconnect-MgGraph
+</code>
+In this PowerShell script this two Microsoft Graph API endpoints are used:
+  * [[https://learn.microsoft.com/en-us/graph/api/site-get?view=graph-rest-1.0&tabs=http#access-a-site-by-server-relative-url|Get a site resource]]
+  * [[https://learn.microsoft.com/en-us/graph/api/site-post-permissions?view=graph-rest-1.0&tabs=http|Create permission]]
+==== Certificates & secrets ====
+It is required to generate a client secret for Stages. It's recommended to choose expire never or a long duration. If the secret expires it must be changed in Stages and all users have to re-authenticate.
 [[https://doc.stagesasaservice.com/lib/exe/detail.php?id=74:cms_sharepoint_online&media=cms:azure_certificates_secrets.png|{{:cms:azure_certificates_secrets.png}}]]
-==== Repository Configuration ====
+===== Repository Configuration =====
-Access to SharePoint Online projects can be configured in Stages processes via “Management > File Management > Repositories”. [[https://doc.stagesasaservice.com/lib/exe/detail.php?id=74:cms_sharepoint_online&media=cms:spo-repository.png|{{  :cms:spo-repository.png  }}]]
+Access to SharePoint Online projects can be configured in Stages processes via “Management > File Management > Repositories”. [[https://doc.stagesasaservice.com/lib/exe/detail.php?id=74:cms_sharepoint_online&media=cms:spo-repository.png|{{ :cms:spo-repository.png }}]]
-If you go to the document library with your browser you will get a URL like this. We will use it in this example.<code>
+If you go to the document library with your browser you will get a URL like this. We will use it in this example.
+<code ->
 https://example.sharepoint.com/sites/steering/Shared Documents/Forms/AllItems.aspx
 </code>
@@ Line 167: / Line 274: @@
 Example:
-  * **config.xml**: //<nowiki><cms-host name="https://example.sharepoint.com/sites/brake" /></nowiki>//
+  * **config.xml**: //%%<cms-host name="https://example.sharepoint.com/sites/brake" />%%//
   * Value in **Site**: //sites/steering//
-  * Resulting **URL**: //<nowiki>https://example.sharepoint.com/sites/steering</nowiki>//
+  * Resulting **URL**: //%%https://example.sharepoint.com/sites/steering%%//
   * The path from the config.xml gets overwritten by the value from Repository Path.
@@ Line 178: / Line 285: @@
 > Default Lifecycle Select a lifecycle from the process metamodel as default for files from this repository.
-==== Known Limitations ====
+===== Known Limitations =====
-=== Behavior of Lock/Unlock ===
+==== Behavior of Lock/Unlock ====
 Currently, the graph API only supports checkin/checkout and no Undo-Checkout. So for every lock/unlock a new version of that file is created in sharepoint online.
-=== Initial commit ===
+==== Initial commit ====
 Creates two versions (one for the creation of a new file/ second for updating the properties)
-=== Set State ===
+==== Set State ====
 After setting the state of a Sharepoint Online document, the assignment to the Stages user gets lost. The modifier will be the Sharepoint Online user instead of the Stages user.
-=== Major / Minor Version ===
+==== Major / Minor Version ====
 The Graph API, wich is used by the SharePoint Online Adapter, does currently not support setting major/minor versions when uploading a file.
-=== Action before authentication ===
+==== Action before authentication ====
 If the current user is not authenticated yet and performs an action, the authentication dialog will be opened. After the authentication the user has to performs the action again.
+==== Internet Access ====
-==== Troubleshooting ====
+  - Stages application technical limitation: Proxy network won’t work to SharePoint online, it will work to direct internet access
+  - We do not support the indirect route via a proxy. The SharePoint Online integration requires direct access to [[https://login.microsoftonline.com/]] and [[https://graph.microsoft.com]]
-=== Error AADSTS50011: The reply URL specified in the request does not match the reply URLs configured for the application ===
+===== Troubleshooting =====
+==== Error AADSTS50011: The reply URL specified in the request does not match the reply URLs configured for the application ====
 Check the Redirect URI in Azure Portal
-=== Unknown certificates ===
+==== Unknown certificates ====
 At the moment this public CAs are required:
@@ Line 226: / Line 337: @@
     * SHA1: DF:3C:24:F9:BF:D6:66:76:1B:26:80:73:FE:06:D1:CC:8D:4F:82:A4
     * SHA256: CB:3C:CB:B7:60:31:E5:E0:13:8F:8D:D3:9A:23:F9:DE:47:FF:C3:5E:43:C1:14:4C:EA:27:D4:6A:5A:B1:CB:5F
 [[https://www.digicert.com/kb/digicert-root-certificates.htm|Download DigiCert-Certificates]]
 [[https://www.microsoft.com/pkiops/Docs/Repository.htm|Download Microsoft-Certificate]]