Microsoft Entra ID

Use Microsoft Entra ID as your Identity Provider.

Configure Microsoft Entra ID as your identity provider for user authentication. This App Registration is specifically for authentication purposes and user/group identity mapping.

Create New App Registration

  1. Authenticate to the Azure Portal via your Microsoft Identity.
  2. Head over to App Registrations.
  3. Click “New Registration”:
    • Enter “Atolio Authentication” for the name.
    • Ensure “Accounts in this organizational directory only” is selected from Supported account types.
    • Add a redirect URI https://search.example.com/auth/_callback (replace search.example.com with your actual Atolio deployment URL - contact your Atolio onboarding support team if you need clarification on the correct URL).
    • Click “Register”.
  4. You should now be on the page of your new app registration. In the Essentials blade, locate the “Add a certificate or secret” link.
  5. Create a Client Secret for use with OIDC:
    • Select the “Client Secrets (0)” tab.
    • Click “New Client Secret”.
    • Enter “Atolio OIDC Authentication” for the description.
    • Set desired expiry. Follow internal procedures for rotation.
    • Copy the newly created “Value” of the Client Secret and store it in a safe place (e.g. 1Password). This will be referenced later for OIDC configuration.
  6. Add a certificate for client authentication:
    • Obtain a .PFX file that includes the public and private keys. The certificate key algorithm must be RSA. A private key password is optional, but recommended.
    • Export the public key to a .CER file.
    • Select the “Certificates (0)” tab.
    • Click “Upload certificate”.
    • Enter “Atolio Client Authentication” for the description.
    • Select the .CER file and select “Add”.
    • Export the .PFX file contents to base 64 and store it in a safe place (e.g. 1Password). You can obtain the base 64 encoding from the command line with cat my-cert.pfx | base64. This value will be referenced later for source configuration.
  7. Add Microsoft Graph API Permissions:
    • In your App Registration, click “API permissions” in the left menu
    • Click “Add a permission”
    • Select “Microsoft Graph”
    • Click “Application permissions” (not Delegated permissions)
    • Add these permissions:
PermissionPurpose
Application.Read.AllResolve service principals and applications
Group.Read.AllList Microsoft 365 and security groups
GroupMember.Read.AllResolve group membership for ACL mapping
User.Read.AllResolve user objects and properties
Directory.Read.AllExtended directory objects (optional*)

*Optional: You can omit Directory.Read.All and set disable_full_permissions: true in your configuration for more restrictive access.

⚠️ Important: This App Registration should only contain the directory permissions listed above. Do not add content source permissions (Files, Sites, Teams, etc.) to this registration.

  1. Grant Admin Consent:

    • Click “Grant admin consent for [your tenant name]” at the top of the API permissions page
    • Confirm by clicking “Yes”
    • Verify all permissions show “Granted for [your tenant name]” with green checkmarks
  2. Finally, revisit the app registration Overview and copy the Directory (tenant) ID as well as the Application (client) ID. These will be used later when configuring Entra ID authentication.

Sample Configuration

Here’s a complete YAML configuration example for Entra ID as an identity provider:

connector: microsoft
source: entraid
common:
  enabled: true
  identity-provider: true     # This is the identity provider
  cron-spec: "0 */1 * * *"   # Sync users/groups every hour
secrets:
  client_secret:
    value: "<CLIENT_SECRET_VALUE>"  # From step 5 above
  client_cert:
    value: "<BASE64_ENCODED_PFX_CONTENT>"  # From step 6 above
  client_cert_password:
    value: "<CERTIFICATE_PASSWORD>"  # Optional if no password set
configuration:
  client-id: "<APPLICATION_CLIENT_ID>"      # From step 7 above
  tenant-id: "<DIRECTORY_TENANT_ID>"        # From step 7 above
  disable_full_permissions: true           # Optional: reduces required permissions

Configuration Notes:

  • identity-provider: true - Marks this as the identity provider source
  • client_secret - Required for OIDC authentication flow
  • client_cert - Required for Microsoft Graph API access to sync users/groups
  • disable_full_permissions: true - Omits Directory.Read.All permission if you prefer more restrictive access

Important: Separate App Registrations for Content Sources

This App Registration is specifically for authentication and identity provider purposes.

For security and scalability best practices, create separate App Registrations for each Microsoft content source (SharePoint, Teams, OneDrive, Outlook) you plan to configure. Each content source should have its own dedicated App Registration with only the minimum permissions required.

See the individual connector documentation: