Setting up SSO with Okta

Okta is one of three identity providers iShared.app supports for single sign-on, alongside Microsoft Entra ID and Google Workspace. This guide walks through connecting Okta via SAML 2.0 and, optionally, turning on SCIM so Okta can automatically create, update, and deactivate accounts in your iShared.app organization.

You'll need Admin or Primary Owner access to your iShared.app organization, and Application administrator access in Okta.

Before you start

Open Settings → Single sign-on in iShared.app in one browser tab, and the Okta Admin Console in another. You'll be copying values back and forth between the two.

Step 1: Create a SAML app in Okta

1. In the Okta Admin Console, go to Applications → Applications and click Create App Integration.
2. Choose SAML 2.0 and click Next.
3. Give the app a name (e.g. "iShared.app") and click Next again.
4. On the SAML settings screen, leave this tab open — you'll fill in the Single sign-on URL and Audience URI in Step 3, after you know your organization ID.

Step 2: Start the connection in iShared.app

1. In iShared.app, go to Settings → Single sign-on.
2. Set Provider to Okta.
3. Set Protocol to SAML 2.0.
4. The card now shows your SP metadata URL, in the form <API base>/auth/sso/saml/<orgId>/metadata. This URL contains your organization's unique ID — you'll need pieces of it for Okta's SAML settings.

Step 3: Finish the Okta SAML settings

Back in the Okta app you started in Step 1:

• Single sign-on URL: the ACS URL from your SP metadata (the same base, with /acs instead of /metadata).
• Audience URI (SP Entity ID): your SP metadata URL itself.
• Name ID format: EmailAddress.
• Application username: Email.

Save the app. Okta will show you a View SAML setup instructions link — open it, and copy three values:

• Identity Provider Single Sign-On URL
• Identity Provider Issuer (the IdP Entity ID)
• X.509 Certificate (the signing certificate, including the -----BEGIN CERTIFICATE----- / -----END CERTIFICATE----- lines)

Step 4: Complete the connection in iShared.app

Back in Settings → Single sign-on, fill in:

• IdP Entity ID: the Identity Provider Issuer from Okta.
• IdP SSO URL: the Identity Provider Single Sign-On URL from Okta.
• IdP signing certificate (PEM, -----BEGIN CERTIFICATE-----): paste the full certificate, including the header/footer lines.

Check Enabled, then click Save.

At this point, members can sign in via SSO from the login page, but only if they already have an invited or active membership in your organization — SAML alone doesn't create new accounts. To assign the app to people in Okta and have accounts appear automatically, turn on SCIM (next step) or invite members manually from Team.

Step 5: Turn on SCIM provisioning (recommended)

SCIM keeps your Okta directory and your iShared.app organization in sync: assigning someone to the app in Okta creates their iShared.app account, removing them deactivates it, and there's no separate invite step.

1. In Settings → Single sign-on, scroll to SCIM provisioning and choose Okta as the provider.
2. Click Generate token. Copy the value immediately — it's only shown once.
3. Note the SCIM base URL shown above it, in the form <API base>/scim/v2.
4. Back in the Okta Admin Console, open your app and go to the Provisioning tab, then Configure API Integration.
5. Check Enable API integration, paste the SCIM base URL into the Base URL field and the token into the API Token field, then click Test API Credentials.
6. Once the test passes, enable Create Users, Update User Attributes, and Deactivate Users under Provisioning to App.
7. Assign people or groups to the app under the Assignments tab. Each assignment provisions an account in iShared.app within a few minutes.

Accounts created via SCIM authenticate through SSO only — no password is set, so there's nothing to phish or leak. When someone leaves the group or is deactivated in Okta, SCIM removes their seat in iShared.app automatically, so you don't pay for licenses no one is using.

Requiring SSO org-wide

Once you've confirmed a few people can sign in successfully, go back to Settings → Single sign-on and check Require SSO. This blocks password login for everyone in the organization except the primary owner, who keeps password access as a break-glass fallback in case your Okta tenant is ever unreachable. Turn this on only after you've verified SSO works — otherwise you risk locking out members who haven't been provisioned yet.

Troubleshooting

"Invalid document signature" or login fails silently: double-check the certificate was pasted in full, including the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- lines, with no extra whitespace.

A user can't sign in even though SSO is configured: if SCIM isn't enabled, the user needs an existing invite or membership in iShared.app before their first SSO login will succeed — SAML confirms who someone is, not that they're allowed into your organization. Either invite them from Team first, or enable SCIM so assignment in Okta handles it automatically.

For Google Workspace, which has no SCIM support and instead uses just-in-time provisioning, see the Google Workspace SSO guide. For Microsoft's identity platform, see the Microsoft Entra ID SSO guide.