Setup Guide - Okta SAML SSO

Configuring SAML SSO with Okta

Use this guide to connect LinearB to Okta using SAML 2.0 so your team can log in with corporate credentials instead of passwords.

---

Overview

What this guide covers

• Creating a SAML 2.0 application in Okta for LinearB
• Configuring SAML settings (ACS URL, Entity ID, NameID)
• Connecting Okta to LinearB’s SSO settings
• Testing and enforcing SSO for your users

Before you begin

• Okta Admin access
• LinearB Admin role
• Your LinearB SSO settings page open:
  Settings → SSO

---

Step 1: Create the LinearB SAML App in Okta

1. In Okta, go to Applications → Applications.
2. Click Create App Integration.
3. Select SAML 2.0 as the sign-in method and click Next.
4. Under General Settings:
   • App name: LinearB (or your preferred label)
   • App logo: (optional) upload the LinearB logo
5. Click Next.

---

Step 2: Configure SAML Settings in Okta

Use the values from your LinearB SSO settings page to configure Okta.

Required SAML settings

• Single sign-on URL (ACS URL)
  Copy from Single Sign-On URL in LinearB.
• Audience URI (SP Entity ID)
  https://app.linearb.io/login
• Name ID format
  EmailAddress
• Application username
  Email (recommended)
• Leave Attribute Statements optional unless your security team requires additional claims.

Finish the SAML app wizard

1. Click Next to move to the Feedback tab.
2. Select I'm an Okta customer adding an internal app.
3. Click Finish.

---

Step 3: Assign Users or Groups

1. Open your new LinearB SAML application in Okta.
2. Go to the Assignments tab.
3. Click Assign → People or Groups.
4. Select the users or groups who should have access to LinearB.
5. Click Assign, then click Done.

Tip: Start with a small pilot group to validate SSO before rolling out to your entire organization.

---

Step 4: Connect Okta to LinearB SSO Settings

Copy the IdP values from Okta into LinearB.

1. In Okta, open the Sign On tab of your LinearB app.
2. Click View SAML setup instructions.
3. In LinearB, go to Settings → SSO.
4. Copy the following values from Okta into LinearB:
   • Identity Provider Issuer
   • Identity Provider SSO URL
   • X.509 Certificate
   • Organization Email Domain (for example example.com)
5. Click Save in LinearB.
6. Toggle SAML Authentication to ON.

Optional: Enforce SSO

To require all users to sign in via Okta, enable:
“Team members will only be able to access LinearB using your SSO provider.”

---

Step 5: Test and Validate SSO

Validate the configuration using the following tests.

Test from Okta

• Open the Okta End-User Dashboard.
• Click the LinearB application tile.
• Expected result: You are logged into LinearB without entering a password.

Test from LinearB

• Navigate to the LinearB login page.
• Click SSO.
• Enter your email and follow the redirect to Okta.
• Expected result: Okta authenticates you and redirects you back to LinearB.

---

Troubleshooting

Invalid Audience or Entity ID mismatch

Verify the Audience URI in Okta is exactly:
https://app.linearb.io/login

Login loop between Okta and LinearB

Check that the Single sign-on URL in Okta matches the LinearB Single Sign-On URL.

User not found or unauthorized

Confirm the user:

• Is assigned to the LinearB app in Okta
• Has the same email address in LinearB

Certificate errors

Ensure the X.509 certificate in LinearB matches the active certificate configured in Okta.

---

FAQs

Do I need SCIM if I use SSO?
No. SSO controls authentication. SCIM is optional and provides automated user provisioning.

What happens to existing password users?
Users can still sign in using their existing method unless SSO enforcement is enabled.

What role do new SSO users get?
New users created via SSO start as Viewer. Admins can change roles in Users & Teams.

Can we use multiple identity providers?
No. Only one SAML configuration is supported per LinearB organization.

---

Still stuck?
Contact LinearB support at linearb.zendesk.com and include screenshots of your Okta SAML settings and the LinearB SSO configuration.

Next steps:

• Return to the Enterprise Setup Guide
• Explore LinearB features and dashboards