What is everything I need to integrate with Sharepoint using OAuth?

johnathan151613

I'm working on putting together a plan for integrating my Decisions Server with SharePoint. I have the module installed, but I don't know where to begin with the OAuth settings for integration. What do I need to get off the ground here?

jacob_Decisions

The setup with OAuth does contain a lot of moving parts, so I've broken my answer down into the following sections: Prerequisites, Set Up OAuth Provider, Set up OAuth Token, OAuth Token Refresh, and Further Resources. 

Prerequisites:

1. The Azure app registration needs to be set up 
2. Scope needs to be configured based on your organization's internal requirements
3. Client Secret provided 
4. Callback URL ({PortalBaseURL}/HandleTokenResponse) configured in Azure > App Registration > API Permissions > Sharepoint. Your PortalBaseURL is the main URL of your Decisions Instance. If you are unsure what your PortalBaseURL is, it can be found in the Settings.xml file, located in your Decisions install location.
5. The Azure tenant (i.e.: https://{tenant}.sharepoint.com)

Set up OAuth Provider:

1. In Decisions, navigate to SYSTEM > Integrations > OAuth > Providers > ADD OAUTH PROVIDER
2. Add a name and description to the OAuth Provider
3. Select OAuth2
4. Token Request URL, found in Azure > App Registration > Overview > Endpoints > OAuth 2.0 token endpoint (v2)
5. Authorize URL, found in Azure > App Registration > Overview > Endpoints > OAuth 2.0 authorization endpoint (v2)
6. Callback URL, must be the same as what we configured in azure in the prerequisites. {PortalBaseURL}/HandleTokenResponse
7. Default Consumer Key, this is the Application (Client) ID found in Azure > App Registration > Overview > Application (Client) ID. Note this is NOT the secret Key ID. The ID of our secret is not used. 
8. Default Consumer Secret Key, this is the value of the secret key. This will need to be provided by Azure admin. They can generate this value in Azure > App Registration > Certificates & Secrets > New Client Secret. Note that this value will only be shown when generated. Once the page is left or refreshed, the value will not be displayed again; it must be grabbed before leaving the page. If not, it will need to be deleted and readded
9. Client Authentication Type, we used Client Secret for our demonstration today. We can also use Private Key JWT, however that requires some additional configuration instead of the Client Secret. Both works just as securely. The Decisions Support Rep handling this ticket is more familiar with Client Secret as demoed, but Private Key JWT can be configured instead if so desired. 

OAuth Token:

1. In Decisions, navigate to SYSTEM > Integrations > OAuth > Tokens
2. Create Token
3. Choose a good token name, and from the drop-down menu select the provider we configured earlier
4. For scope, we will need the tenant URL provided by the Azure admin, this will look like (https://{tenant}.sharepoint.com). We will need .default and offline_access scope. .default grabs the permissions configured by the Azure admin during the prerequisites, and offline_access allows us to refresh the token. We will enter everything inside the parenthesis: (https://{tenant}.sharepoint.com/.default offline_access)
5. Request Token. If you see "Token processed successfully. You may close this window." you have configured everything correctly. 

OAuth Token Refresh

• The token will expire; however, we can configure a scheduled job to refresh it. 
• If we used Client Secret in our OAuth Provider settings, we use the Reset Client Credentials step, inputting our token ID, secret value, and scope used earlier. This step can be found in the flow designer under INTEGRATION > INTERNALSERVICES > OAUTHTOKENSERVICE
• If we used Private Key JWT in our OAuth Provider settings, we use the Refresh Access Token step, inputting just our token ID. This step can be found in the flow designer under INTEGRATION > INTERNALSERVICES > OAUTHTOKENSERVICE
• This scheduled job can be set to run every 20-30 minutes

Further Resources:

• Color Coded Chart on what to get from Azure and where to put in Decisions: https://community.decisions.com/discussion/47974/how-to-integrate-with-azure
• Establishing an OAuth Provider: https://documentation.decisions.com/docs/establishing-an-oauth-provider
• Creating OAuth Tokens: https://documentation.decisions.com/docs/creating-oauth-tokens
• Sharepoint Module: https://documentation.decisions.com/v8/docs/en/sharepoint

For any assistance with this, please reach out to support@decisions.com