# SCIM

Configure SCIM (System for Cross-domain Identity Management) with your Identity Provider for automated user provisioning in Shortcut.

## Overview

SCIM enables automated user provisioning between your Identity Provider (IdP) and Shortcut. As of now, the only officially supported SCIM integration is via [Okta](https://www.okta.com/integrations/shortcut-scim/).

## Requirements

- **Enterprise or Business plan** - SCIM relies on SSO/SAML, which is included on Enterprise plans and available as an add-on on Business plans
- **Owner or Admin access** in Shortcut
- **SSO/SAML enabled** on your Shortcut Organization
- **Both Okta apps installed**: [Shortcut](https://www.okta.com/integrations/shortcut/) (SAML) and [Shortcut SCIM](https://www.okta.com/integrations/shortcut-scim/)
- **Invitation-only workspace** - Set under **Settings > Invite New User > Settings**
- **SCIM credentials** - Contact [support@shortcut.com](mailto:support@shortcut.com) to request your Workspace ID and API Token

> SCIM operates at the Workspace level while SAML operates at the Organization level. Organizations with multiple Workspaces should create separate SCIM applications for each Workspace.

## Supported SCIM Features

| Feature | Description |
|---------|-------------|
| **Push New Users** | Users assigned the Shortcut app in your IdP are created in Shortcut |
| **Push Profile Updates** | Profile changes in your IdP sync to Shortcut |
| **Push User Deactivation** | Disabling access in your IdP disables the user in Shortcut |

## Supported SCIM Attributes

| Attribute | Required | Description |
|-----------|----------|-------------|
| `userName` | Yes | User's email address |
| `email` | Yes | User's email address |
| `displayName` | Yes | User's name in Shortcut |
| `role` | Yes | Admin, Member, or Observer (Owner not supported) |

**Schema namespace:** `urn:ietf:params:scim:schemas:core:2.0:User`

## SCIM Configuration

Configure these settings in your IdP (field names may vary):

| Setting | Value |
|---------|-------|
| **SCIM Base URI** | `https://api.app.shortcut.com/integrations/scim/YOUR_WORKSPACE_ID` |
| **Authorization** | Header auth with Bearer token |
| **Unique Identifier** | `email` |

Contact [support@shortcut.com](mailto:support@shortcut.com) to obtain your Workspace ID and Bearer token.

## Configuring Okta with SCIM

This guide covers how to configure Okta for SCIM provisioning in Shortcut, enabling automated user creation, updates, and deactivation.

### 1. Add Shortcut SCIM App

1. From your Okta Admin console, click **Applications**
2. Select **Browse App Catalog** and search for **Shortcut SCIM**
3. Click **Shortcut SCIM** and then **Add Integration**
4. On the **General Settings** tab, check both:
   - *Do not display application icon to users*
   - *Do not display application icon in the Okta Mobile App*

> The Shortcut SCIM app is only for provisioning users. Login should be done via the Shortcut SAML app.

### 2. Configure SCIM Provisioning

1. Navigate to **Provisioning** settings for Shortcut SCIM
2. Click **Configure API Integration**
3. Check **Enable API Integration**
4. Enter the **Workspace ID** from support
5. Enter the **API Token** from support
6. Click **Test API Credentials**
7. If successful, click **Save**

### 3. Enable Provisioning Features

1. In **Provisioning** settings, go to the **To App** section
2. Click **Edit**
3. Select the features you want to enable
4. Click **Save**

### 4. Configure SAML Application

Ensure your **Shortcut** SAML app has correct settings:

1. Go to the **Sign On** settings tab
2. Set **Application username format** to **Email**
3. Click **Save**

## Advanced: Custom Username Field

By default, the `userName` field is locked to the Okta user's email. To customize:

1. Contact Okta support at [support.okta.com](https://support.okta.com/help/s/?language=en_US)
2. Request to disable the Feature Flag **CONSOLIDATE_USERNAME_EL**
3. Once disabled, you can map a custom attribute for `userName`