When building a System for Cross-domain Identity Management (SCIM) 2.0 integration with Okta, user or group updates fail to reflect on the downstream application. This occurs because Okta applies different HTTP methods for update operations depending on whether the integration originates from the App Integration Wizard (AIW) or the Okta Integration Network (OIN). Implement the correct HTTP methods for the specific integration type to ensure successful SCIM updates.

• Okta Identity Engine (OIE)
• Okta Classic Engine
• System for Cross-domain Identity Management (SCIM) 2.0
• Okta Integration Network (OIN)
• App Integration Wizard (AIW)

Okta applies different HTTP methods for update operations depending on the integration type. For AIW integrations, Okta sends all user and group object updates exclusively via PUT. For OIN integrations, Okta sends general attribute updates via PUT, while activation, deactivation, and group updates transmit via PATCH.

If a SCIM server only handles one method and the integration type sends the other, the operation fails silently or returns an unexpected error.

How are integration types determined?

Determine the integration type by identifying where the integration originates.

• If the integration originates from the OIN Wizard or publishes to the OIN catalog, it is an OIN integration.
• If the integration originates from the AIW inside an Okta org, it is an AIW integration.

Implement the Correct HTTP Methods for AIW Integrations

Configure the SCIM server to handle PUT requests for all user and group update operations. Okta sends a full user or group object replacement for every update.

• For users, the SCIM server must handle PUT /Users/{userID} for attribute updates, activation ("active": true), and deactivation ("active": false).
• For groups, the SCIM server must handle PUT /Groups/{groupID} for group name changes and all membership modifications.

Review the following example PUT request that Okta sends for a user update.

PUT /scim/v2/Users/23a35c27-23d3-4c03-b4c5-6443c09e7173 HTTP/1.1
Authorization: <Authorization credentials>

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "id": "23a35c27-23d3-4c03-b4c5-6443c09e7173",
  "userName": "test.user@okta.local",
  "name": {
    "givenName": "Test",
    "familyName": "User"
  },
  "emails": [
    {
      "primary": true,
      "value": "test.user@okta.local",
      "type": "work"
    }
  ],
  "active": false,
  "groups": []
}

The SCIM server must respond with HTTP 200 and the full updated user object.

Review the following example PUT request that Okta sends for a group update.

PUT /scim/v2/Groups/abf4dd94-a4c0-4f67-89c9-76b03d227c06 HTTP/1.1
Authorization: <Authorization credentials>

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
  "id": "abf4dd94-a4c0-4f67-89c9-76b03d227c06",
  "displayName": "Engineering",
  "members": [
    {
      "value": "23a35c27-23d3-4c03-b4c5-6443c09e7173",
      "display": "test.user@okta.local"
    }
  ]
}

The SCIM server must respond with HTTP 200 and the full updated group object.

Implement the Correct HTTP Methods for OIN Integrations

Configure the SCIM server to handle PUT requests for attribute updates and PATCH requests for lifecycle and group operations.

• For users, attribute updates transmit via PUT. Activation and deactivation transmit via PATCH.
• For groups, both group name updates and membership changes (add, remove, replace) transmit via PATCH.

Review the following example PATCH deactivation request that Okta sends for a user.

PATCH /scim/v2/Users/23a35c27-23d3-4c03-b4c5-6443c09e7173 HTTP/1.1
Authorization: <Authorization credentials>

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "replace",
      "value": {
        "active": false
      }
    }
  ]
}

The SCIM server must respond with either HTTP 200 with the full updated user object, or HTTP 204 with no response body.

Review the following example PATCH membership add request that Okta sends for a group.

PATCH /scim/v2/Groups/abf4dd94-a4c0-4f67-89c9-76b03d227c06 HTTP/1.1
Authorization: <Authorization credentials>

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "add",
      "path": "members",
      "value": [
        {
          "value": "23a35c27-23d3-4c03-b4c5-6443c09e7173",
          "display": "test.user@okta.local"
        }
      ]
    }
  ]
}

The SCIM server must respond with either HTTP 200 with the full updated group object or HTTP 204 with no response body.

Review Additional SCIM Provisioning Behaviors

Review the following additional behaviors regarding SCIM provisioning in Okta.

• Okta never sends DELETE on user objects. User removal always occurs by setting "active": false.
• Suspended users within Okta do not generate a deprovisioning event to the SCIM server.
• To enable deactivation via provisioning, confirm that the administrator enables Deactivate Users under the Provisioning > To App settings of the integration.

Related References

• Update the user | SCIM v2.0 | Okta Developer
• SCIM Protocol | Okta Developer
• RFC 7644 System for Cross-domain Identity Management: Protocol