Setting up Okta SAML

This document outlines the setup process for integrating SAML-based Okta with Abacus.AI for Single Sign-On (SSO). It also includes best practices, security requirements, and answers to commonly asked enterprise questions.

• Overview
• Using SAML
• Security & Access Control
• Common Errors
• Troubleshooting and FAQ

Overview

Okta can be used to integrate with Abacus.AI for Single Sign-On (SSO) using either OAuth or SAML. This document provides step-by-step instructions for SAML, along with details on security requirements and troubleshooting. The OAuth instructions can be found here.

Using SAML

Step 1: Create a SAML Application in Okta

1. Log in to your Okta Admin Console.
2. Go to Applications → Click Create App Integration.
3. Select SAML 2.0 as the sign-in method.
4. Click Next, give your application a name (e.g., Abacus.AI), and optionally upload a logo.

Step 2: Configure SAML Settings

Pleasee confirm the Abacus.AI organization you want to sign into. We’ll need the subdomain of the org, and it’ll be difficult to change it once this is set up and running in prod.

1. Set the following configuration:
   • Single Sign-On URL: https://abacus.ai/api/samlSignIn
   • Audience URI (SP Entity ID): https://<subdomain>.abacus.ai

2. [Optional] Set "Default RelayState". By default we land user on https://.abacus.ai, which is the chat interface.

   • If your use cases are not chat related, you may want to set this as https://abacus.ai/app/projects, which lands on the projects list page.
   • Be careful that once you set an URI under https://abacus.ai/, we by default treat new users as platform user, who can have access to the projects and data.
   • We assume you will gate on who can be added as platform users to have more permissions.

3. Under "Attribute Statements (claims)", set the following attributes:

   • email = user.email
   • firstName = user.firstName
   • lastName = user.lastName

4. [Optional] Set group attributes if needed:
   • Use the name groups.
   • We suggest making group names descriptive and unique (e.g., include words/characters to identify the group is for your organization).

Step 3: Share Metadata with Abacus.AI

1. Go to your application in the Okta Admin Console.
2. Click on "Sign on" on the right of the General tab.
3. Click "View SAML setup instructions on the right to access the metadata.
4. Share the following information with Abacus.AI at connectors@abacus.ai:
   • Option 1: Provide the IdP metadata file (this contains all of the necessary information, including the x509 certificate and issuer URL).
   • Option 2: If the IdP metadata is not availble, then please provide the following:
     • Identity Provider Issuer URL
     • X.509 certificate
     • Audience URI (SP Entity ID): This is your Abacus.AI organization subdomain (e.g., https://<subdomain>.abacus.ai).

Step 4: Test the Integration

1. Go to your application, click Sign on on the right of General, then click View SAML setup instructions.
2. Test the integration by signing in with SAML.

Security & Access Control

• Signed Responses: Signed SAML responses are required. Unsigned responses will be rejected.
• Session Expiration: Sessions expire after 24 hours of inactivity.
• Re-authentication: Re-authentication is required after logout.
• JIT Provisioning: New users are auto-created in Abacus.AI on first login based on SAML assertion attributes.

Common Errors

1. Invalid Audience URI (Entity ID mismatch):
   - Error: "Audience URI is invalid" or "Invalid recipient."
   - Cause: The audience or Entity ID in your IdP is incorrect.
   - Fix: Match exactly with https://<subdomain>.abacus.ai. Watch for typos or slashes.

2. Missing or Mismatched Attributes:
   - Error: "Invalid login" or user isn’t created via JIT provisioning.
   - Cause: Required attributes like email, firstName, or lastName are missing.
   - Fix: Ensure these are mapped and correctly named in IdP settings.

3. Invalid or Expired x509 Certificate:
   - Error: "Signature validation failed" or "Untrusted certificate."
   - Cause: Expired or mismatched certificate.
   - Fix: Renew the certificate and share the updated one with support.

Troubleshooting and FAQ for Okta SAML SSO

Debugging Tip:
- Use browser extensions like SAML-tracer to inspect assertions, detect missing attributes, or identify signature issues.

Can we restrict login to specific email domains?

• Yes, we currently restrict it to your registered org’s domain in the Abacus.AI platform

What is the landing page for users?

• By default, the landing page is https://<subdomain>.abacus.ai . If you need a different page, please contact us at support@abacus.ai.

How do I find my subdomain?

• It’s in the URL to access the chat app interface for your organization. If you're unsure, please contact support.

Can I test before going live?

• Yes. We recommend testing with a few users before rolling out org-wide.

What if my certificate expires?

• Update the certificate in your IdP (Okta) and send the new x.509 cert to us at connectors@abacus.ai.

How can I disable or remove the integration?

• Remove the SAML application from your IdP or disconnect from your Abacus.AI organization settings. Reach out to support if you need assistance.

Where can I access user login logs?

• Admins can access authentication logs from your identity provider's dashboard (e.g., Okta) to review user sign-ins, failures, and SAML assertions. For any issues traced back to Abacus.AI, please contact our support team.