Sign in with your organisation's identity provider
Employees can sign in to Monotree with the account they already use at work, through your organisation's identity provider (IdP). This page is for the IT administrator who sets it up at the IdP.
Monotree uses OpenID Connect (OIDC). It works with any OpenID Connect provider, for example Microsoft Entra ID (Azure AD), Google Workspace or Okta. SAML is not supported.
How it works
- You register Monotree as an application at your IdP and send us a few details (see below).
- Monotree sets up the provider on your Monotree server. There is no setting for this in the CMS.
- The Monotree login page now shows a Continue with <name> button, for example Continue with Microsoft. For Microsoft, Google and Okta the button shows their logo.
- An employee clicks the button, signs in at your IdP, and comes back to Monotree signed in.
Password login stays available next to the button.
Set up your identity provider
Register a new web application at your IdP. In Microsoft Entra ID this is App registrations → New registration, with the platform Web.
| Setting | Value |
|---|---|
| Redirect URI | https://<your-monotree-domain>/sso/callback, for example https://acme.monotree.com/sso/callback |
| Client secret | Create one |
| Scopes | openid, email and profile (the standard ones) |
Use your main Monotree domain in the redirect URI, for example acme.monotree.com. If your employees also reach Monotree on another domain, still use the main one. Ask your Monotree contact if you are not sure which domain is the main one.
Send us the details
Send these to your Monotree contact:
| Detail | Example |
|---|---|
| Issuer | Entra ID: https://login.microsoftonline.com/<tenant-id>/v2.0 |
| Client ID | The application (client) ID from your IdP |
| Client secret | The secret you created |
| Button name | The name on the login button, for example Microsoft |
| Email domains | The domains whose users may sign in, for example acme.com. At least one is required |
Who can sign in
Monotree does not create users from the IdP. A person must already exist in Monotree, through your HR integration or created in the CMS, before they can sign in with the IdP.
- The first sign-in links by email. Monotree reads the
emailclaim and finds the user with that email. In Entra ID, users without a mailbox may have noemailclaim. Then Monotree usespreferred_username(the UPN) instead, if it is an email address. - The email must be under one of your email domains. Other emails cannot sign in, even if the person exists in Monotree.
- The email must be verified. If your IdP sends
email_verified, it must betrue. If the IdP does not send it, as Entra ID does not, this check is skipped. - After the first sign-in, the IdP's user ID counts. Monotree remembers the IdP's user ID (
sub). If the email changes later at the IdP, the person can still sign in. - One Monotree account links to one IdP identity. If an account is already linked to a different IdP identity, for example because the IdP account was deleted and created again, the sign-in is refused. Ask Monotree support to remove the old link.
- Invited users can sign in. A user who was invited but has not registered yet counts as registered after their first IdP sign-in.
- Banned and terminated users cannot sign in.
- Several accounts: someone with more than one Monotree account signs in to the account that has the email the IdP sends.
Two-factor authentication
A sign-in through your IdP counts as two-factor authentication in Monotree. If two-factor authentication is on, employees who sign in through the IdP do not get an SMS code. Turn on multi-factor authentication (MFA) at your IdP.
When a sign-in fails
The employee sees a Sign-in did not complete page with one of these messages.
| Message | What it means |
|---|---|
| There is no account for this email. Ask your administrator to add you, then try again. | No Monotree user has this email. Add the person in Monotree or in your HR integration. |
| Your account is not active. | The Monotree user is banned or terminated. |
| Your identity provider has not verified your email address. | The IdP sent email_verified with a value other than true. |
| This email address is not allowed to sign in here. | The email is not under one of the email domains you sent us. |
| Your identity provider did not share an email address, so we could not find your account. | The IdP sent no email claim, and no preferred_username that is an email address. Check that the email scope is allowed. |
| This email belongs to an account that is already linked to another identity. Ask your administrator. | The Monotree account is linked to a different IdP identity. Ask Monotree support to remove the old link. |
| Your identity provider could not be reached. Please try again. | Monotree could not reach the IdP. If it keeps happening, the issuer may be wrong. |
| Your identity provider did not accept the sign-in. Please try again. | The IdP refused Monotree's request. A wrong or expired client secret is the usual cause. |
| Your identity provider did not approve the sign-in. | The IdP sent back an error instead of a sign-in, for example because the employee cancelled. |
| Your identity provider sent an answer we could not verify. Please try again. | The IdP's answer did not pass Monotree's checks. Contact Monotree support. |
| This sign-in link has expired or was already used. Please start again. | The sign-in took too long, or the browser went back to an old page. Start again from the login page. |
If the redirect URI at your IdP does not match, the IdP shows its own error page, and the employee never reaches Monotree.
In the Monotree app
The Monotree app shows the same Continue with <name> button on its login screen. It opens your IdP's sign-in page in the phone's browser and then returns to the app, signed in. The same rules apply as on the web.