# SCIM

### Overview

Enterprise plan subscribers with SAML SSO enabled can opt to enable SCIM for their workspace. SCIM, or *System for Cross-domain Identity Management*, is an open standard that allows for the automation of user provisioning. If you have SAML SSO enabled with a supported identity provider, you can contact us to get SCIM enabled for your workspace.

### Configure

To configure SCIM, you'll need to add a Token and URL to your SCIM provider.

The SCIM token is the [API access token](https://github.com/secoda/gitbook/blob/master/saml/broken-reference/README.md). As an Admin, you can generate one by navigating to Settings > API.

{% hint style="info" %}
Your SCIM URL may be under a custom domain at https\://\<CUSTOM>/api/v2/scim/
{% endhint %}

Follow the directions below for your identity provider to setup the SCIM integration.

{% tabs %}
{% tab title="Okta" %}

* In the Okta admin pages, open the Secoda application you have for SAML 2.0
* In the *General* tab, click *Edit* and choose *SCIM* in the Provisioning section and *Save*
* In the *Provisioning* tab, enter the `https://app.secoda.co/api/v2/scim/`
* For the *Unique identifier* field for users section enter **email**
* For *Authentication mode* field, choose HTTP Header and enter your Bearer token generated from your API settings in Secoda
* For *Supported provisioning actions* only enable "Push New Users", "Push Profile Updates", "Push Groups"

<figure><img src="https://secoda-public-media-assets.s3.amazonaws.com/db613534-681d-4ce6-8ba7-23827b561cec.png" alt=""><figcaption></figcaption></figure>

* Then you may check the following *Provisioning to App*\\

  <figure><img src="https://secoda-public-media-assets.s3.amazonaws.com/65e43c69-96e7-49de-99d6-07c1905b95b9.png" alt=""><figcaption></figcaption></figure>

{% endtab %}

{% tab title="OneLogin" %}

* In OneLogin's Admin panel > Applications, click *Add App*
* Search for the "SCIM Provisioner with SAML (SCIM v2 Enterprise, full SAML)" app and add
* Click on the *Configuration* tab and add your SCIM base URL as `https://app.secoda.co/api/v2/scim/` and the Bearer token generated from your API settings in Secoda.
* Click on the *Provisioning* tab and Enable Provisioning
* Save your App
  {% endtab %}

{% tab title="Azure AD" %}

1. In Azure portal, go to Azure Active Directory -> Enterprise Applications.
2. Select an existing application or create a new one by searching for the specific application in the gallery.
3. In the application management screen, choose Provisioning in the left panel.
4. Under Provisioning Mode, select Automatic.
5. In Admin Credentials, enter the Tenant URL (e.g., `https://app.secoda.co/api/v2/scim/`) and a Secret Token generated from your API settings in Secoda.
6. Expand Mappings and configure user attributes. Set mappings like `userPrincipalName` to `userName`, `mail` to `emails[type eq "work"].value`, etc.
7. Ensure Create, Update, and Delete actions are selected under Target Object actions.
8. Save the configuration
   {% endtab %}
   {% endtabs %}

### Okta Push Users and Groups

When users are assigned to your Okta application they will receive an invitation email to join Secoda. These users will be populated in Secoda in an "Invited" state. You must filter by "Invited" to see these users.

<figure><img src="https://secoda-public-media-assets.s3.amazonaws.com/cbbf7159-46b8-4c84-9223-602458c6ce6c.png" alt=""><figcaption></figcaption></figure>

When Groups are pushed, they will appear under the "Groups" tab on "Members and permissions". "Invited" users will not appear as a group member until the user activates their account by signing in for the first time.

<figure><img src="https://secoda-public-media-assets.s3.amazonaws.com/4fa784ab-2c21-4e75-ae14-efeb6e4b1c8d.png" alt=""><figcaption></figcaption></figure>

<figure><img src="https://secoda-public-media-assets.s3.amazonaws.com/76ef453b-4174-4f78-8c72-d7e03303d0ae.png" alt=""><figcaption></figcaption></figure>

### Advanced

#### Troubleshooting

`Automatic provisioning of user <USER'S NAME> to app Secoda failed: Error while trying to push profile update for <EMAIL>: User not found`

To resolve, unassign the user from the Okta application. Then reassign. This will ensure your Okta application has the correct user ID.

#### Provisioning Roles

To automatically provision roles via SCIM, create a custom attribute with external `secodaRole` under the `urn:ietf:params:scim:schemas:core:2.0:User` external namespace. You should then be able to assign roles (including custom roles) to users in Secoda via SCIM.

#### SCIM Groups endpoint

Secoda's SCIM integration also supports group syncing. From your side all you have to do is start pushing groups from your Identity provider to Secoda. These will then map one to one with [groups](https://docs.secoda.co/user-management/groups "mention") in Secoda.

When syncing groups, the following attributes are supported:

* `displayName`: The name of the group in Secoda
* `members`: Array of user references that belong to the group

```json
PUT /api/v2/scim/Groups/{group_id}
Content-Type: application/json
Authorization: Bearer {your_access_token}

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
  "displayName": "{group_name}",
  "members": [
    {
      "value": "{user_id_1}",
      "display": "{user_1_display_name}"
    }
    // Add other members here if needed, for example:
    // ,
    // {
    //   "value": "{user_id_2}",
    //   "display": "{user_2_display_name}"
    // }
  ]
}

```

#### SCIM Users endpoint

To add an active or disabled user using SCIM you can make a PUT request. Here is an example of how to use SCIM to add a user.

```json
PUT /api/v2/scim/Users/{user_id}
Content-Type: application/json
Authorization: Bearer {access_token}

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "userName": "{user_email}",
  "name": {
    "givenName": "{user_first_name}",
    "familyName": "{user_last_name}"
  },
  "emails": [
    {
      "value": "{user_email}",
      "primary": true,
      "type": "work"
    }
  ],
  "active": true,
  "externalId": "{scim_external_id}"
}
```

Setting `"active": false` will disable the user, while setting it to `"active": true` would activate the user.