Microsoft Entra ID
Connect a Grovs project to your Entra ID tenant so your team signs in with their work account.
You need a Global Administrator account in your Entra tenant and admin rights on the Grovs project. Use a work account for the Entra steps; personal Microsoft accounts cannot manage a tenant's applications.
Register Grovs in Entra
Create the app registration
Entra admin center → App registrations → New registration. Name it, for example Grovs. Supported account types: single tenant. Under Redirect URI choose Web and paste the redirect URI from Grovs: Settings → Single sign-on shows it before and after setup. On the SaaS product it is https://sqd.link/api/v1/identity/sso/auth/oidc/callback.
Copy the client ID
On the Overview page copy the Application (client) ID and the Directory (tenant) ID. Your issuer is https://login.microsoftonline.com/<tenant-id>/v2.0.
Create a client secret
Certificates & secrets → New client secret. Copy the Value immediately; Entra never shows it again. Entra caps secrets at 24 months, so put the expiry in your calendar.
Add an admin role
App roles → Create app role: display name Grovs admin, allowed member types Users/Groups, value grovs-admin. People assigned this role become project admins on their first sign-in. Add a second role such as grovs-member as well: with only one role defined, Entra pre-selects it for every assignment and makes everyone an admin.
Grant admin consent
API permissions → Grant admin consent for your tenant. Without it, the first person to sign in sees "Need admin approval" and is blocked.
Require assignment and assign people
Enterprise applications → your app → Properties → "Assignment required": Yes. Then Users and groups → Add user/group → pick who may sign in, giving admins the Grovs admin role. Grovs relies on this list as the access list: someone Entra refuses never reaches Grovs.
Group-based assignment and provisioning need an Entra ID P1 licence. User-by-user assignment works on the free tier.
Connect it in Grovs
Create the connection
Settings → Single sign-on → Set up. Enter the issuer, client ID and client secret, the admin role value (grovs-admin), and your email domains, one per line. Saving fetches the issuer's discovery document, so a wrong tenant ID fails right here.
Verify your domains (SaaS)
Each domain shows a TXT record: name _grovs-sso.<domain>, value grovs-sso-verification=<token>. Add it at your DNS provider and press Verify. Self-hosted deployments skip this; domains are verified on save. The connection becomes active once one domain is verified.
Sign in through the organisation
Open the login page in a private window, type your work email, and press Continue with your organisation. Complete the Microsoft sign-in. You land on the dashboard with your existing role.
Require single sign-on
Back in Settings, switch on Require single sign-on and confirm. Everyone on the verified domains is signed out and can only sign in through Entra from now on.
Adding and removing domains
Domains are managed on the connection card. Add domain accepts several at once and validates each as you type. Removing a domain asks twice, the second time by typing the domain name, because everyone with an address on it loses the ability to sign in through the organisation. The last verified domain cannot be removed while enforcement is on.
Subdomains are separate: mail.example.com is not covered by example.com.
Troubleshooting
"Need admin approval" on the Microsoft screen. Admin consent was not granted. App registrations → your app → API permissions → Grant admin consent.
"This email domain is not enabled for single sign-on." The account's email is not on a verified domain of the connection. Common with guest users and with accounts whose mail attribute is on another domain. Add the domain, or use an account on a verified one.
"Your identity provider did not supply an email address." The account has neither a mail attribute nor a usable user principal name. Give the user a mail address in Entra.
Signed in as the wrong person. Microsoft keeps its own session in the browser. Grovs passes the typed email to Entra as a hint so it prompts for that account, but if you need to switch users repeatedly, sign out of Microsoft too or use a private window per user.
Locked out after enforcing. Self-hosted operators run rake sso:disable_enforce[<instance_id>] on the backend, which turns enforcement off for that project and is written to the audit log. SaaS customers contact support.