Okta SSO + SCIM

Documentation Index

Fetch the complete documentation index at: https://docs.roark.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

What this gets you

Connecting Okta to Roark lets your team sign in with their Okta credentials. New users are auto-created in Roark on first sign-in (just-in-time provisioning), so you don’t have to invite them individually. If you also enable SCIM, Okta becomes the source of truth for user lifecycle: assigning a user pushes them into Roark before their first login, profile updates flow through automatically, and deactivating the user in Okta disables their Roark account.

---

​

How it works

SAML and SCIM are two independent channels. You can run SAML-only (JIT provisioning) and add SCIM later, or run both from day one.

• SAML authenticates the user. Okta posts the SAML response to Roark’s Cognito User Pool, which establishes the session.
• SCIM is a separate, outbound channel from Okta to Roark for user lifecycle events (create, update, deactivate).

Roark verifies you own the email domain via a DNS TXT record before activating the SSO config — preventing accidental or malicious claims on a domain you don’t control.

---

​

Before you start

• You are an OWNER of your Roark organization.
• You have admin access to your Okta tenant.
• You can publish a DNS TXT record at the apex of your email domain.
• You know which email domain your team uses (e.g., acmecorp.com). One domain per Roark org.

---

​

Step 1 — Create the SAML app in Okta

In your Roark dashboard, open Org Settings → Single Sign-On. The page shows two values you’ll paste into Okta: the ACS URL and the SP Entity ID. Keep that tab open. In the Okta Admin Console:

1. Go to Applications → Applications → Create App Integration.
2. Choose SAML 2.0 and click Next.
3. Give the app a name (e.g., “Roark”) and continue.
4. On the SAML Settings screen, fill in:

5. Add three Attribute Statements. Names are case-sensitive — type them exactly:

6. Finish the wizard. On the resulting app’s Sign On tab, find Identity Provider metadata and copy the URL.

---

​

Step 2 — Enable SAML in Roark

Back in Org Settings → Single Sign-On:

1. Paste the IdP metadata URL.
2. Enter your email domain (e.g., acmecorp.com).
3. Click Enable SSO.

Roark validates the metadata, registers the IdP with Cognito, and switches the settings page into the pending verification state with your ACS URL, Entity ID, and a DNS TXT record envelope displayed.

---

​

Step 3 — Verify your email domain

After you enable SSO, Roark issues a one-time verification token and shows a DNS TXT record envelope on the settings page. Until you publish the record and Roark confirms it, the SSO config is inert: sign-ins for the domain fall through to the non-SSO path and any SCIM token you generate will not authenticate. Copy the values from the settings page into your DNS provider:

1. Add the record at the apex of your email domain — not a subdomain like _roark.acmecorp.com. It coexists with existing TXT records on the apex (SPF, DKIM, Google site verification, and so on).
2. Wait for propagation. This is typically a few minutes, but can take up to an hour depending on your provider’s TTL.
3. Roark polls automatically in the background once the token is issued, so most admins won’t need to click anything — leave the settings page open for a few minutes after the DNS change propagates. There’s a Verify now button for an explicit check.

The token is valid for 7 days. If it expires before you publish the record, click Regenerate to issue a fresh one — regenerating invalidates any prior token, and if the row was already verified, clears that verified state as well (the new token becomes a re-attest). If another Roark org has already verified the same email domain, your verify call returns dns_record_mismatch — Roark won’t tell you which org owns it. Contact support.

---

​

Step 4 — Assign users and test

1. In Okta, open the app’s Assignments tab and assign at least one test user.
2. Have that user go to roark.ai/login, enter their work email, and submit.
3. Roark detects SSO for the domain and redirects to Okta. After authenticating, the user lands in Roark — auto-created and joined to your org if they didn’t already exist.

If sign-in fails, jump to Troubleshooting.

---

​

Step 5 (optional) — Turn on SCIM

SCIM lets Okta push user lifecycle events into Roark — useful for larger teams and required if you want Okta to deactivate Roark accounts automatically.

1. In Roark, on Org Settings → Single Sign-On → Okta, click Generate SCIM token. Copy both the base URL and the bearer token. The token is shown once.

2. In Okta, open the same SAML app and go to the Provisioning tab. Click Configure API Integration.

