Microsoft Entra ID

A Microsoft Entra ID administrator connects the directory to RingSync, with admin consent or with their own application, then assigns the people who will receive the directory.

Choose the method

RingSync reads your directory from its servers, read-only. The Connect a directory form offers two methods.

Method	What you do	Secret to manage
Sign in to Microsoft (recommended)	You approve RingSync's multi-tenant application with an administrator account.	None
Manual entry	You create your own multi-tenant app registration and paste its credentials.	Your client secret, to renew before it expires

Both methods request the same three read-only permissions. Choose manual entry if your security policy requires that the app registration and its secret belong to you. Permission details: Microsoft permissions.

Prerequisites

A RingSync account with the Owner or Admin role.
Sign in to Microsoft: an account in the tenant that can grant admin consent to an application. This account must be a member of the tenant, not a guest.
Manual entry: the right to create an app registration and a client secret, and the right to grant admin consent.
To assign people or groups: the right to assign users to an enterprise application in Entra.

In the RingSync dashboard, click Connect a directory.
At the Name step, enter the Directory name.
At the Directory provider step, choose Microsoft Entra ID.
At the Microsoft Entra ID application step, choose Sign in to Microsoft.
Click Sign in to Microsoft.
On the Microsoft page, sign in with an administrator account of the tenant you are connecting.
Review the three read-only permissions shown, then accept. Microsoft adds the RingSync application to your tenant's enterprise applications.
If RingSync asks you to, sign in with Microsoft on this tenant with a member account, not a guest.
You land on the directory Dashboard. RingSync has already read the assignments once.

Step 8 only appears if the confirmed email address of your RingSync account is not that of an active member of the tenant. See "Technical details" below.

With this method, the application appears in your tenant's enterprise applications under the name "RingSync Graph Access".

Method 2: Manual entry

Create the app registration

Open portal.azure.com, then Microsoft Entra ID → App registrations → New registration.
Name the application RingSync.
Under Supported account types, choose Accounts in any organizational directory (Multi-tenant).
Leave the redirect URI empty: it is not needed.
Confirm the registration.

Multi-tenant required

A single-tenant application is refused with the message "The Entra app must be configured as multi-tenant." To fix an existing application, open Authentication → Supported account types in its registration.

Add the permissions

Open API permissions → Microsoft Graph → Application permissions.
Add User.Read.All, GroupMember.Read.All and Application.Read.All.
Click Grant admin consent for your tenant.

Create the client secret

Open Certificates & secrets → New client secret. The maximum lifetime is 24 months.
Copy the Value right away: it will not be shown again.

Note the identifiers

In Overview, copy the Application (client) ID and the Directory (tenant) ID.

Connect the directory in RingSync

In RingSync, click Connect a directory, enter the Directory name, choose Microsoft Entra ID, then Manual entry.
In Microsoft Tenant ID, paste the Directory (tenant) ID.
In Client ID, paste the Application (client) ID.
In Client Secret, paste the secret's Value.
Click Test connection and wait for Connection successful. RingSync checks with Microsoft Graph that these credentials work, without saving anything.
Click Connect the directory.

RingSync stores the secret encrypted, reads its expiry date and reads the assignments once, then takes you to the directory dashboard.

Require assignment in Entra

At connection, RingSync tries to set its enterprise application so that Entra refuses users who are not assigned to it. If Microsoft refuses this setting, the connection still succeeds.

In Entra, open the RingSync enterprise application: "RingSync Graph Access" with Sign in to Microsoft, the name you chose with Manual entry.
Open its properties.
Turn on the option that requires users to be assigned, then save.

This setting does not decide who uses RingSync: access to the mobile app depends on the RingSync seat, computed from the assignments.

Decide who has access

A person can sign in to the app and receive the directory if they are assigned to the RingSync enterprise application, directly or through a group. Each assigned person takes one seat.

In RingSync, open Settings → Who has access, then click Open in Entra ID.
In Entra, assign the users or groups who should use RingSync to the application.
To apply the assignments right away, go back to RingSync and click Refresh now. You can also click Sync from directory on the Users page.

RingSync reads the assignments again every 15 minutes.

Nested groups: RingSync counts every member of an assigned group as a seat, including members of nested groups.
Plan limit: beyond the number of seats in your plan, the extra people do not get a seat and the "Plan limit reached" banner appears. See Seats and limits.
Removing someone: remove their assignment in Entra, because the dashboard cannot remove a seat that comes from the directory. At the next pass, 15 minutes at most, the seat is revoked and the person's phones purge the directory's contacts. See Security and data.

