> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://uploadcare.com/docs/llms.txt.

# Okta SSO and SCIM provisioning

> Sign in to the Uploadcare dashboard with Okta, require Okta for your email domain, and create, update, and deactivate Uploadcare accounts from Okta with SCIM 2.0.

Use Okta as the identity provider for the [Uploadcare dashboard](https://app.uploadcare.com/). 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](https://www.okta.com/integrations/uploadcare/).

Each user has their own Uploadcare account rather than a seat in a shared workspace. Users work together by [sharing projects](/docs/start/settings/#project-teams).

## Supported features \[#supported-features]

### Single sign-on (OIDC) \[#sso]

* **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**
>
> **Note:** Single Logout (SLO) isn't supported: signing out of Okta doesn't end an open Uploadcare dashboard session.

### SCIM 2.0 provisioning \[#scim]

* **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](#deactivation).

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](https://help.okta.com/okta_help.htm?type=oie\&id=ext_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 \[#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**
>
> **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 \[#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](https://en.wikipedia.org/wiki/Basic_Latin_%28Unicode_block%29), [Latin-1 Supplement](https://en.wikipedia.org/wiki/Latin-1_Supplement), and [Latin Extended-A](https://en.wikipedia.org/wiki/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](mailto:help@uploadcare.com) before you start.

## Prerequisites \[#prerequisites]

* **An Uploadcare account on the [Enterprise plan](https://uploadcare.com/pricing/).**
* **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 \[#setup]

### Before you start \[#before-you-start]

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

> **Warning**
>
> **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 \[#step-1]

1. In the Okta Admin Console, go to **Applications → Applications** and click **Browse App Catalog**.
2. Search for **Uploadcare**, open it, and click **Add Integration**.
3. On the **Sign On** tab, set **Application username format** to **Email**. Uploadcare identifies users by email address.
4. 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 \[#step-2]

Write to [help@uploadcare.com](mailto: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 \[#step-3]

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](#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 \[#step-4]

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

1. In the Uploadcare app in Okta, open the **Provisioning** tab and go to **Integration → Configure API Integration**.
2. Select **Enable API integration** and enter the **OAuth Bearer Token** from step 3.
3. Clear **Import Groups**. Uploadcare doesn't support SCIM groups.
4. Click **Test API Credentials**, then **Save**. The test fails until Uploadcare has turned the integration on. If it still fails, see [Provisioning errors](#provisioning-errors).
5. 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.
6. Check that the mappings match [Attribute mappings](#attribute-mappings).

### Step 5: Assign users and verify sign-in \[#step-5]

#### Import existing accounts \[#step-5-import]

Do this first if you use SCIM and some users on your domain already have Uploadcare accounts. Otherwise, skip to [Assign users](#step-5-assign).

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

#### Assign users \[#step-5-assign]

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](#provisioning-errors).

#### Verify sign-in \[#verify]

1. **From Okta**: open an assigned user's Okta dashboard and click the Uploadcare tile. The Uploadcare dashboard opens with the user signed in.
2. **From Uploadcare**: go to [app.uploadcare.com](https://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](https://uploadcare.com/about/terms/) and [Privacy Policy](https://uploadcare.com/about/privacy-policy/). This happens once per user, including users created by provisioning.

## Sign in with Okta \[#sign-in]

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

1. Go to [app.uploadcare.com](https://app.uploadcare.com/) and click **Continue with SSO**.
2. Enter your work email address and click **Log in**. If you entered it on the previous screen, it's already filled in.
3. 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 \[#deactivation]

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**
>
> **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](mailto: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 \[#troubleshoot]

### Provisioning errors \[#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](#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](#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](#attribute-mappings).              |
| `429`                                                                          | Okta exceeded the rate limit. The `Retry-After` header gives the wait time in seconds.                                                |

### Sign-in problems \[#sign-in-problems]

* **"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 \[#support]

Contact [help@uploadcare.com](mailto:help@uploadcare.com) with your email domain, the affected user's email address, and the message Okta reported.