Docs/Getting Started·Entra ID·Server Core·EWS Migration·EWS Deprecation

Configuration

Entra ID Setup

Create an App Registration in Microsoft Entra ID, generate a certificate for authentication, and grant the Graph API permissions that CYNC requires.

Prerequisites: You need Global Administrator or Application Administrator privileges in your Microsoft Entra ID tenant to create App Registrations and grant admin consent.

1Create an App Registration

  1. Sign in to the Microsoft Entra admin center.
  2. Navigate to Identity → Applications → App registrations.
  3. Click New registration.
  4. Enter a name, for example CYNC Contact Sync.
  5. For Supported account types, select “Accounts in this organizational directory only (Single tenant)”.
  6. Leave the Redirect URI blank - CYNC does not use interactive (delegated) authentication.
  7. Click Register.

After registration, note the following values from the Overview page:

FieldWhere used
Application (client) IDCYNC dashboard → Configuration → Client ID
Directory (tenant) IDCYNC dashboard → Configuration → Tenant ID

2Generate a certificate

CYNC authenticates using ClientCertificateCredential from the Azure.Identity library. The private key is stored in the Windows Certificate Store on the machine running the CYNC service. No client secrets or passwords are stored.

Option A: Generate from the CYNC dashboard (recommended)

The CYNC admin dashboard can generate and install the certificate for you:

  1. Open the CYNC dashboard and navigate to the Configuration page.
  2. Click Generate/Renew Certificate.
  3. CYNC creates a self-signed certificate, installs the private key in the Local Machine certificate store, and exports the public key (.cer file) for you to upload to Entra ID.
  4. The certificate thumbprint is automatically populated in the Configuration page.

Tip: This is the fastest path. The dashboard handles key generation and store installation in one click. You only need to upload the exported .cer file to your App Registration (see below).

Option B: Generate manually (PowerShell)

If you prefer to generate the certificate yourself (e.g., using your internal PKI or on a Server Core machine without the dashboard):

# Create a self-signed certificate valid for 2 years
$cert = New-SelfSignedCertificate `
  -Subject "CN=CYNC Contact Sync" `
  -CertStoreLocation "Cert:\LocalMachine\My" `
  -KeyExportPolicy Exportable `
  -KeySpec Signature `
  -KeyLength 2048 `
  -NotAfter (Get-Date).AddYears(2)

# Export the public key (.cer) for upload to Entra ID
Export-Certificate `
  -Cert $cert `
  -FilePath "C:\cync-cert.cer"

# Display the thumbprint - enter this in the CYNC dashboard
$cert.Thumbprint

Important: The certificate must be in Cert:\LocalMachine\My (Local Machine → Personal store), not the Current User store. The CYNC service runs as LocalSystem and needs access to the private key.

Upload the certificate to Entra ID

Regardless of which method you used to generate the certificate, upload the public key to your App Registration:

  1. In the Entra admin center, go to your CYNC App Registration.
  2. Navigate to Certificates & secrets → Certificates.
  3. Click Upload certificate and select the .cer file (exported by the dashboard or by the PowerShell script above).
  4. Add a description (e.g. “CYNC server cert”) and click Add.

3Grant API permissions

CYNC requires three Application permissions (not Delegated) from the Microsoft Graph API:

PermissionTypePurpose
User.Read.AllApplicationRead all user profiles from Entra ID (display name, email, department, job title, phone, etc.)
Group.Read.AllApplicationRead group memberships (required when using source group filtering to sync specific groups)
Contacts.ReadWriteApplicationCreate, update, and delete contacts in target users' Exchange Online mailboxes

Steps

  1. In your App Registration, go to API permissions.
  2. Click Add a permission → Microsoft Graph → Application permissions.
  3. Search for and select User.Read.All. Click Add permissions.
  4. Repeat for Group.Read.All and Contacts.ReadWrite.
  5. Click Grant admin consent for [your tenant] and confirm.

Admin consent is required. Without admin consent, CYNC cannot read users or write contacts. The permission status should show a green checkmark next to each permission after granting consent.

Service restart required: After changing API permissions, restart the CYNC service to clear the cached access token. The service caches OAuth tokens for up to 75 minutes. Run Restart-Service CyncService on the server.

4Configure CYNC

Enter the three values from the previous steps into the CYNC admin dashboard:

  1. Open the CYNC dashboard and navigate to the Configuration page.
  2. Enter your Tenant ID (Directory ID from the App Registration overview).
  3. Enter your Client ID (Application ID from the App Registration overview).
  4. Enter the Certificate Thumbprint (SHA-1 thumbprint of the certificate in the Local Machine store).
  5. Click Test Connection to verify that CYNC can authenticate with Entra ID.

Success: If the test passes, CYNC can authenticate with your Entra ID tenant and read user profiles. You're ready to define target users and run your first sync.

Troubleshooting

"Certificate not found" error

Verify the certificate is in Cert:\LocalMachine\My (not CurrentUser). The CYNC service runs as LocalSystem and needs access to the Local Machine store.

"Insufficient privileges" error

Ensure admin consent has been granted for all three permissions: User.Read.All, Group.Read.All, and Contacts.ReadWrite. Check the API permissions page in the Entra admin center for green checkmarks.

"Invalid tenant" error

Double-check the Tenant ID. It should be a GUID from the App Registration overview page, not the tenant name or domain.

Permissions changed but sync still fails / still works

The CYNC service caches OAuth access tokens for up to 75 minutes. Restart the service (Restart-Service CyncService) to clear the token cache after changing API permissions.

Next: Server Core GuideBack to Getting Started