Set up SSO with Microsoft Entra ID
Create an enterprise application for Lingo.dev in Microsoft Entra ID, assign users, connect it to your organization, and provision members over SCIM.
This guide connects Microsoft Entra ID to Lingo.dev over SAML 2.0. You need at least the Cloud Application Administrator role in Entra, and you must be an Owner of a Lingo.dev organization on the Enterprise plan. For how SSO works in Lingo.dev, see Single sign-on.
Keep Settings → SSO open in Lingo.dev. You copy two values from it into Entra.
Create the enterprise application #
- Sign in to the Microsoft Entra admin center.
- Go to Entra ID → Enterprise apps → All applications and select New application.
- Select Create your own application.
- Type
Lingo.devas the name, choose Integrate any other application you don't find in the gallery (Non-gallery) and select Create.
Configure SAML #
- In the new application, open Single sign-on and choose SAML.
- In Basic SAML Configuration, select Edit.
- Under Identifier (Entity ID), select Add identifier and paste
https://auth.lingo.dev/auth/v1/sso/saml/metadata(the Entity ID in Lingo.dev). - Under Reply URL (Assertion Consumer Service URL), select Add reply URL and paste
https://auth.lingo.dev/auth/v1/sso/saml/acs(the ACS URL in Lingo.dev). - Leave Sign on URL, Relay State and Logout Url empty for now. Select Save. You set Sign on URL after you connect, in Sign in from Microsoft My Apps.
Keep the default Attributes & Claims. Apps created in the Entra admin center send the user's email in the emailaddress claim, from user.mail, and an email-format Name ID. Make sure every user who signs in has an email address in Entra.
An app created without the default claims, for example through the Microsoft Graph API, sends no email. Sign-in then fails with "Your identity provider didn't send an email address." In Attributes & Claims, add the email claim with the source attribute user.mail.
Copy the metadata URL #
In SAML Certificates, copy App Federation Metadata Url.
Assign users and groups #
- In the application, open Users and groups and select Add user/group.
- Under Users and groups, select None Selected, pick the users or groups, and select Select.
- Select Assign.
- Open Properties, set Assignment required? to Yes and select Save.
With Assignment required? set to Yes, only assigned users can sign in to Lingo.dev through Entra. With No, every user in your tenant can reach the app, including guest accounts. Lingo.dev still lets only accounts at your connected domains join; it signs anyone else out again. Apps created through the Microsoft Graph API start with No. Assigning groups needs Microsoft Entra ID P1 or P2. On the free tier, assign users one by one.
Connect in Lingo.dev #
- Open Settings → SSO.
- Paste the App Federation Metadata Url into Identity provider metadata URL.
- In Email domains, type your company's email domains, separated by commas.
- Select Connect.
See Domain rules if a domain is refused.
Test the sign-in #
- Open a private browser window and go to the Lingo.dev sign-in page.
- Select Continue with SSO, type the email of an assigned user and select Sign in.
- Sign in with Microsoft.
You return to Lingo.dev as a member of the organization. Check the email shown on the organizations page: it's the account Microsoft signed in, not necessarily the email you typed. If the browser is already signed in to Microsoft, for example as the admin who set up the app, Microsoft continues as that account without asking for a password. That's why the test needs a private window.
Start the test from Lingo.dev rather than the Test button in Entra. Until you set Sign on URL, the Lingo.dev tile in Microsoft My Apps doesn't sign you in: you land on the Lingo.dev home page, still signed out.
If your tenant uses security defaults, Microsoft asks each user to register an authenticator app on their first sign-in. That can take longer than Lingo.dev waits, about 5 minutes, and the first attempt fails with "Single sign-on took too long to finish. Try again." Trying again works.
When the test works, you can require SSO. First make your own SSO account an Owner, as described in Turn it on.
Sign in from Microsoft My Apps #
Set Sign on URL so the Lingo.dev tile in My Apps signs people in.
- In Lingo.dev, open Settings → SSO and copy Dashboard sign-in link. It looks like
https://lingo.dev/auth/sso?domain=example.com. - In Entra, open the Lingo.dev application and select Single sign-on.
- In Basic SAML Configuration, select Edit.
- Paste the link into Sign on URL. Select Save.
Now the Lingo.dev tile in My Apps opens the link. Lingo.dev sends the user to Microsoft and back, signed in, without asking for an email.
Provision members with SCIM #
Entra can manage Lingo.dev members over SCIM and set their roles through groups. Set up SSO with this guide first. For how SCIM works in Lingo.dev, see Provision members with SCIM.
- In Lingo.dev, generate a SCIM key.
- In Entra, open the Lingo.dev enterprise application and select Provisioning.
- Set Provisioning Mode to Automatic.
- Under Admin Credentials, paste the SCIM base URL from Lingo.dev,
https://api.lingo.dev/v2/scim, into Tenant URL. Paste the SCIM key into Secret Token. - Select Test Connection, then Save.
- Keep the default attribute mappings. Lingo.dev takes
userNamefromuserPrincipalNameand the work email frommail. - Under Settings, set Scope to Sync only assigned users and groups.
- Select Start provisioning.
The invite goes to the user's mail address, so every user you assign needs one at a connected domain. A userPrincipalName that differs from mail is fine.
Each user you assign gets a pending invite in Lingo.dev and becomes a member on their first SSO sign-in.
Entra provisions in cycles, about every 40 minutes, so changes and removals reach Lingo.dev on the next cycle. To send one user now, use Provision on demand.
When you unassign a user, Entra sends a deactivation, not a delete, and Lingo.dev removes their membership. See Remove people.
Set roles with Entra groups #
- Make sure the Entra group has the same name as a Lingo.dev role, such as
Translator. - Assign the group to the application in Users and groups.
Entra matches the group to the role with that name and provisions its members, who get the role. People you remove from the group lose it. If the group was a user's only assignment, removing them from it also removes them from Lingo.dev.
Troubleshooting #
| Problem | Fix |
|---|---|
Microsoft shows AADSTS700016: "Application with identifier '…' was not found in the directory". | Identifier (Entity ID) is not exactly https://auth.lingo.dev/auth/v1/sso/saml/metadata. Fix it in Basic SAML Configuration. |
Microsoft shows AADSTS50011: "The reply URL does not match the reply URLs configured for the application". | Set Reply URL (Assertion Consumer Service URL) to https://auth.lingo.dev/auth/v1/sso/saml/acs exactly. |
Microsoft shows AADSTS50105: the user isn't assigned to the application. | Assign the user, or a group they belong to, in Users and groups. |
| Someone who isn't assigned signed in, or Lingo.dev shows an email you didn't type. | Assignment required? is No, or the browser was already signed in to Microsoft as another account. Set Assignment required? to Yes in Properties, and test in a private window. |
| Lingo.dev says your email isn't at a domain your organization uses for single sign-on. | Microsoft signed in an account outside your connected domains, often a guest or the admin who created the tenant. Sign in with a work account, or add its domain in Settings → SSO. |
| Lingo.dev shows "Your identity provider didn't send an email address". | The app sends no email claim, or the user has no email address in Entra. Add the email claim (user.mail) in Attributes & Claims, and set the user's email. |
| Lingo.dev shows "Single sign-on took too long to finish. Try again." | The Microsoft sign-in took longer than about 5 minutes, often while registering an authenticator app. Try again from Lingo.dev. The next attempt works. |
| Lingo.dev shows "You're signed in, but we couldn't add you to your organization." | Sign in with SSO again. If it keeps failing, ask an Owner to check that Settings → SSO shows Connected since. |
| Lingo.dev shows "Single sign-on didn't complete". | Compare Identifier (Entity ID) and Reply URL with the values in Lingo.dev, then try again. |
Test Connection or provisioning fails with 401 Unauthorized. | The SCIM key was rotated or revoked. Paste the current key into Secret Token, or generate a new one in Lingo.dev. |
| An assigned user doesn't show in Settings → Team, on the Invitations tab. | Wait for the next provisioning cycle, or use Provision on demand. Check that the user's mail is at a connected domain. |
For other messages, see Troubleshooting.