Skip to main content

Create a GivingData Application Registration in Microsoft Entra ID

Lauren Neulinger
Updated

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.

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.

  1. Log into the Azure Portal (https://portal.azure.com), and then navigate to the Microsoft EntraID service.microsoft entra id option
     
  2. On the Overview page, copy the Tenant ID, as you will be asked to provide this to your GivingData contact.
  3. Click Branding & properties, and then copy the Publisher (Tenant) Domain, as you will be asked to provide this to your GivingData contact.publisher domain
     

  4. In the left-side menu, click App registrations, and then click New registration. 

    new registration option
     

  5. 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.register button

Once you click Register, you will receive a toast notification confirming the application's registration and will be automatically taken to the new application.

  1. Copy the Application ID, as you will be asked to provide this to your GivingData contact, and then click Add an Application ID URI. add an application id uri option
     

  2. 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.

    save button

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.

  1. In the left-side menu, click Certificates & secrets.
  2. Click Client secrets.
  3. Click New client secret.
  4. Enter any description, select 24 months in the Expires dropdown, and then click Add.add button
     
  5. 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. client secret value

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

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).

  1. In the left-side menu, click API Permissions.
  2. Click Add a permission.
  3. Click Microsoft Graph.microsoft graph option
     
  4. Click Application permissions.
  5. For each integration you are setting up, add the permissions listed in the Permission Requirements Matrix section below.
  6. Click Add permissions.add permissions button
     
  7. 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.grant admin consent button

Follow the steps below to add Delegated permissions (applicable if you are setting up either of the following integrations: Azure SSO, OneDrive Document Linking).

  1. In the left-side menu, click API Permissions.
  2. Click Add a permission.
  3. Click Microsoft Graph.
  4. Click Delegated permissions.
  5. For each integration you are setting up, add the permissions listed in the Permission Requirements Matrix section below.
  6. Click Add permissions.add permissions button
     
  7. 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.grant admin consent button

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

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.

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.

  1. In the left-side menu, click Manifest.
  2. Locate "implicitGrantSettings" in the manifest editor, and set the following keys to "true":
    • "enableAccessTokenIssuance"

    • "enableIdTokenIssuance"

      manifest keys
       

  3. 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/*"

manifest entries
 

  1.  Click Save.

The final step in this section is to verify that the authentication flow settings are configured properly.

  1. In the left-side menu, click Authentication.
  2. In the Implicit grant and hybrid flows section, check the box for both the Access tokens and ID tokens options, and then click Save.checkboxes

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.

Powered by Zendesk