Microsoft Entra ID is Microsoft's cloud-based identity service that manages user identities and controls access to applications and data. Microsoft renamed Azure Active Directory to Entra ID in 2023. The goal was to reduce confusion with the old "Active Directory" (which runs on local office servers) and to show that the service works for all clouds and applications, not just those inside of Azure.
To integrate Microsoft with GivingData, you must first set up an application registration for GivingData in Microsoft Entra ID.
Once you have created the application registration, the same Application ID, Client Secret, and Tenant Domain can be used when setting up all other GivingData integrations with Microsoft:
- GivingData Add-In for Outlook
- Azure SSO
- OneDrive Premium Document Management
- OneDrive Document Linking
This initial setup only needs to be completed once per GivingData site.
If you are adding an additional GivingData integration with Microsoft at a later time, edit the existing GivingData application registration in Microsoft Entra ID as needed, referencing the sections below in this article.
If you are setting up one or more integrations with your GivingData Staging site, the applicable steps in this article can be repeated to create an application registration for your Staging site as well.
If you have any questions or need assistance during setup, contact our Support team.
Create the Application Registration
This section is required if you are setting up any of the following GivingData integrations with Microsoft:
- GivingData Add-In for Outlook
- Azure SSO
- OneDrive Premium Document Management
- OneDrive Document Linking
Creating an application registration is like getting a digital ID card for an application. It establishes a trust relationship for applications within the Microsoft identity platform and allows them to authenticate users, integrate with Microsoft services, and securely access APIs.
- Log into the Azure Portal (https://portal.azure.com), and then navigate to the Microsoft EntraID service.
- On the Overview page, copy the Tenant ID, as you will be asked to provide this to your GivingData contact.
- Click Branding & properties, and then copy the Publisher (Tenant) Domain, as you will be asked to provide this to your GivingData contact.
-
In the left-side menu, click App registrations, and then click New registration.
- Complete the fields as follows, and then click Register.
- Name - Enter a name for the application (e.g. GivingData.Production).
-
Supported account types - Select Accounts in this organizational directory only.
Once you click Register, you will receive a toast notification confirming the application's registration and will be automatically taken to the new application.
- Copy the Application ID, as you will be asked to provide this to your GivingData contact, and then click Add an Application ID URI.
-
Click the Add link next to Application ID URI at the top of the page, accept the pre-populated Application ID URI value, and then click Save.
- Copy the value in the Application ID URI field, as you will be asked to provide this to your GivingData contact.
Create the Client Secret
This section is required if you are setting up any of the following GivingData integrations with Microsoft:
- GivingData Add-In for Outlook
- OneDrive Premium Document Management
The client secret is a confidential value generated within your application registration. It acts as a password for your application, proving its identity to Microsoft when requesting access tokens. Once the secret expires or is revoked, the integration will stop working until a new secret is generated and provided to GivingData.
- In the left-side menu, click Certificates & secrets.
- Click Client secrets.
- Click New client secret.
- Enter any description, select 24 months in the Expires dropdown, and then click Add.
- Copy the Client secret value, as you will be asked to provide this to your GivingData contact.
- ⚠️ Copy and securely store the client secret value immediately after creation, as it will not be visible again once you navigate away from the page.
- ⚠️ Copy and securely store the client secret value immediately after creation, as it will not be visible again once you navigate away from the page.
Configure API Permissions
This section is required if you are setting up any of the following GivingData integrations with Microsoft:
- GivingData Add-In for Outlook
- Azure SSO
- OneDrive Premium Document Management
- OneDrive Document Linking
Application registration API permissions define what data and actions an application can access within your Microsoft tenant. When you register an application in Entra ID, you must explicitly list which APIs the application is permitted to call.
GivingData integrations use two types of API permissions:
-
Application Permissions - These permissions operate without a signed-in user. The application authenticates as itself using the Client secret and accesses tenant resources directly. The following integrations use Application permissions:
- GivingData Outlook Add-In
- OneDrive Premium Document Management
-
Delegated Permissions - These permissions operate on behalf of a signed-in user. The application can only access what that user already has access to. The following integration uses Delegated permissions:
- OneDrive Document Linking
Add Application Permissions
Because Application permissions grant tenant-wide access, a tenant admin must click Grant admin consent after adding them. This step authorizes the application to operate at that level. Without consent, the permissions are inactive.
Follow the steps below to add Application permissions (applicable if you are setting up either of the following integrations: GivingData Add-In for Outlook, OneDrive Premium Document Management).
- In the left-side menu, click API Permissions.
- Click Add a permission.
- Click Microsoft Graph.
- Click Application permissions.
- For each integration you are setting up, add the permissions listed in the Permission Requirements Matrix section below.
- Click Add permissions.
- Click Grant admin consent at the top of the page.
- ⚠️ Clicking Grant admin consent requires Global Administrator or Privileged Role Administrator access in Microsoft Entra ID. If this button is greyed out, contact your organization's Azure administrator to complete this step.
- ⚠️ Clicking Grant admin consent requires Global Administrator or Privileged Role Administrator access in Microsoft Entra ID. If this button is greyed out, contact your organization's Azure administrator to complete this step.
Add Delegated Permissions
Follow the steps below to add Delegated permissions (applicable if you are setting up either of the following integrations: Azure SSO, OneDrive Document Linking).
- In the left-side menu, click API Permissions.
- Click Add a permission.
- Click Microsoft Graph.
- Click Delegated permissions.
- For each integration you are setting up, add the permissions listed in the Permission Requirements Matrix section below.
- Click Add permissions.
- Click Grant admin consent at the top of the page.
- ⚠️ Clicking Grant admin consent requires Global Administrator or Privileged Role Administrator access in Microsoft Entra ID. If this button is greyed out, contact your organization's Azure administrator to complete this step.
- ⚠️ Clicking Grant admin consent requires Global Administrator or Privileged Role Administrator access in Microsoft Entra ID. If this button is greyed out, contact your organization's Azure administrator to complete this step.
Permission Requirements Matrix
One Entra ID application registration can serve all GivingData integrations with Microsoft. This matrix defines which permissions and configurations each integration requires as well as the permission type (Application vs. Delegated).
The User.Read permission is added by default to each new application registration, so it does not need to be manually configured.
| Permission |
Azure SSO OIDC / OAuth 2.0 |
Outlook Add-In App-only |
OneDrive Doc Mgmt App-only |
OneDrive Doc Linking Delegated |
| MSFT GRAPH API PERMISSIONS | ||||
| Mail > Mail.Read | — | APP | — | — |
| Files > Files.Read.All | — | — | APP | DEL |
| Files > Files.ReadWrite.All | — | — | APP | DEL |
| Group > Group.Read.All | — | — | APP | — |
| Group > Group.ReadWrite.All | — | — | APP | — |
| Sites > Sites.Read.All | — | — | — | DEL |
| Sites > Sites.ReadWrite.All | — | — | — | DEL |
| User > User.Read | DEL | DEL | DEL | DEL |
| APP REGISTRATION CONFIG | ||||
| Client Secret required | — | ✓ | ✓ | — |
| Manifest / redirect URIs | ✓ | — | — | — |
| ID token issuance | ✓ | — | — | — |
| Access token issuance | ✓ | — | — | — |
| Admin consent required | — | ✓ | ✓ | ✓ |
Legend
| APP = Application permission | DEL = Delegated permission | ✓ = Required |
Additional Information on API Permissions
The table above lists the required permissions for each integration you are configuring.
In particular, a frequently asked question is why the required permissions for the OneDrive Premium Document Management integration are so broad. While the permissions themselves are tenant-wide, GivingData's access to your Microsoft environment is constrained by the configuration of our integration. So in practice:
- The integration uses the SharePoint URL you provide during setup to target only the SharePoint site and document libraries relevant to your organization's instance.
- These specific permissions are necessary in order for the integration to read/write files and traverse group structures across the tenant without a user session.
- Because the architecture of the integration authenticates as the app rather than a specific user, Microsoft requires the .All scope.
Manifest and Authentication Flow
This section is required if you are setting up any of the following GivingData integrations with Microsoft:
- GivingData Add-In for Outlook
- Azure SSO
Every application registration has a manifest, which is essentially its configuration file written in JSON. Think of it as the application's blueprint. It tells Microsoft's identity platform what the application is allowed to do: what kinds of tokens it can request, which URLs it is allowed to redirect users to after sign-in, and how it identifies itself. For the Azure SSO integration, you will make two changes in the manifest: enable token issuance (so Microsoft will send authentication tokens to GivingData) and register your GivingData site URL as an approved redirect destination.
- In the left-side menu, click Manifest.
- Locate "implicitGrantSettings" in the manifest editor, and set the following keys to "true":
- "enableAccessTokenIssuance"
-
"enableIdTokenIssuance"
- Locate the
"spa"property in the manifest editor. Inside it, find the"redirectUris"array and add the following entries:
"https://<<clientsubdomain>>.givingdata.com/*", "https://<<clientsubdomain>>.givingdata.com", "https://*.givingdata.com", "https://*.givingdata.com/*"
- Click Save.
The final step in this section is to verify that the authentication flow settings are configured properly.
- In the left-side menu, click Authentication.
- In the Implicit grant and hybrid flows section, check the box for both the Access tokens and ID tokens options, and then click Save.
Provide Required Information to GivingData
Once all configuration steps are complete, gather the applicable values below and share them with your GivingData Project Manager or Technical Lead.
Do not share credentials through unsecured channels. Use your organization's preferred method for securely transmitting sensitive values such as the Client secret value.
| Value | Where to Find It | Required For |
|---|---|---|
| Tenant ID | Entra ID > Properties | Azure SSO |
| Tenant Domain | Entra ID > Overview > Primary domain | Outlook Add-In, OneDrive Premium Document Management, OneDrive Document Linking |
| Application ID | App Registration > Overview | All Microsoft integrations |
| Application ID URI | App Registration > Overview | Azure SSO |
| Client Secret value | App Registration > Certificates & secrets | Outlook Add-In, OneDrive Premium Document Management |
🛑 Wait to move forward with next steps until instructed by your GivingData contact.