Okta SSO and SCIM provisioning

Use Okta as the identity provider for the Uploadcare dashboard. Users sign in with their Okta credentials over OpenID Connect (OIDC). If you also enable SCIM 2.0 provisioning, you create, update, and deactivate their Uploadcare accounts from Okta.

This guide is for Okta administrators setting up the Uploadcare app from the Okta Integration Network.

Each user has their own Uploadcare account rather than a seat in a shared workspace. Users work together by sharing projects.

Supported features

Single sign-on (OIDC)

SP-initiated SSO: the user starts from the Uploadcare sign-in page.
IdP-initiated SSO: the user starts from the Uploadcare tile in their Okta dashboard.
Just-In-Time provisioning: a user assigned to the app in Okta gets an Uploadcare account the first time they sign in.

Single sign-on works on its own: accounts are created at first sign-in, and unassigning a user in Okta stops them from signing in again. Add SCIM provisioning if you want to manage the account lifecycle from Okta.

Note: Single Logout (SLO) isn’t supported: signing out of Okta doesn’t end an open Uploadcare dashboard session.

SCIM 2.0 provisioning

Create users: assigning a user to the app creates their Uploadcare account.
Import users: Okta finds existing Uploadcare accounts linked to your organization, so you can match them to Okta users.
Update user attributes: first name and last name.
Deactivate users: unassigning a user from the app, or deactivating them in Okta, deactivates their Uploadcare account and ends their sessions. File delivery stops for projects the user owns. See What deactivation does.

Not supported: password sync, profile sourcing, deleting users, and groups (neither group push nor group import).

For definitions of these features, see the Okta Glossary.

How the two setups compare:

Behavior	SSO only	SSO with SCIM
Account creation	At first sign-in	When you assign the user
Existing accounts	Used when the user signs in	Imported and matched in Okta
Unassignment or deactivation	Blocks new sign-ins. Open sessions stay open until they expire.	Deactivates the account and ends its sessions
Reassignment or reactivation	Allows sign-in again	Restores the same account

Attribute mappings

The integration maps four attributes. Okta sets them up when you add the app.

Attribute	Value	Applied on
Username (`userName`)	Application username, set to Email	Create. Must not change afterwards.
Given name (`givenName`)	`user.firstName`	Create and update
Family name (`familyName`)	`user.lastName`	Create and update
Email (`email`)	`user.email`	Create

Uploadcare ignores the other attributes of the core SCIM User schema, but a malformed value still fails validation.

Warning: Don’t map attributes from extension schemas, such as department from the Enterprise User extension: they make Okta’s create and update requests fail with 400 invalidSyntax.

Restrictions

userName must be an email address on your registered domain. Uploadcare routes users by email domain. A user on another domain, such as a contractor using their own company’s address, can’t be provisioned, and the request fails with 400 invalidValue.
userName can’t change. Uploadcare identifies users by email address, so a request that changes it fails with 400 mutability. Contact support before you change a user’s email address in Okta.
Names use a restricted character set and length. Allowed: letters from Basic Latin, Latin-1 Supplement, and Latin Extended-A, plus digits, spaces, and these characters: , . ' / _ - !. That covers most Western and Central European alphabets. The first and last name together, including the space between them, can’t exceed 83 characters. A name that breaks either rule fails with 400 invalidValue.
Filtering supports userName eq "..." only. Other attributes and operators fail with 400 invalidFilter.
SCIM requests are rate-limited. Uploadcare accepts 90 read requests and 20 write requests per minute from your Okta org, and returns 429 with a Retry-After header beyond that.

If your setup needs something these rules don’t allow, such as users on a second email domain, contact help@uploadcare.com before you start.

Prerequisites

An Uploadcare account on the Enterprise plan.
An Okta administrator role that can add and configure app integrations: Super Admin, or an equivalent custom role.
An email domain your organization controls, such as example.com. Uploadcare routes sign-in by the domain of the user’s email address, so the domain must belong to your organization and be used only by it. Shared public domains such as gmail.com can’t be used.
One or two break-glass email addresses on that domain (optional, recommended). These addresses keep regular Uploadcare sign-in, so you can still get in when Okta is unavailable. Create and test their Uploadcare accounts before the cutover, and protect them with MFA. A break-glass account loses this exception if Okta deactivates it through SCIM. Without break-glass addresses, contact Uploadcare support if an Okta outage blocks access.
Uploadcare enables the integration for you. There’s no self-service setting in the dashboard: support sets up your organization and, if you use provisioning, gives you the SCIM token.

Configuration steps

Before you start

Turning the integration on changes how everyone on your domain signs in to Uploadcare.

Warning: From the moment Uploadcare turns the integration on, Okta is the only way to sign in for addresses on your domain. Password, email link, Google, and GitHub sign-in and new sign-ups are blocked, and users can’t start new dashboard sessions until you assign them to the Uploadcare app in Okta.

Users who are already signed in keep their sessions until they expire. Break-glass addresses keep regular sign-in.

Plan a cutover time with Uploadcare support and tell your users the date in advance. Be ready to complete steps 4 and 5 right after support confirms activation.

Steps 1, 2, 3, and 5 apply to every setup. Step 4 configures SCIM provisioning, so skip it if you use single sign-on only.

Step 1: Add Uploadcare in Okta

In the Okta Admin Console, go to Applications → Applications and click Browse App Catalog.
Search for Uploadcare, open it, and click Add Integration.
On the Sign On tab, set Application username format to Email. Uploadcare identifies users by email address.
Note the values you’ll send to Uploadcare in step 2:
- Client ID and Client secret, on the Sign On tab.
- Your Okta domain, such as https://example.okta.com. Uploadcare sends sign-in requests to this domain and uses it to recognize sign-ins started from the Okta tile.

