Microsoft SSO

With Microsoft single sign-on (SSO), your team signs in to the RingQ web app with the Microsoft work account they already use for Outlook and Teams. There is no separate RingQ password to remember, and your Microsoft security rules, such as multi-factor authentication and Conditional Access, apply to RingQ too.

Setting it up takes about 15 minutes and has three parts:

• Part 1 (Microsoft administrator): register RingQ as an app in Microsoft Entra ID.
• Part 2 (RingQ administrator): enter the app details in RingQ and switch Microsoft SSO on.
• Part 3 (every user): sign in with the Microsoft button on the RingQ login page.

Before you start

• You need a Microsoft Entra ID administrator who can create app registrations (Application Administrator, Cloud Application Administrator or Global Administrator).
• You need a RingQ administrator account.
• Know your RingQ web address, the address your team types in the browser, such as pbx.yourcompany.com. This guide calls it your RingQ address.
• Each person who will sign in must already have a RingQ extension, and the email address on that RingQ user must be the same as their Microsoft sign-in email (for example emily@yourcompany.com in both places). RingQ uses the email to find the right user.
• The server must accept connections on TCP port 8443. The Microsoft sign-in returns to RingQ on this port. See the Port Forwarding guide.

Part 1 (Microsoft administrator): register RingQ in Microsoft Entra ID

1. Sign in to the Microsoft Entra admin center at entra.microsoft.com.
2. Go to Identity > Applications > App registrations and click New registration.
3. Fill in the form:
   • Name: RingQ Sign-in (any name your users will recognize).
   • Supported account types: Accounts in this organizational directory only (Single tenant).
   • Redirect URI: choose platform Web and enter https://your RingQ address:8443/teams/callback/1, for example https://pbx.yourcompany.com:8443/teams/callback/1. You can also copy it from the RingQ Microsoft SSO window in Part 2.
4. Click Register.
5. On the app's Overview page, copy these two values and keep them for Part 2:
   • Application (client) ID: this is the RingQ Client ID.
   • Directory (tenant) ID: this is the RingQ Tenant ID.
6. Open Certificates & secrets > Client secrets and click New client secret. Enter a description such as "RingQ" and pick an expiry, then click Add.
7. Copy the secret's Value straight away. Microsoft shows it only once. This is the RingQ Client secret. Do not copy the Secret ID, which is a different value and will not work.
8. Open API permissions. Make sure Microsoft Graph > User.Read (Delegated) is listed. It is added by default. RingQ asks Microsoft only for the user's basic profile and email (openid, profile, email and User.Read).
9. Optional: click Grant admin consent for your organization. Users then won't see a permission prompt the first time they sign in.

Write down the client secret's expiry date. When it expires, Microsoft sign-in stops working until you create a new secret and enter it in RingQ (Part 2).

Part 2 (RingQ administrator): switch on Microsoft SSO in RingQ

1. Sign in to the RingQ web app as an administrator, using your RingQ address (the same address your users will use).
2. In the left menu, click Global Settings.
3. Under Tools, click Integrations.
4. Stay on the SSO tab. In Single sign-on, find the Microsoft card ("Sign in with Microsoft Entra ID") and click Configure.
5. The Microsoft SSO window opens. Under API credentials, enter:
   • Client ID: the Application (client) ID from Part 1.
   • Client secret: the secret Value from Part 1. Click the eye icon to check what you pasted.
   • Tenant ID: the Directory (tenant) ID from Part 1.
6. Check Redirect URI. It must match the redirect URI in your Entra app registration exactly. Click the copy icon if you still need to add it in Entra.
7. Switch on Enable SSO ("Show Microsoft as a sign-in option.").
8. Click Save configuration. You will see "Microsoft SSO settings saved successfully." and the Microsoft card shows Connected.

All three credential fields are required. If one is empty, the window shows "Please fill in all credentials."

If you also use Address book > Microsoft 365: the address book and Microsoft SSO share the same Microsoft settings. After you save the address book settings, open SSO > Microsoft > Configure again and check that Enable SSO is still on.

Part 3 (users): sign in with Microsoft

1. Open your RingQ address in the browser, for example https://pbx.yourcompany.com/cloudapp.
2. Under Or sign in with, click Microsoft.
3. The Microsoft sign-in page opens. Pick your work account or enter your work email, then your password and any multi-factor step your company uses.
4. The first time, Microsoft may ask you to accept the permissions RingQ needs (your basic profile and email). Click Accept. If your administrator granted consent in Part 1, you won't see this.
5. Microsoft returns you to RingQ and your RingQ dashboard opens, signed in as your own extension.

Next time, if you are still signed in to Microsoft in that browser, step 3 is usually a single click on your account.

The Microsoft button appears only when Enable SSO is on. The other sign-in tabs (Access Code, SSO QR and SSO Code) keep working alongside it.

Turning Microsoft sign-in off

• For everyone: in Global Settings > Integrations > SSO > Microsoft > Configure, switch off Enable SSO and click Save configuration. The Microsoft button disappears from the login page.
• For one person: block or remove their account in Microsoft Entra ID, or disable their RingQ extension. A person whose Microsoft account is blocked can no longer sign in to RingQ with Microsoft.

Troubleshooting

Security notes

• RingQ never sees or stores your users' Microsoft passwords. Microsoft checks the password and multi-factor step, then tells RingQ who signed in.
• RingQ asks Microsoft only for the user's basic profile and email.
• Keep the client secret private. Anyone with it and the Client ID could pretend to be your RingQ app. Set a calendar reminder before it expires.
• Each sign-in link from Microsoft to RingQ can be used once and expires after 5 minutes.