SurfaceAI + Okta Configuration Guide

The SurfaceAI OIDC integration supports:

• Service Provider (SP) initiated SSO — users start at SurfaceAI and click Sign in with Okta.
• Identity Provider (IdP) initiated SSO — users click the SurfaceAI tile in their Okta End-User Dashboard and land signed-in in SurfaceAI.

The following are not supported:

• Just-in-Time (JIT) user provisioning. SurfaceAI accounts must be pre-provisioned (see Prerequisites).
• SCIM provisioning / deprovisioning.
• Single Logout (SLO).

Before configuring this integration, ensure that:

1. You have an active Okta org with administrator access sufficient to create OIDC application integrations.
2. You have an active SurfaceAI tenant.
3. Each user who will sign in via Okta will need to be provisioned in SurfaceAI before attempting to log in.

Users can be created via SurfaceAI’s self-service user management system.

Step 1 — Create an OIDC application in Okta

1. In the Okta Admin Console, go to Applications → Applications and click Create App Integration.

2. Select OIDC – OpenID Connect as the sign-in method.

3. Select Web Application as the application type and click

Next.

4. Enter the following values:

5. Under Assignments, assign the application to the users or groups
who should be able to sign in to SurfaceAI. Only users that have also
been provisioned in SurfaceAI will be able to complete sign-in.

6. Click Save.

Step 2 — Collect the values SurfaceAI needs

From the application’s General tab in Okta, record:

• Client ID
• Client Secret
• Okta domain / Issuer URI (for example,
  https://your-org.okta.com or `https://your-org.okta.com/oauth2/default`)

Step 3 — Provide Relevant Information to SurfaceAI

Collect these three values from Okta:

Provide this information to the SurfaceAI team using secret-sharing technology of your choosing (for instance, 1Password).

Please provide instructions for how to retrieve the information securely with operations@getsurface.ai or email with any questions.

Step 4 — Required scopes and claims

SurfaceAI requests the following standard OIDC scopes, all of which are
enabled by default in Okta:
• openid
• email
• profile

SurfaceAI uses the email claim returned from the /userinfo endpoint to look up the user’s pre-provisioned account. Ensure that the email claim issued by your authorization server matches the email address recorded for the user in SurfaceAI.

1. From SurfaceAI’s sign-in page at https://app.getsurface.ai, click
   Sign in with Okta. You should be redirected to your Okta org,
   prompted to authenticate (if not already signed in), and then
   redirected back to SurfaceAI signed-in.
2. From the Okta End-User Dashboard, click the SurfaceAI tile. You should land in SurfaceAI signed-in.

• The email claim from Okta is the sole identifier SurfaceAI uses to match an Okta user to a SurfaceAI account. If a user’s email address changes in Okta, their SurfaceAI account email must be updated to match before they can sign in again.
• Users that have not been pre-provisioned in SurfaceAI will see an authentication error after completing the Okta login. This is expected behavior; contact SurfaceAI support to provision the user.
• Single Logout (SLO) is not supported. Signing out of SurfaceAI does not end the user’s Okta session, and signing out of Okta does not end the user’s SurfaceAI session.

For help configuring or troubleshooting this integration, contact SurfaceAI support at support@getsurface.ai.

When contacting support, please include:

• The Okta org domain (for example, your-org.okta.com).
• The email address of the affected user.
• The approximate UTC time of the sign-in attempt.
• Any error message displayed by SurfaceAI or Okta.