Seats and synced contacts

Assignments decide who uses the app. The contacts written to phones are, by default, those of the whole directory. To restrict them, see Select and exclude groups (Pro plan and above).

Replace the client secret

This section applies to Manual entry. With Sign in to Microsoft, you have no secret to manage.

When the client secret expires, RingSync can no longer read the directory and syncs fail. RingSync does not renew the secret for you.

The expiry date is shown in Settings, on the directory configuration card.
The Directory connection card on the dashboard shows "The client secret expires in …" within the 30 days before the deadline.
30 days before expiry, owners and admins receive an email, except those who turned off Receive operational alerts in their profile.

To replace the secret:

In your app registration, open Certificates & secrets → New client secret and copy the Value.
In RingSync, open Settings → Replace the client secret. The Replace the secret button on the Directory connection card leads to the same place.
Paste the value in the New client secret field, then click Replace.
Wait for the message "Secret replaced. The next syncs will use it."

RingSync checks the secret with Microsoft before saving it. If it is refused, the old one stays in place. The connection, seats and history are kept.

Verify the connection

In Dashboard → Directory connection, the status is Working and the message is "RingSync reads your directory normally."
The Users page lists the assigned people.
In Entra, the assignment requirement of the enterprise application is turned on.
On an assigned person's phone, they tap Sign in with Microsoft, the directory appears, then the first sync succeeds.

Troubleshooting

Message or symptom	Likely cause	What to do
The app shows "No directory has been shared with you. Contact your administrator."	The person is not assigned, or RingSync has not read the assignments yet.	Assign them, click Refresh now, then ask them to sign in again.
"We couldn't verify that you belong to this Microsoft directory…"	The account used is not a member of the tenant (guest account, another tenant).	Start over with a member account of the tenant.
"The Microsoft verification sign-in failed or was cancelled. Please start the installation again."	The verification sign-in was interrupted.	Start the installation again.
"Consent was refused…" or "Consent was not granted."	Consent was refused or did not complete.	Start over with an account that can grant admin consent.
"The install session is invalid or expired. Please start over."	The sign-in session expired.	Start again from Connect a directory.
"The Entra app must be configured as multi-tenant."	Single-tenant app registration.	Switch it to multi-tenant.
"Microsoft refused the credentials: …"	One of the three values is wrong, or the secret expired.	Check that Client Secret holds the secret's Value and that Microsoft Tenant ID is the Directory (tenant) ID, then click Test connection.
"This directory is already configured on RingSync."	This tenant is already connected to a RingSync organization.	Contact us.
"Your plan limit has been reached (number of directories)."	Your plan does not allow another directory.	See Seats and limits.
Directory connection: "The client secret of your Entra application expired or is no longer valid…"	Secret expired or deleted.	Replace the secret (previous section).
Directory connection: "A permission is missing…"	One of the three permissions is missing or has no admin consent.	Grant admin consent for the three permissions.
Directory connection: "RingSync's access was removed from the Microsoft tenant…"	Application deleted or consent revoked.	If that was not intended, write to us from Contact us. See RingSync lost access to the directory.
Signing in to the app is refused with a personal Microsoft account.	RingSync syncs organization directories.	The person signs in with their work account.

Technical details

Two separate Microsoft applications. The application that reads the directory is "RingSync Graph Access" with Sign in to Microsoft, or your own registration with Manual entry. Employees sign in to the mobile app through another application, "RingSync Identity", which only requests openid profile email and has no access to Microsoft Graph.
Application permissions. User.Read.All, GroupMember.Read.All and Application.Read.All, which require admin consent. RingSync calls Graph with its own application token, with no signed-in user.
Proof of membership. The tenant returned by admin consent is not signed, and the shared application can remain installed at a former customer. Before any write, RingSync therefore checks that the installer belongs to the tenant: either their confirmed RingSync email is the mail or user principal name of an active member of the tenant, or they sign in with Microsoft on that tenant and the identity token must name a member, not a guest. An email alias does not match the first check: the second one then applies.
Assignment requirement. RingSync tries to set appRoleAssignmentRequired to true on the service principal, in both methods. A failure does not interrupt the connection.
Seats. They come from the assignments (appRoleAssignedTo) of the enterprise application; assigned groups are expanded with their transitive members.