Setting up Sharepoint on Azure AD - how to set up permissions
We are trying to use the Sharepoint Online Integration component but we are having trouble configuring it. I feel that we are missing some steps while adding the application to the Azure AD.
It would be really useful if someone could guide me step-by-step on how to do that, what permissions to give to the app, etc.
I have attached screeshots from azure AD and also from prpc.
Accepted Solution
Dynamic Credit
NL
After some research we have come to an understanding of how to use SharePoint online from Pega. Following are our findings.
There are several ways in which you can connect Pega to SharePoint Online.The first one is using the existing Pega component and the other is through a custom connector using the Microsoft Graph API.
Pega component
The Pega component can be found here.
In order to make it work, a new SharePoint Online add-in needs to be registered by following the instructions in the SharePoint Online Admin Guide.docx
Once the add-in is registered, proceed to add the component to Pega by using the Designer Studio -> Application -> Distribution -> Import. Once it is added, configure it as described in the SPOnline component documentation.docx document.
After some research we have come to an understanding of how to use SharePoint online from Pega. Following are our findings.
There are several ways in which you can connect Pega to SharePoint Online.The first one is using the existing Pega component and the other is through a custom connector using the Microsoft Graph API.
Pega component
The Pega component can be found here.
In order to make it work, a new SharePoint Online add-in needs to be registered by following the instructions in the SharePoint Online Admin Guide.docx
Once the add-in is registered, proceed to add the component to Pega by using the Designer Studio -> Application -> Distribution -> Import. Once it is added, configure it as described in the SPOnline component documentation.docx document.
The SharePoint add-in only supports the OAuth2 Authorization Code flow which is interactive. The whole flow is described here. Since the goal is to have the component upload documents using a single service account, an operator would have to perform the first step manually. Once that step is completed and you have an authorization code, an agent can then be scheduled to request the access token and to keep it valid by using the refresh token.
There are two main steps to get the access code. A get call to the SharePoint authorization endpoint as in the example below. Once the call is made, the user will be asked to login and give permissions to the add-in to perform the requested operation. After the user logs in and gives permission, an authorization code is returned. The authorization code is short lived (several minutes).
https://mysharepoint.sharepoint.com/sites/{my-site}/_layouts/OAuthAuthorize.aspx?
client_id={client_id}&
scope=Web.Read&
response_type=code&
redirect_uri={url_encoded_redirect_url}
- the endpoint should be the SharePoint site/subsite where the add-in was registered followed by /_layouts/OAuthAuthorize.aspx
- client_id - the client id of the SharePoint add-in that you get after the registration.
- scope - the type of operation that you want authorization to perform (Web.Read - read permissions on the site level). You can find the list of scopes in the flow description article and the scope description in this article.
- response_type - what type of response to expect. It should be code, since you are requesting an authorization code.
- redirect_uri - the reply/redirect uri that was configured when the add-in was registered
A post call to the Access Control Service with the authorization code in order to get an access and a refresh token. The result of the call is an access and a refresh token. The access token can be used to make calls to the API. The refresh token can be used to request another access token once the first is expired. This step of the process is not interactive.
https://accounts.accesscontrol.windows.net/{realm}/tokens/OAuth/2
content-type: application/x-www-form-urlencoded
grant_type=authorization_code
code={authorization_code}
redirect_uri={redirect_uri}
client_id={client_id}@{realm}
client_secret={client_secret}
resource={audience_principal_id}/mysharepoint.sharepoint.com@{realm}
- the endpoint should have the form https://accounts.accesscontrol.windows.net/<<REALM>>/tokens/OAuth/2, where the REALM and the AudiencePrincipalID were found out during the configuration of Pega.
- the content type should be application/x-www-form-urlencoded and the parameters should be sent in the request body
- grant_type - the type of flow, should be authorization_code.
- code - the code from the call to the authorization endpoint
- redirect_uri - the reply/redirect uri that was configured when the add-in was registered
- client_id - the client_id should have the form CLIENT_ID@REALM, where the CLIENT_ID is the client id of the SharePoint add-in
- client_secret - the client secret of the SharePoint add-in
- resource - the resource should have the form <<AudiencePrincipalID>>/<<SPO_Site_Domain>>@<<REALM>>
Microsoft Graph API
The Graph API supports both the Oauth2 authorization code flow, which is interactive and needs an user intervention, and also the client credentials flow, which is not interactive and supports a service-to-service scenario.
The client credentials flow is described in this article.
The first step when configuring this flow is to register the app on the app registration portal. The registration process is described here. You can register the app as a web app and put the pega oauth2 redirect url as the Redirect URI.
After the app is registered, you need to add permissions to the app. Since the app will use it’s own identity to access the Microsoft Graph, you need to give it Direct Application Pemirssions. You can find the permissions as well as the api for OneDrive and SharePoint here and here.
Once the app is registered and the permissions are set, an admin needs to give consent and grand the app the permissions it requested. This is a one time operation (if you request new permissions, it has to be done again). The admin consent can be asked with a get request to the following link by an AD admin:
GET https://login.microsoftonline.com/{tenant}/adminconsent?
client_id={client_id}
&state=12345
&redirect_uri={redirect_uri}
- the endpoint has the form https://login.microsoftonline.com/{tenant}/adminconsent
- client_id – the id of the app as shown on the app registration portal
- state – a random number that will be returned back to track the session
- redirect_uri – the redirect uri that was set on the app registration process
If the admin consent succeeds, the app can now get access tokens and call the Graph API. In order to get an access token you can make a post request to the following link:
POST https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded
client_id={client_id}&
scope=https%3A%2F%2Fgraph.microsoft.com%2F.default&
client_secret={client_secret}
grant_type=client_credentials
- the endpoint has the form https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token
- client_id – the id of the app as shown on the app registration portal
- scope – the scope of the access token. If you want to call the Graph API, it should be https://graph.microsoft.com/.default
- client_secret – the client secret as generated on the app registration portal
- grant_type – the grant type. Should be client_credentials for service-to-service calls
Once you have the access token, you can add it as a Bearer authorization header when making the call to the api. You can try the api using this explorer https://developer.microsoft.com/en-us/graph/graph-explorer#
JPMorgan Chase & Company
US
Hi ,
Please check below pdn article
Pegasystems Inc.
IN
Hi Jim,
Thanks! The SR number is under the Related Support Case Number field in the original post above: SR-B86445
Regards,
Pegasystems Inc.
IN
This is more of a question to a Sharepoint Online administrator and I doubt Pega provides that support.
BTW, do you see any error in Pega while integrating with Sharepoint Online component.
Accepted Solution
Dynamic Credit
NL
After some research we have come to an understanding of how to use SharePoint online from Pega. Following are our findings.
There are several ways in which you can connect Pega to SharePoint Online.The first one is using the existing Pega component and the other is through a custom connector using the Microsoft Graph API.
Pega component
The Pega component can be found here.
In order to make it work, a new SharePoint Online add-in needs to be registered by following the instructions in the SharePoint Online Admin Guide.docx
Once the add-in is registered, proceed to add the component to Pega by using the Designer Studio -> Application -> Distribution -> Import. Once it is added, configure it as described in the SPOnline component documentation.docx document.
After some research we have come to an understanding of how to use SharePoint online from Pega. Following are our findings.
There are several ways in which you can connect Pega to SharePoint Online.The first one is using the existing Pega component and the other is through a custom connector using the Microsoft Graph API.
Pega component
The Pega component can be found here.
In order to make it work, a new SharePoint Online add-in needs to be registered by following the instructions in the SharePoint Online Admin Guide.docx
Once the add-in is registered, proceed to add the component to Pega by using the Designer Studio -> Application -> Distribution -> Import. Once it is added, configure it as described in the SPOnline component documentation.docx document.
The SharePoint add-in only supports the OAuth2 Authorization Code flow which is interactive. The whole flow is described here. Since the goal is to have the component upload documents using a single service account, an operator would have to perform the first step manually. Once that step is completed and you have an authorization code, an agent can then be scheduled to request the access token and to keep it valid by using the refresh token.
There are two main steps to get the access code. A get call to the SharePoint authorization endpoint as in the example below. Once the call is made, the user will be asked to login and give permissions to the add-in to perform the requested operation. After the user logs in and gives permission, an authorization code is returned. The authorization code is short lived (several minutes).
https://mysharepoint.sharepoint.com/sites/{my-site}/_layouts/OAuthAuthorize.aspx?
client_id={client_id}&
scope=Web.Read&
response_type=code&
redirect_uri={url_encoded_redirect_url}
- the endpoint should be the SharePoint site/subsite where the add-in was registered followed by /_layouts/OAuthAuthorize.aspx
- client_id - the client id of the SharePoint add-in that you get after the registration.
- scope - the type of operation that you want authorization to perform (Web.Read - read permissions on the site level). You can find the list of scopes in the flow description article and the scope description in this article.
- response_type - what type of response to expect. It should be code, since you are requesting an authorization code.
- redirect_uri - the reply/redirect uri that was configured when the add-in was registered
A post call to the Access Control Service with the authorization code in order to get an access and a refresh token. The result of the call is an access and a refresh token. The access token can be used to make calls to the API. The refresh token can be used to request another access token once the first is expired. This step of the process is not interactive.
https://accounts.accesscontrol.windows.net/{realm}/tokens/OAuth/2
content-type: application/x-www-form-urlencoded
grant_type=authorization_code
code={authorization_code}
redirect_uri={redirect_uri}
client_id={client_id}@{realm}
client_secret={client_secret}
resource={audience_principal_id}/mysharepoint.sharepoint.com@{realm}
- the endpoint should have the form https://accounts.accesscontrol.windows.net/<<REALM>>/tokens/OAuth/2, where the REALM and the AudiencePrincipalID were found out during the configuration of Pega.
- the content type should be application/x-www-form-urlencoded and the parameters should be sent in the request body
- grant_type - the type of flow, should be authorization_code.
- code - the code from the call to the authorization endpoint
- redirect_uri - the reply/redirect uri that was configured when the add-in was registered
- client_id - the client_id should have the form CLIENT_ID@REALM, where the CLIENT_ID is the client id of the SharePoint add-in
- client_secret - the client secret of the SharePoint add-in
- resource - the resource should have the form <<AudiencePrincipalID>>/<<SPO_Site_Domain>>@<<REALM>>
Microsoft Graph API
The Graph API supports both the Oauth2 authorization code flow, which is interactive and needs an user intervention, and also the client credentials flow, which is not interactive and supports a service-to-service scenario.
The client credentials flow is described in this article.
The first step when configuring this flow is to register the app on the app registration portal. The registration process is described here. You can register the app as a web app and put the pega oauth2 redirect url as the Redirect URI.
After the app is registered, you need to add permissions to the app. Since the app will use it’s own identity to access the Microsoft Graph, you need to give it Direct Application Pemirssions. You can find the permissions as well as the api for OneDrive and SharePoint here and here.
Once the app is registered and the permissions are set, an admin needs to give consent and grand the app the permissions it requested. This is a one time operation (if you request new permissions, it has to be done again). The admin consent can be asked with a get request to the following link by an AD admin:
GET https://login.microsoftonline.com/{tenant}/adminconsent?
client_id={client_id}
&state=12345
&redirect_uri={redirect_uri}
- the endpoint has the form https://login.microsoftonline.com/{tenant}/adminconsent
- client_id – the id of the app as shown on the app registration portal
- state – a random number that will be returned back to track the session
- redirect_uri – the redirect uri that was set on the app registration process
If the admin consent succeeds, the app can now get access tokens and call the Graph API. In order to get an access token you can make a post request to the following link:
POST https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded
client_id={client_id}&
scope=https%3A%2F%2Fgraph.microsoft.com%2F.default&
client_secret={client_secret}
grant_type=client_credentials
- the endpoint has the form https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token
- client_id – the id of the app as shown on the app registration portal
- scope – the scope of the access token. If you want to call the Graph API, it should be https://graph.microsoft.com/.default
- client_secret – the client secret as generated on the app registration portal
- grant_type – the grant type. Should be client_credentials for service-to-service calls
Once you have the access token, you can add it as a Bearer authorization header when making the call to the api. You can try the api using this explorer https://developer.microsoft.com/en-us/graph/graph-explorer#