How to request and set up Microsoft single sign-on
The full end-to-end guide to Microsoft single sign-on, from your HR request through what IT creates in Azure, the setup link email, the self-service setup page, the credential fields, the redirect URI, and the admin consent IT must grant.
Microsoft (Entra ID) single sign-on lets employees sign in to CLVR Benefits with their existing Microsoft work account, so there is no separate password or sign-in link to manage. Turning it on is a short, two-part process: your HR team asks your CLVR Benefits contact to start it, and your IT or Microsoft 365 contact finishes the technical setup through a secure link. Your HR team never enters any Azure credentials.
This guide follows the whole flow from start to finish: what your HR team provides, what IT needs to brief in advance, the setup link email IT receives, the self-service setup page IT works through, what each credential field means, the redirect URI that has to match exactly, and the one admin consent IT must grant before sign-in works.
What your HR team provides
To get started, contact your CLVR Benefits contact and give them two things:
- The email domain your employees use, for example
company.com. Provide the domain only, without the@and without a full email address. - The email address of the IT or Microsoft 365 contact who will configure the connection in Azure.
That is all your HR team needs to supply. Your CLVR contact takes it from there.
What happens next
CLVR sends a secure, time-limited setup link directly to the IT contact you named. The link goes straight to IT, so your HR team does not handle any Azure credentials.
Your IT contact opens the link and follows the step-by-step instructions on the page. They create an app registration in Azure and enter three values: the Application (client) ID, the Directory (tenant) ID, and a Client secret. The email domain is filled in for them.
As soon as IT submits those details, Microsoft sign-in turns on automatically for everyone on your domain. There is nothing further for your HR team to do in CLVR.
The setup link is valid for 7 days. If it expires or gets lost before IT finishes, just ask your CLVR contact to send a new one.
What IT needs to set up Microsoft SSO
The setup page lists everything IT needs, but it helps to brief IT in advance so they can have the values ready. This is the full checklist of what your IT team creates in Microsoft Entra ID (Azure) and the three values they will paste into the form.
What IT creates in Azure
Your IT team works through five short steps in the Azure Portal, all shown on the setup page next to the form:
Create an app registration. Go to Microsoft Entra ID then App registrations then New registration. Name it something clear (for example "CLVR Benefits - Your Company"), and set Supported account types to Accounts in this organizational directory only.
Add a redirect URI. Under Authentication then Add a platform then Web, add the exact redirect URI shown on the setup page. It points back to CLVR so Microsoft knows where to return employees after they sign in.
Add the Microsoft Graph permission. Under API permissions, add Microsoft Graph then Delegated permissions, search for User.Read, add it, and then Grant admin consent for your organization. Without consent for this permission, sign-in cannot complete.
Create a client secret. Under Certificates & secrets then New client secret, copy the secret Value (not the Secret ID). The value is shown only once, so it has to be copied straight away.
Enter the credentials. Fill in the three values on the form and select Save and enable.
Briefing IT in one line
If you just need a short message to send IT ahead of the link, this covers it: create an app registration in Microsoft Entra ID for our company, add the redirect URI from the setup page, add the User.Read Microsoft Graph delegated permission with admin consent, create a client secret, then paste the Application (client) ID, Directory (tenant) ID, and client secret Value into the CLVR setup form.
Check that IT has the right access
A few steps require Azure admin rights, so IT should sign in to the Azure Portal with an administrator account, for example Global Administrator or Application Administrator. These two actions in particular need it:
- Creating the app registration.
- Granting admin consent for the User.Read Microsoft Graph permission.
If the person doing the setup cannot grant admin consent, sign-in will not work until someone with the right rights does. It is worth confirming this before they start, so they do not get blocked partway through.
The setup link email IT receives
When you request Microsoft single sign-on, CLVR sends a secure setup email straight to the IT or Microsoft 365 contact you named. IT sometimes pauses on an unexpected email asking for Azure credentials, which is sensible, so here is exactly what that email looks like. With it in hand you can confirm to your IT contact that the message is genuine before they click through.
Who sends it and what the subject says
The email comes from CLVR Benefits and lands directly in your IT contact's inbox, not yours. The subject line reads:
- Microsoft OAuth setup for [your company name]
It arrives in Swedish by default, or in English depending on the language set for the recipient. The body and the heading both repeat that same line, so IT can match the subject to the message at a glance.
What the email says
The email explains in two short lines why it was sent:
- To enable Microsoft sign-in for your employees, CLVR needs your Azure app credentials. This is a secure, time-limited link from CLVR Benefits.
- Open the link to enter your details. Step-by-step instructions are on the page itself, and the link expires in 7 days.
There is no attachment and nothing to download. The only action is to follow the link.
The button and the fallback link
The email has one main action: an Enter credentials button. Below it, the email also prints the full setup link as plain text, introduced with "If the button does not work, copy and paste this link into your browser." So if the button is stripped or blocked by email security, IT can still copy the full address into the browser by hand.
The setup link points to the CLVR portal (an address under clvrbenefits.com). IT can check the destination before clicking by hovering over the button or reading the printed fallback link. The link contains a one-time setup token, so encourage IT to use the whole address rather than a shortened copy.
The IT self-service setup page explained
Opening the link lands IT on a self-service page where they enter your Azure app registration details, with no CLVR login required. You do not fill this in yourself: it is built for whoever manages your Microsoft Entra ID (Azure) tenant. Here is a section-by-section tour, so you can hand it off and answer questions confidently.
What the page shows
The page is titled Microsoft OAuth setup and has two halves:
- On the left, a short How we handle your data notice and the credential form.
- On the right, step-by-step Setup instructions for creating the app registration in the Azure Portal.
The intro line names the company and, when CLVR set your email domain on the link, the domain that will use Microsoft sign-in. Your HR team never sees or enters those credentials: the whole technical part stays between IT and the secure page.
The "How we handle your data" notice
Above the form, an info box explains that the credentials IT enters are stored securely, used only to enable Microsoft sign-in for your employees, and not shared with third parties. It notes that CLVR Benefits is GDPR compliant and links to the Privacy Policy and Trust Center for details, with a contact address (hello@clvrbenefits.com) for questions. This is there to reassure IT before they paste in a client secret.
Saving and the confirmation
When all four fields are filled in, IT selects Save and enable. On success the page replaces the form with a Setup complete confirmation that says Microsoft sign-in is now enabled and employees can sign in with their work account. That is the signal the handoff is done.
What happens behind the scenes
Saving does two things you should know about:
- The link IT used is marked as used, so it cannot be opened again.
- Any other setup links still pending for your company are revoked automatically. If CLVR sent more than one (for example, a resend), only the one IT completed counts, and the rest stop working.
After this, employees on the configured domain see Continue with Microsoft on the CLVR sign-in page. To confirm it is working, see confirming SSO is live.
The credential fields explained
The form asks for four values from your Azure app registration. Here is what each field means and exactly where in the Azure Portal IT finds the value, so you can help orient your IT contact before they start. The fields, top to bottom, are:
- Email domain
- Application (client) ID
- Directory (tenant) ID
- Client secret
All four are required. The form cannot be saved until each one is filled in; if any field is empty, saving returns "All fields are required".
Email domain
This is the part of your work email after the @ sign, for example company.com, entered on its own with no @ symbol and no name in front of it. CLVR uses it to decide which employees sign in with Microsoft. In most setups your CLVR contact fills this in for you when they create the link, in which case the field is shown but locked. If the link was sent without a domain, IT types it in, without the @ (just company.com).
Application (client) ID
A unique ID for the app registration your IT team created in Azure. The field description on the form reads "Found on the Overview page of your app registration". In the Azure Portal it appears on the app registration Overview page, labeled Application (client) ID. It looks like a long string of letters and numbers in five groups (for example xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx).
Directory (tenant) ID
An ID for your organization's Microsoft directory (your Entra ID tenant). The form description reads "Found on the same Overview page, below the Application ID". It sits right under the Application (client) ID on the same Overview page, labeled Directory (tenant) ID, and has the same five-group format.
The client ID and tenant ID are both on the one Overview page, one above the other, so IT can copy both in the same place. They are identifiers, not passwords, so they are not hidden.
Client secret
This is the one true password among the four, so it needs the most care. IT creates it in Azure under Certificates & secrets. When a new client secret is created, Azure shows two columns: Value and Secret ID.
- Copy the Value column. That is what goes in this field.
- Do not copy the Secret ID. It is a different string and will not work for sign-in.
The form spells this out in the field description: "The 'Value' column (not 'Secret ID') from Certificates & secrets". On the CLVR form, the field behaves like a password field, so the characters are masked as IT types or pastes.
Azure shows the secret Value only once, right after it is created. If IT navigates away from the Certificates & secrets page without copying it, the value can no longer be read and a new secret has to be created. Ask your IT contact to copy the Value into the form straight away.
The redirect URI explained
The redirect URI is the one web address Microsoft sends your employees back to after they sign in, and it is the part of setup most likely to cause a "something went wrong" error if it is even slightly off. IT does not enter it on the CLVR form; they register it in Azure as part of the app registration.
What the redirect URI is
When an employee signs in with Microsoft, they leave CLVR Benefits, prove who they are with Microsoft, and are then handed back to CLVR to finish signing in. The redirect URI is the exact return address Microsoft uses for that final hand-back. For every company it is the same value:
https://app.clvrbenefits.com/api/auth/oauth/microsoft/callback
That address is built from the CLVR Benefits web app, so it is the live production address. It is never a personal device, a local test URL, or your own company's domain.
Why it has to match exactly
Microsoft will only send an employee back to a return address that has been registered in advance, character for character. Your IT contact registers this value in your company's Microsoft (Entra ID) app registration, under Authentication, by choosing Add a platform and then Web. When the registered value and the value CLVR uses match, sign-in completes. When they do not, Microsoft refuses the request and the employee never reaches CLVR.
Common ways the value drifts out of match:
- Using http instead of https.
- Dropping or changing any part of the path, which must end in
/api/auth/oauth/microsoft/callback. - Adding a trailing slash at the end.
- A typo anywhere in the address.
Your IT contact does not have to type any of this. The secure setup page CLVR sends shows the exact redirect URI in a copy-ready code block, so the safest approach is always to copy it from there and paste it straight into Azure.
Why IT must grant admin consent for User.Read
Microsoft single sign-on needs exactly one permission to work: the Microsoft Graph delegated permission User.Read. CLVR Benefits uses it to read the signed-in employee's work email and basic profile so it can match them to their CLVR account. Here is where IT adds the permission, why an administrator must grant consent, and what CLVR does (and does not) read.
The one permission SSO needs
When an employee signs in with Microsoft, CLVR asks Microsoft for the User.Read permission. After the employee approves on Microsoft's screen, CLVR reads their basic details from Microsoft Graph and uses the email to find the matching employee in your company's CLVR account. That is the whole exchange: no mailbox access, no calendar, no files, no directory browsing.
CLVR reads only:
- The employee's work email, which is how CLVR matches them to their CLVR account.
- Basic profile fields (such as display name) that come with that same call.
The name shown inside CLVR comes from the employee record your HR team set up, not from Microsoft, so the profile read is only ever used to confirm identity at sign-in.
Where IT adds User.Read
On the Azure app registration your IT contact creates for CLVR, the permission lives under API permissions:
User.Read is a standard, low-privilege Microsoft permission. In many tenants it is already present by default on a new app registration, so IT may only need to confirm it is listed rather than add it.
Why admin consent is required
Adding the permission is not enough on its own. An administrator for your Microsoft tenant must approve it for the whole organisation by selecting Grant admin consent for [your organization] on the same API permissions page. Until that button has been used and the permission shows a green "Granted" status, employee sign-in cannot complete.
The person granting consent needs administrator rights in your Microsoft tenant, such as Global Administrator or Application Administrator. A regular employee account cannot grant consent for the organisation.
Granting admin consent once covers every employee, so individual employees are never prompted to approve anything themselves.
What employees see if consent is missing
Without admin consent, sign-in starts but cannot finish. A typical sign-in attempt looks like this:
- The employee selects Continue with Microsoft and is sent to Microsoft to sign in.
- They authenticate successfully with their Microsoft work account.
- They are returned to CLVR with an error instead of their dashboard, because CLVR was never allowed to read the profile it needs to identify them.
If employees report that Microsoft sign-in "loops back" or ends on an error page right after authenticating, missing admin consent is one of the first things to check.
What employees see once it is live
After setup is complete, anyone signing in with a work email on your domain sees a short notice and a single Continue with Microsoft button, with no other options. Employees do not need to do anything to switch over: CLVR detects Microsoft sign-in from their email domain automatically. To confirm it took effect, see confirming SSO is live.
Troubleshooting
- The setup link expired or shows "Invalid or expired link". Setup links are valid for 7 days, and each one works only once. An expired link cannot be reactivated, and once a new one is sent, older pending links for your company stop working. Ask your CLVR contact to send a fresh link to your IT contact.
- IT is not sure the email is genuine. Confirm the three things above: it comes from CLVR Benefits, the subject is "Microsoft OAuth setup for [your company name]", and the only action is an Enter credentials button leading to a clvrbenefits.com setup page. If IT still wants reassurance, you or your CLVR contact can confirm it directly.
- The button in the email does nothing. Have IT use the full link printed under the button instead, copied into the browser address bar in one piece.
- IT never received the email. Check spam and quarantine, and confirm with your CLVR contact that the email address you supplied for IT was correct.
- IT cannot complete the form, or lacks the right Azure access. A few steps need an administrator account (Global Administrator or Application Administrator) to create the app registration and grant admin consent. Loop in whoever manages your Microsoft tenant.
- IT cannot edit the Email domain field. That is expected when CLVR set the domain on the link. If the domain is wrong, ask your CLVR contact for a corrected link rather than working around it.
- IT is unsure which value goes where. The client ID and tenant ID are both on the app registration Overview page; the secret comes from Certificates & secrets. Each field has a hint, and the instructions on the right repeat this next to the form.
- The secret value can no longer be seen in Azure. Azure shows the secret Value only once, so it cannot be recovered. IT creates a new client secret and uses its Value instead.
- Sign-in fails after setup, even though the form saved. The most common cause is the wrong client secret: check that IT copied the Value column and not the Secret ID, and that the secret has not expired. If in doubt, IT can create a fresh client secret in Azure and your CLVR contact can send a new setup link.
- Microsoft shows a reply-URL or redirect mismatch error. The registered redirect URI does not match. Re-copy
https://app.clvrbenefits.com/api/auth/oauth/microsoft/callbackfrom the CLVR setup page and compare it character by character to what is in Azure, watching for a trailing slash, http instead of https, a missing path, or a stray space. If no redirect URI is listed at all, add it as a Web platform redirect under Authentication. - Employees reach Microsoft but land on an error in CLVR. Confirm User.Read is listed under API permissions and that Grant admin consent has been used, so the permission shows as granted for your organisation. If the Grant admin consent button is greyed out, the signed-in person does not have the rights to consent; ask someone with Global Administrator or Application Administrator rights to grant it.
- Sign-in still shows a sign-in link or password. Microsoft sign-in only applies to the exact domain you provided. If some employees use a different email domain, mention it to your CLVR contact so it can be covered too.