Set up SSO with Okta
Create a SAML app for Lingo.dev in Okta, assign people, connect it to your organization, and provision members over SCIM.
This guide connects Okta to Lingo.dev over SAML 2.0. You need an Okta admin account that can create app integrations, 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 Okta.
Create the app integration #
- Sign in to the Okta Admin Console.
- Go to Applications → Applications (Applications and Resources → Applications in newer Admin Consoles) and select Create App Integration.
- Choose SAML 2.0 and select Next.
- In App name, type
Lingo.dev. Select Next.
Configure SAML #
Fill in these fields and leave the rest at their defaults:
| Okta field | Value |
|---|---|
| Single sign-on URL | https://auth.lingo.dev/auth/v1/sso/saml/acs (the ACS URL in Lingo.dev) |
| Use this for Recipient URL and Destination URL | Selected |
| Audience URI (SP Entity ID) | https://auth.lingo.dev/auth/v1/sso/saml/metadata (the Entity ID in Lingo.dev) |
| Default RelayState | Empty |
| Name ID format | EmailAddress |
| Application username |
Under Attribute Statements, add one attribute:
| Name | Name format | Value |
|---|---|---|
email | Unspecified | user.email |
With Name ID format set to EmailAddress and this email attribute, Okta sends the email address Lingo.dev needs.
Newer Okta orgs no longer show Attribute Statements while you create the app. There, add the attribute after you select Finish: on the app's Sign On tab, in the Attributes Statements section, select Add expression. Type email in Name and user.profile.email in Expression, then select Save.
Select Next. On the Feedback step, select I'm an Okta customer adding an internal app and select Finish.
Copy the metadata URL #
On the app's Sign On tab, copy Metadata URL from the Metadata details section. It looks like https://your-company.okta.com/app/exk.../sso/saml/metadata.
Assign people #
- Open the app's Assignments tab.
- Select Assign, then Assign to People or Assign to Groups.
- Select Assign next to each person or group, then Done.
Only assigned people can sign in to Lingo.dev through Okta.
Connect in Lingo.dev #
- Open Settings → SSO.
- Paste the Okta 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 person and select Sign in.
- Sign in to Okta.
You return to Lingo.dev as a member of the organization. Check the email shown on the organizations page: it's the account Okta signed in, not necessarily the email you typed. If the browser already has an Okta session, for example as the admin who set up the app, Okta continues as that account. An admin who isn't assigned to the app gets "User is not assigned to this application". That's why the test needs a private window.
Start the test from Lingo.dev. The SAML app's own tile on the Okta dashboard doesn't sign you in: you land on the Lingo.dev home page, still signed out. To sign in from the dashboard, add the bookmark in Sign in from the Okta dashboard.
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 the Okta dashboard #
To give members a Lingo.dev tile that signs them in, add a Bookmark App that opens the dashboard sign-in link. Then hide the SAML app's own icon, so members see only the bookmark.
- In Lingo.dev, open Settings → SSO and copy Dashboard sign-in link. It looks like
https://lingo.dev/auth/sso?domain=example.com. - In the Okta Admin Console, go to Applications → Applications (Applications and Resources → Applications in newer Admin Consoles) and select Browse App Catalog.
- Search for and select Bookmark App, then select Add Integration.
- In General settings, type
Lingo.devas the name and paste the link as the URL. Leave Do not display application icon to users cleared. Select Done. - On the bookmark's Assignments tab, assign the same people or groups as the SAML app.
- Open the Lingo.dev SAML app. On the General tab, select Edit in App Settings.
- Under Application visibility, select Do not display application icon to users and Do not display application icon in the Okta Mobile app. Select Save.
Keep people assigned to the SAML app. It still signs them in; it's only hidden.
Members now see one Lingo.dev tile. It opens Lingo.dev, which sends them to Okta and back, signed in, without asking for an email.
Provision members with SCIM #
Okta 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 the Okta Admin Console, open the Lingo.dev SAML app. On the General tab, select Edit in App Settings.
- Set Provisioning to SCIM and select Save. The app gets a Provisioning tab.
- On the Provisioning tab, open Integration and select Edit.
Fill in these fields:
| Okta field | Value |
|---|---|
| SCIM connector base URL | https://api.lingo.dev/v2/scim (the SCIM base URL in Lingo.dev) |
| Unique identifier field for users | userName |
| Supported provisioning actions | Push New Users, Push Profile Updates and Push Groups. Leave the import actions cleared. Okta doesn't import users or groups from Lingo.dev. |
| Authentication Mode | HTTP Header. Paste the SCIM key as the Bearer token. |
Select Test Connector Configuration. When the test passes, close it and select Save.
On the Provisioning tab, open To App and select Edit. Turn on Create Users, Update User Attributes and Deactivate Users, and select Save.
Okta sends no one to Lingo.dev until Create Users is saved. After that, each person you assign gets a pending invite in Lingo.dev and becomes a member on their first SSO sign-in.
When you unassign or deactivate a person in Okta, Okta deactivates them in Lingo.dev, which removes their membership. See Remove people.
Set roles with Okta groups #
- Make sure the Okta group has the same name as a Lingo.dev role, such as
Translator. - On the app's Push Groups tab, select Push Groups, then Find groups by name.
- Find the group and select Save.
Push a different group from the one that assigns the app. Okta doesn't support using one group for both. Okta pushes only members who are assigned to the app, so assign everyone in a pushed group directly or through another group.
Okta links the group to the role with that name. Its members get the role, and people you remove from the group lose it. If no role has the group's name, the push shows an error with "No role named". Create the role in Lingo.dev, then push the group again.
If you stop pushing a group and Okta asks whether to delete it in the app, Delete clears the role from its members. The role stays in Lingo.dev.
Troubleshooting #
| Problem | Fix |
|---|---|
| Lingo.dev shows "Single sign-on didn't complete" after you sign in to Okta. | Check Audience URI (SP Entity ID) and Single sign-on URL. They must match the Entity ID and ACS URL in Lingo.dev exactly, with no trailing slash. |
| Lingo.dev shows "Your identity provider didn't send an email address". | Set Name ID format to EmailAddress and Application username to Email, and add the email attribute statement: user.email in the setup wizard, or user.profile.email on the Sign On tab. |
| Okta says you are not assigned to the app. | Assign the person, or a group they belong to, on the Assignments tab. If you typed an assigned person's email but Okta shows your admin account, the browser kept your Okta session. Sign out of Okta or use a private window. |
| Lingo.dev shows "Single sign-on took too long to finish. Try again." | The Okta sign-in took longer than about 5 minutes, for example during first-time multi-factor setup. 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 is not set up for" your domain. | Add the domain in Settings → SSO, or check the email you typed. |
Test Connector Configuration or provisioning fails with 401 Unauthorized. | The SCIM key was rotated or revoked. Paste the current key into Integration, or generate a new one in Lingo.dev. |
| A person assigned in Okta doesn't show in Settings → Team, on the Invitations tab. | Check that Create Users is on in To App. For people assigned before you saved it, open Okta's provisioning task list and retry them. |
For other messages, see Troubleshooting.