3. Check Enable API integration, paste the SCIM base URL and bearer token, and click Test API Credentials. Save.
4. Under Provisioning → To App, enable:
   • Create Users
   • Update User Attributes
   • Deactivate Users

5. Assign users (or groups) to the app. Okta will create or link Roark accounts on assignment.

---

​

Auto-join projects (optional)

By default, new SSO and SCIM-provisioned users are added to your organization but no projects. To onboard them into a default set of projects automatically:

1. Go to Org Settings → Single Sign-On → Auto-join projects.
2. Pick the projects new users should land in.
3. Save.

From then on, every user provisioned via JIT or SCIM is auto-added to those projects. Existing users are unaffected.

---

​

What happens for existing Roark users

Account linking only takes effect once the domain is verified — until then, SCIM POST /Users is rejected (the token doesn’t authenticate) and SAML sign-ins fall through to the non-SSO path. Roark links existing accounts (password or Google) to Okta by email — no duplicates, no data loss. The user keeps their user ID, history, and project memberships.

• JIT path: linking happens on first SSO sign-in. Roark finds the user by email and merges Okta into their identity providers.
• SCIM path: when Okta sends POST /Users for an existing user, Roark responds 200 (link) instead of 201 (create) and records the Okta externalId. The user does not need to sign in for this to take effect.

If the email belongs to a different active Roark org, SCIM responds 409 (uniqueness). To resolve, remove the user from the other org and retry, or contact support.

---

​

Deprovisioning

• Unassign in Okta (SAML only): the user can’t start a new session. Existing sessions expire within ~1 hour.
• SCIM PATCH active=false: the user is marked INACTIVE, their Cognito record is disabled, and their project memberships are removed. If you later re-activate them in Okta, their org membership and prior project memberships are restored.

---

​

Disabling SSO

From Org Settings → Single Sign-On, click Disable SSO. Roark removes the IdP from Cognito. Active sessions keep working until the token expires (within an hour). Users with a linked password or Google identity can still sign in that way; SSO-only users will be locked out until you re-enable. Disabling SSO does not clear domain verification. If you re-enable with the same email domain later, the prior verification still stands. If you re-enable with a different email domain, you’ll need to verify the new one.

---

​

Troubleshooting

• “Invalid SAML response received” — Cognito couldn’t fetch your IdP metadata. Confirm the metadata URL is publicly reachable and returns valid XML.
• User signs in but is treated as new — the email in the Okta profile doesn’t match the one on the existing Roark account. Update the Okta user’s email to match, or contact support to relink.
• “Email domain is already claimed” — another Roark org has already enabled SSO for this domain. Contact support.
• SSO check times out at login — Roark couldn’t look up the SSO provider for that domain. Check your network/firewall to roark.ai and confirm the email domain exactly matches what you configured.

Domain verification returns one of the following results. The settings page surfaces these on every Verify now click; transient misses during background polling stay silent.

• dns_record_not_found — no TXT record at the apex carries the roark-domain-verification= prefix. Confirm you added the record at the apex (not _roark.acmecorp.com) and allow time for DNS propagation — typically minutes, sometimes up to an hour depending on your provider’s TTL.
• dns_record_mismatch — a record with the roark-domain-verification= prefix exists, but its token doesn’t match the one Roark issued. Two common causes: you regenerated the token after pasting the old value (paste the new one), or another organization is concurrently attempting to claim the same domain (only one will win — contact support if you believe this is your domain).
• token_expired — the issued token is past its 7-day TTL. Click Regenerate and paste the fresh value.
• dns_lookup_failed — DNS resolution itself errored. Usually transient; retry. If it persists, confirm the domain resolves at all (dig TXT acmecorp.com).
• verified — success. The SSO config is now active end-to-end; SAML sign-ins and SCIM provisioning will route.

---

​

Limitations

• IdP-initiated SAML Single Logout is not supported. Logging out of Okta does not end Roark sessions; existing sessions expire on their own within ~1 hour.
• One email domain per Roark org. If your team uses multiple domains, reach out.
• Wildcard or sub-domain claims are not supported — verification and the email-domain match are exact at the apex only.
• SCIM GET /Users only honors the userName eq "<email>" filter. Okta only uses this form in practice; other filter expressions (userName co, active eq true, etc.) are ignored.

---

​

Next steps