Step 2: Contact Uploadcare support

Write to help@uploadcare.com with:

Your email domain, such as example.com. Everyone on this domain will sign in through Okta.
Your Okta domain and the Client ID from step 1.
Break-glass email addresses, if you want them.
Whether you want SCIM provisioning or single sign-on only.

Don’t include the client secret in this message: support replies with a secure way to send it.

Step 3: Uploadcare turns the integration on

Support sets up your organization, then:

Links existing Uploadcare accounts on your domain. Users who already have an account keep it, along with their projects and files, and sign in through Okta from then on. If you use SCIM, import these accounts in step 5 before you assign their users.
Turns the integration on at the agreed time and confirms when it’s done. The sign-in changes from Before you start take effect immediately.
Sends you the SCIM bearer token, if you asked for provisioning. Store it securely: it’s shown once. If you lose it, support issues a new one, which invalidates the old token immediately.

Step 4: Configure provisioning

Skip this step if you use single sign-on only.

In the Uploadcare app in Okta, open the Provisioning tab and go to Integration → Configure API Integration.
Select Enable API integration and enter the OAuth Bearer Token from step 3.
Clear Import Groups. Uploadcare doesn’t support SCIM groups.
Click Test API Credentials, then Save. The test fails until Uploadcare has turned the integration on. If it still fails, see Provisioning errors.
Go to Provisioning → To App, click Edit, and enable Create Users, Update User Attributes, and Deactivate Users. Leave Set password when creating new users off: Uploadcare ignores passwords sent over SCIM.
Check that the mappings match Attribute mappings.

Step 5: Assign users and verify sign-in

Import existing accounts

Do this first if you use SCIM and some users on your domain already have Uploadcare accounts. Otherwise, skip to Assign users.

Open the Import tab and click Import Now.
Review the Uploadcare accounts Okta finds.
Match each account to its Okta user and confirm the assignments.

Assign users

On the Assignments tab, assign everyone else who should have Uploadcare access. With provisioning, each assignment creates an Uploadcare account right away. Without it, the account is created the first time the user signs in.

If an import or assignment fails, check the Okta System Log and see Provisioning errors.

Verify sign-in

From Okta: open an assigned user’s Okta dashboard and click the Uploadcare tile. The Uploadcare dashboard opens with the user signed in.
From Uploadcare: go to app.uploadcare.com, click Continue with SSO, and sign in with the user’s email address.

The first time someone signs in, Uploadcare asks them to accept the Terms of Service and Privacy Policy. This happens once per user, including users created by provisioning.

Share these steps with your users. To sign in from Uploadcare:

Go to app.uploadcare.com and click Continue with SSO.
Enter your work email address and click Log in. If you entered it on the previous screen, it’s already filled in.
Uploadcare sends you to Okta. Sign in there if you aren’t already, and you return to the Uploadcare dashboard.

To sign in from Okta, click the Uploadcare tile on your Okta dashboard.

Password sign-in and email login links don’t work for addresses on your domain. Always use Continue with SSO.

What deactivation does

With SCIM provisioning, when you unassign a user from the Uploadcare app or deactivate them in Okta, Okta sends active: false over SCIM. Uploadcare then deactivates the account:

The user can’t sign in, and their open sessions end immediately.
They’re removed from projects that other accounts shared with them, and invitations addressed to them are revoked.
Projects the user owns are blocked, and file delivery stops for them.

Warning: Deactivating a user stops file delivery for every project they own, including projects other people work on. Don’t deactivate the account that owns your projects and pays for your Uploadcare plan. If you need to, contact help@uploadcare.com first.

Nothing is deleted: reassigning or reactivating the user in Okta restores the same account and unblocks the projects they own. Access to shared projects isn’t restored: the owners of those projects have to invite the user again.

Troubleshoot

Provisioning errors

Okta records the message Uploadcare returns in the System Log.

Status and message	What it means
`401` Invalid bearer token	The SCIM token is wrong or has been replaced. Ask support for a new one. Right after setup, the integration may not be turned on yet.
`400 invalidValue` userName is outside the tenant scope	The user’s email address isn’t on the domain registered with Uploadcare. Only users on that domain can be provisioned.
`400 invalidValue` Please use only Latin letters and safe punctuation	The first or last name contains characters Uploadcare doesn’t accept. See Restrictions.
`400 invalidValue` Please make sure this value is no longer than 83 characters	The first and last name together are too long. See Restrictions.
`400 mutability` userName cannot be changed	The user’s email address changed in Okta. Contact support.
`409 uniqueness` A user with this email already exists	The address belongs to an Uploadcare account that isn’t linked to your organization. Contact support to have it linked.
`400 invalidSyntax` Request payload is not a valid SCIM resource	An attribute from an extension schema is mapped, or a value is malformed. See Attribute mappings.
`429`	Okta exceeded the rate limit. The `Retry-After` header gives the wait time in seconds.

“This email is managed by single sign-on. Use your organization’s SSO login.” The user tried to sign in with a password, Google, or GitHub, or to sign up. Use Continue with SSO instead.
“Selected social account can’t be used with Uploadcare.” The identity Okta returned doesn’t match the domain registered for your organization. Check that Application username format is Email and that the user’s Okta profile has their work email address.
The user reaches Okta but doesn’t return signed in. Check that they’re assigned to the Uploadcare app in Okta.

Still stuck

Contact help@uploadcare.com with your email domain, the affected user’s email address, and the message Okta reported.