Skip to main content

Set up Enterprise SSO with Okta

This guide connects Okta to Devs.ai using SAML 2.0. When you are done, anyone with an email address at your domain signs in through Okta instead of a Devs.ai password.

📝 Note: Enterprise SSO is an enterprise feature and is not enabled by default. To turn it on for your organization, reach out to your Devs.ai representative.

You will need: edit access to Organization Settings in Devs.ai, administrator access to your Okta org, and the list of email domains to route through Okta. See the overview for the full prerequisites.

Configuration moves back and forth between the two products, because each side needs values generated by the other. Follow the steps in order.

Step 1 — Create the connection in Devs.ai​

  1. Go to Organization Settings and select Enterprise SSO (https://devs.ai/org-enterprise-sso).
  2. Select Add Connection.
  3. Enter a Connection Name, for example Okta SSO.
  4. Set Identity Provider to Okta. This cannot be changed later.
  5. Under Domains, add each email domain you want routed through Okta, for example acme.com. Press Enter or type a comma after each one.
  6. Leave the identity provider fields empty for now — you will fill them in at Step 4 — and select Create Connection.

Step 2 — Copy the service provider values​

Open the connection you just created and find the Service Provider Configuration section. Copy these two values; each has a copy button:

  • ACS URL
  • SP Entity ID

Keep this page open in a second tab. You will come back to it.

Step 3 — Create the SAML app in Okta​

  1. In the Okta Admin Console, go to Applications → Applications.
  2. Select Create App Integration, choose SAML 2.0, then select Next.
  3. Enter an App name, for example Devs.ai. Optionally add a logo, then select Next.
  4. On the Configure SAML step, enter:
Okta fieldValue
Single sign-on URLThe ACS URL from Step 2
Audience URI (SP Entity ID)The SP Entity ID from Step 2
Name ID formatEmailAddress
Application usernameEmail
  1. Still on the same step, expand Attribute Statements and add these four statements. The names must match exactly — they are the claim names Devs.ai expects by default.
NameName formatValue
idBasicuser.id
mailBasicuser.email
firstNameBasicuser.firstName
lastNameBasicuser.lastName
  1. Select Next. On the feedback step, choose I'm an Okta customer adding an internal app, then select Finish.

Step 4 — Send the Okta details back to Devs.ai​

  1. In your new Okta app, open the Sign On tab.
  2. Find the Identity Provider metadata link and copy its URL. It looks like https://your-org.okta.com/app/<app-id>/sso/saml/metadata.
  3. Back on the Devs.ai connection page, paste it into App Federation Metadata Url and select Save Changes.

Using the metadata URL is the recommended path: Okta's endpoints and signing certificate are read directly from Okta, so a certificate rotation does not break sign-in.

If you prefer to enter the values manually, select Use manual configuration and take these from View SAML setup instructions on the Okta Sign On tab:

Devs.ai fieldOkta value
Login URLIdentity Provider Single Sign-On URL
IssuerIdentity Provider Issuer
Certificate (Base64)X.509 Certificate — save it as a file and use Upload file

Step 5 — Assign users in Okta​

Open the Assignments tab of your Okta app and assign the people or groups who should have access. Anyone not assigned in Okta cannot sign in, even if their email domain matches your connection.

Step 6 — Test and enable​

  1. On the Devs.ai connection page, confirm the header shows the Active badge. If it shows Inactive, select Enable.
  2. Have one administrator — assigned to the app in Okta — sign out and sign back in with their work email address. They should be redirected to Okta.
  3. After signing in, check that their name and email are correct in Devs.ai. If a name is missing, revisit the attribute statements in Step 3.
  4. Once the test passes, announce the change and roll out to the rest of your organization.

Okta-specific troubleshooting​

"The SAML assertion is invalid" or a generic SAML error The Single sign-on URL and Audience URI in Okta must match the ACS URL and SP Entity ID on the connection page exactly. Watch for a trailing slash or a copied newline.

Sign-in succeeds but the member has no first or last name The attribute statements are missing or misnamed. Okta attribute names are case-sensitive, so firstname will not work where firstName is expected. Alternatively, change the Attribute mapping fields in Devs.ai to whatever names your Okta app already sends.

"User is not assigned to this application" The member is not assigned to the app in Okta. Add them, or the group they belong to, on the Assignments tab.

Sign-in broke after a certificate rotation If you entered values manually, upload the new X.509 certificate to Certificate (Base64) and save. Switching to the metadata URL avoids this for future rotations.

⌘J