Differences

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

--- 710:cms_sharepoint_online_new [2024/04/15 08:20] – [API Permissions] Policnik, Florian
+++ 710:cms_sharepoint_online_new [2024/07/17 07:54] (current) – removed Policnik, Florian
@@ Line 1: / Line 1: @@
-[[:710:cms_configuration|Back to CMS Configuration]]
-====== !!! DRAFT !!! ======
-====== Sharepoint Online ======
-You are able to connect Stages with SharePoint Online. A typical URL to SharePoint Online looks like ''https://companyname.sharepoint.com/''
-===== Example Configuration =====
-<code xml>
-<cms-type name="sharepointonlinegraph">
-    <!-- Global Properties -->
-    <cms-host ident="sharepoint.online.ident" name="https://example.sharepoint.com" displayName="SharePoint Online Example">
-        <!-- Host Properties -->
-        <cms-property name="client.id" value="xxxx-xxxx-xxxx-xxxx-xxxx" />
-        <cms-property name="client.secret" value="xxxxxx" />
-        <cms-property name="tenant.id" value="xxxx-xxxx-xxxx-xxxx-xxxx" />
-        <cms-property name="state.attribute.name" value="_Status" />
-        <cms-property name="link.content.type.name" value="Link to a Document" />
-    </cms-host>
-</cms-type>
-</code>
-===== Host Properties =====
-These configuration properties affect the behavior of one SharePoint Online server.
-*** ** ''Required'' \\
-Properties marked with ** * ** are required for the adapter to work.
-**# ** ''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.
-''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.
-> client.id ** * **
-   * 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]]
-> client.secret ** * **
-  * Description: The client secret, which can be generated after registering the stages application at the Microsoft azure portal website.
-  * Links: [[https://portal.azure.com|Microsoft Azure Portal]]
-> tenant.id ** * **
-  * Description: The tenant id identifies your company when using Microsoft Services. You can get this id at the Microsoft azure portal website.
-  * Links: [[https://portal.azure.com|Microsoft Azure Portal]]
-> loginserver
-  * Default Value: <nowiki>https://login.microsoftonline.com/</nowiki>
-  * 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]]
-> state.attribute.name
-  * Description: This property specifies a column name, which will be used by stages to store the file status.
-> document.content.type.name
-  * 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" />
-</code>
-> link.content.type.name
-  * Default Value: Link to a document
-  * Description: The second content type which is supported by stages.
-  * 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" />
-</code>
-> use.system.account.for.download
-  * Default Value: false
-  * Description: When set to true, files will be downloaded using the system account.
-> sites.selected.scope (since Stages XXX)
-  * 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 XXX for detailed explanation.
-===== 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 ====
-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.
-[[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>
-https://<stages-hostname>/stages/app/files/oauth_callback
-</code>
-  * Microsoft only accepts __https__  expect for testing scenarios on localhost (then __http__ is valid as well)
-  * 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 ===
-If the link to your Stages looks like this
-<code>
-https://stages.example.com/stages/#/workspace/191/_vv/process/process/_h8ijENV8Enq3iqjRPK3spw
-</code>
-then your redirect URI is
-<code>
-https://stages.example.com/stages/app/files/oauth_callback
-</code>
-==== 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 XXX 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 XXX we added the option to use application and delegated permission [[https://learn.microsoft.com/en-us/graph/permissions-reference#sitesreadwriteall|Sites.Selected]]. This is the recommended option.
-=== 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)
-  * 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}}]]
-=== Recommended option: application and delegated permission Sites.Selected (Since Stages XXX) ===
-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)
-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 by PowerShell or GraphAPI:
-== PowerShell ==
-Please refer [[https://pnp.github.io/powershell/cmdlets/Grant-PnPAzureADAppSitePermission.html|documentation]]. For example a grant for an app with clientId ''01234567-8901-2345-6789-012345678901'' might look like:
-<code powershell>
-Grant-PnPAzureADAppSitePermission -AppId "01234567-8901-2345-6789-012345678901" -DisplayName "Stages site/process permission" -Permissions Write -Site https://example.sharepoint.com/sites/process [-Connection <PnPConnection>]
-</code>
-== GraphAPI ==
-Please refer [[https://learn.microsoft.com/en-us/graph/api/site-post-permissions?view=graph-rest-1.0&tabs=http|documentation]]. In this example a HTTP request to grant for an app with clientId ''01234567-8901-2345-6789-012345678901'' might look like:
-First the ID of the SharePoint site have to be found out.
-  * Method: ''POST''
-  * URL: ''<nowiki>https://graph.microsoft.com/v1.0/sites/{id}/permissions</nowiki>''
-    * In the URL replace ''{id}'' with the ID of the SharePoint Site.
-    * e.g.: ''<nowiki>https://graph.microsoft.com/v1.0/sites/companyname.sharepoint.com,d904e4bf-aef2-423b-9922-7fb5d5ac763f,17782e2a-0df3-4933-ba0a-f95f1d9981bc/permissions</nowiki>''
-  * Payload / body:
-<code javascript>
-{
-    "roles": [
-        "write"
-    ],
-    "grantedToIdentities": [
-        {
-            "application": {
-                "id": "01234567-8901-2345-6789-012345678901",
-                "displayName": "Stages site/process permission"
-            }
-        }
-    ]
-}
-</code>
-==== 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 =====
-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>
-https://example.sharepoint.com/sites/steering/Shared Documents/Forms/AllItems.aspx
-</code>
-> Name: The name of this SharePoint Online configuration. This name will be used by Stages to refer to this repository configuration (e.g. in repository plan)
-> Host: This selection field contains an entry for each cms-host section in the Stages configuration file (config.xml). You can select the host for this repository configuration.
-> Site: Define a site parameter for this repository configuration. The site is the path to the location, where your document libraries are located on the SharePoint server. The site is one piece for the complete connection string to the SharePoint server.  > According to the example URL the site-part is **sites/steering**
-This overwrites the **path**  from the URL entered in the configuration file (config.xml).
-Example:
-  * **config.xml**: //<nowiki><cms-host name="https://example.sharepoint.com/sites/brake" /></nowiki>//
-  * Value in **Site**: //sites/steering//
-  * Resulting **URL**: //<nowiki>https://example.sharepoint.com/sites/steering</nowiki>//
-  * The path from the config.xml gets overwritten by the value from Repository Path.
-> Document Library: Defines the name of the document library. The document library is one piece for the complete connection string to the SharePoint server. If your document library contains a space it must be replaced by **%20**  > According to the example URL the Document Library part is **Shared%20Documents**
-> Root Folder: Defines a root folder **inside**  the given document library. Every file linked or uploaded to a repository, which defines a root folder in the configuration, will be **inside**  this root folder.
-> Default Lifecycle Select a lifecycle from the process metamodel as default for files from this repository.
-===== Known Limitations =====
-==== 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 ====
-Creates two versions (one for the creation of a new file/ second for updating the properties)
-==== 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 ====
-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 ====
-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.
-===== 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 ====
-At the moment this public CAs are required:
-  * DigiCert Global Root CA
-    * valid until 10 Nov 2031 00:00:00 GMT
-    * SHA1: A8:98:5D:3A:65:E5:E5:C4:B2:D7:D6:6D:40:C6:DD:2F:B1:9C:54:36
-    * SHA256: 43:48:A0:E9:44:4C:78:CB:26:5E:05:8D:5E:89:44:B4:D8:4F:96:62:BD:26:DB:25:7F:89:34:A4:43:C
-  * DigiCert Assured ID Root G2
-    * Valid unitl: 15 Jan 2038 12:00:00 GMT
-    * SHA1: A1:4B:48:D9:43:EE:0A:0E:40:90:4F:3C:E0:A4:C0:91:93:51:5D:3F
-    * SHA256: 7D:05:EB:B6:82:33:9F:8C:94:51:EE:09:4E:EB:FE:FA:79:53:A1:14:ED:B2:F4:49:49:45:2F:AB:7D:2F:C1:85
-  * Microsoft RSA Root Certificate Authority 2017
-    * Valid until Fri, 18 Jul 2042 23:00:23 GMT
-    * SHA1: 73:A5:E6:4A:3B:FF:83:16:FF:0E:DC:CC:61:8A:90:6E:4E:AE:4D:74
-  * DigiCert Global Root G2
-    * Valid until Fri, 15 Jan 2038 12:00:00 GMT
-    * 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]]