Provisioning SCIM Messages Sent by Okta to a SCIM Server Skip to main content
https://support.okta.com/help/oktaarticledetailpage?childcateg=&id=ka0f0000000ay3wkaw&source=documentation&refurl=http%3a%2f%2fsupport.okta.com%2fhelp%2fdocumentation%2fknowledge_article%2f80110523-provisioning-scim-messages-sent-by-okta-to-a-scim-server
How satisfied are you with the Okta Help Center?
Thank you for your feedback!
How satisfied are you with the Okta Help Center?
1
2
3
4
5
Very Dissatisfied
Very satisfied
Enter content less than 200 characters.
Average Rating:
Provisioning SCIM Messages Sent by Okta to a SCIM Server
Published: Jan 10, 2015   -   Updated: Feb 9, 2017

Okta uses a subset of available SCIM messages to send provisioning instructions to a SCIM server. The following sections describe the SCIM messages Okta uses along with example requests and responses.

Get Implemented User Management Capabilities

This instruction is sent during app instance configuration and asks your connector to return the list of provisioning capabilities your connector has implemented. Based on the result, appropriate provisioning features are supported by the app instance.

Example HTTP Request and JSON Message Sent by Your Provisioning Agent

GET /ServiceProviderConfigs
ExampleGET http://acme.com:8080/ServiceProviderConfigs

Expected Response from Connector Acting as SCIM Server

{
   "schemas":[
      "urn:scim:schemas:core:1.0",
      "urn:okta:schemas:scim:providerconfig:1.0"
   ],
   "documentationUrl":"https://support.okta.com/scim-fake-page.html",
   "patch":{
      "supported":false
   },
   "bulk":{
      "supported":false
   },
   "filter":{
      "supported":true,
      "maxResults":100
   },
   "changePassword":{
      "supported":true
   },
   "sort":{
      "supported":false
   },
   "etag":{
      "supported":false
   },
   "authenticationSchemes":[

   ],
   "urn:okta:schemas:scim:providerconfig:1.0":{
      "userManagementCapabilities":[
         "GROUP_PUSH",
         "IMPORT_NEW_USERS",
         "IMPORT_PROFILE_UPDATES",
         "PUSH_NEW_USERS",
         "PUSH_PASSWORD_UPDATES",
         "PUSH_PENDING_USERS",
         "PUSH_PROFILE_UPDATES",
         "PUSH_USER_DEACTIVATION",
         "REACTIVATE_USERS"
      ]
   }
}

Create New User

This instruction is sent when you assign a new user to an on-prem app. Okta sends two messages. The first one determines whether or not the user already exists in the app. If the user does not exist in the app, Okta sends another message to create the user. 

Example HTTP Request and JSON Message Sent by Your Provisioning Agent

GET /Users?filter=userName=myemail@domain.com&startIndex=1&count=100

Expected Response from Connector Acting as SCIM Server

The following example shows a return when the user does not exist:

schemas: "urn:scim:schemas:core:1.0", "urn:scim:schemas:extension:enterprise:1.0", "urn:okta:onprem_app:1.0:user" id: "102" userName: "admin" name: formatted: "Barbara Jensen"       givenName: "Barbara"       familyName: "Jensen"       middleName: "Brian"
   emails:       value: "bjensen@example.com"       primary: true       type: "work"
   active: false   password: "god"   groups:       value: "1002"       display: "secondGroup"
   urn:okta:onprem_app:1.0:user:custom:       isAdmin: true       isOkta: false       departmentName: "Administration"

The following example shows a return when the user does exist:

{
"totalResults":1,
"schemas":["urn:scim:schemas:core:1.0"],
"Resources":[
{
"schemas": [
"urn:scim:schemas:core:1.0",
"urn:scim:schemas:extension:enterprise:1.0",
"urn:okta:onprem_app:1.0:user:custom"
],
"id": "102",
"userName": "admin",
"password": "god",
"active": false,
"name": {
"formatted": "Barbara Jensen",
"givenName": "Barbara",
"familyName": "Jensen"
},
"emails": [
{
"value": "bjensen@example.com",
"primary": true,
"type": "work"
}
],
"groups": [
{
"value": "1002",
"display": "secondGroup"
}
],
"urn:okta:onprem_app:1.0:user:custom": {
"isAdmin": true,
"isOkta": false,
"departmentName": "Administration"
}
}
]
}

Example HTTP Request and JSON Message Sent by Your Provisioning Agent

POST /Users

Example: http://acme.com:8080/Users
{
   "schemas":[
      "urn:scim:schemas:core:1.0",
      "urn:okta:onprem_app:1.0:user:custom"
   ],
   "userName":"myemail@domain.com",
   "emails":[
      {
         "primary":true,
         "value":"myemail@domain.com",
         "type":"primary"
      },
      {
         "primary":false,
         "value":"mypersonalemail@domain.com",
         "type":"secondary"
      }
   ],
   "phoneNumbers":[
      {
         "value":"123-444-5555",
         "type":"mobile"
      }
   ],
   "name":{
      "familyName":"LastName",
      "givenName":"FirstName"
   },
   "active":true,
   "password":"verySecure",
   "urn:okta:onprem_app:1.0:user:custom":{
      "isAdmin":false,
      "isOkta":false,
      "departmentName":"Testing User"
   }
}

Expected Response from Connector Acting as SCIM Server

schemas: "urn:scim:schemas:core:1.0", "urn:scim:schemas:extension:enterprise:1.0"   phoneNumbers:       value: "123-444-5555"       type: "mobile"
   userName: "myemail@domain.com"   name:       familyName: "LastName"       givenName: "FirstName"
   active: true   emails:       primary: true       value: "myemail@domain.com"       type: "primary"
       primary: false       value: "mypersonalemail@domain.com"       type: "secondary"
   password: "verySecure"   id: "103"

Create Pending User

This instruction is sent when an Okta user who has not been activated yet in Okta is assigned to an app.

Example HTTP Request and JSON Message Sent by Your Provisioning Agent

POST /Users

{
   "schemas":[
      "urn:scim:schemas:core:1.0"
   ],
   "userName":"myemail-pending@domain.com",
   "emails":[
      {
         "primary":true,
         "value":"myemail-pending@domain.com",
         "type":"primary"
      },
      {
         "primary":false,
         "value":"mypersonalemail-pending@domain.com",
         "type":"secondary"
      }
   ],
   "phoneNumbers":[
      {
         "value":"123-444-5555",
         "type":"mobile"
      }
   ],
   "name":{
      "familyName":"LastName-pending",
      "givenName":"FirstName-pending"
   },
   "active":false,
   "password":"verySecure",
   "groups":[
      {
         "display":"secondGroup",
         "value":"1002"
      }
   ]
}

Expected Response from Connector Acting as SCIM Server

schemas: "urn:scim:schemas:core:1.0", "urn:scim:schemas:extension:enterprise:1.0"   phoneNumbers:       value: "123-444-5555"       type: "mobile"
   userName: "myemail@domain.com"   name:       familyName: "LastName"       givenName: "FirstName"
   active: false   emails:       primary: true       value: "myemail@domain.com"       type: "primary"
       primary: false       value: "mypersonalemail@domain.com"       type: "secondary"
   password: "verySecure"   id: "103"

Note: This call is almost identical to the create user call except for the inclusion of the active value.

Import Users from on-prem application into Okta

This instruction is sent when an admin imports users from an app into Okta.

Note: Your provisioning agent might make multiple requests to your connector if multiple pages of users exist.

Example HTTP Request and JSON Message Sent by Your Provisioning Agent

GET /Users?startIndex=1&count=100

Expected Response from Connector Acting as SCIM Server

schemas: "urn:scim:schemas:core:1.0", "urn:scim:schemas:extension:enterprise:1.0", "urn:okta:onprem_app:1.0:user:custom"   id: "102"   userName: "admin"   password: "god"   active: false   name:       formatted: "Barbara Jensen"       givenName: "Barbara"       familyName: "Jensen"
   emails:       value: "bjensen@example.com"       primary: true       type: "work"
   groups:       value: "1002"       display: "secondGroup"
   urn:okta:onprem_app:1.0:user:custom:       isAdmin: true       isOkta: false       departmentName: "Administration"
schemas: "urn:scim:schemas:core:1.0", "urn:scim:schemas:extension:enterprise:1.0", "urn:okta:onprem_app:1.0:user:custom"   id: "101"   userName: "okta"   password: "inSecure"   active: true   name:       formatted: "John Smith"       givenName: "John"       familyName: "Smith"
   emails:       value: "jsmith@example.com"       primary: true       type: "work"
   groups:       value: "1001"       display: "firstGroup"
       value: "1002"       display: "secondGroup"
   urn:okta:onprem_app:1.0:user:custom:       isAdmin: false       isOkta: true       departmentName: "Cloud Service"

Note: The value, onprem_app, represents the name of the on-prem app that you created in Okta.

Import User Profile

Example HTTP Request and JSON Message Sent by Your Provisioning Agent

GET /Users/<Id>

Expected Response from Connector Acting as SCIM Server

schemas: "urn:scim:schemas:core:1.0", "urn:scim:schemas:extension:enterprise:1.0", "urn:okta:onprem_app:1.0:user"   id: "101"   userName: "okta"   name:       formatted: "John Smith"       givenName: "John"       familyName: "Smith"       middleName: "William"
   emails:       value: "jsmith@example.com"       primary: true       type: "work"
   active: true   password: "inSecure"   groups:       value: "1001"       display: "firstGroup"
       value: "1002"       display: "secondGroup"
   urn:okta:onprem_app:1.0:user:custom:       isAdmin: false       isOkta: true       departmentName: "Cloud Service"

When Okta attempts to provision a user and finds that the user already exists in the on-prem app, Okta either pushes the profile of the user to the app or imports the user profile. This depends on whether or not you have the Push Profile Update option enabled. If it is enabled, Okta pushes the profile of the user to the app. If it is not enabled, it imports the user profile.

Activate User

This instruction is sent when a user who was previously provisioned in inactive state is activated in Okta.

Example HTTP Request and JSON Message Sent by Your Provisioning Agent

PUT /Users/<id

{
   "schemas":[
      "urn:scim:schemas:core:1.0",
      "urn:scim:schemas:extension:enterprise:1.0",
      "urn:okta:onprem_app:1.0:user:custom"
   ],
   "id":"101",
   "userName":"okta",
   "name":{
      "givenName":"John",
      "familyName":"Smith"
   },
   "emails":[
      {
         "value":"jsmith@example.com",
         "primary":true,
         "type":"work"
      }
   ],
   "active":true,
   "password":"inSecure",
   "groups":[
      {
         "value":"1001",
         "display":"firstGroup"
      },
      {
         "value":"1002",
         "display":"secondGroup"
      }
   ],
   "urn:okta:onprem_app:1.0:user:custom":{
      "isAdmin":false,
      "isOkta":true,
      "departmentName":"Cloud Service"
   }
}

Expected Response from Connector Acting as SCIM Server

schemas: "urn:scim:schemas:core:1.0", "urn:scim:schemas:extension:enterprise:1.0", "urn:okta:onprem_app:1.0:user"   id: "101"   userName: "okta"   name:       formatted: "John Smith"       givenName: "John"       familyName: "Smith"       middleName: "William"
   emails:       value: "jsmith@example.com"       primary: true       type: "work"
   active: true   password: "inSecure"   groups:       value: "1001"       display: "firstGroup"
       value: "1002"       display: "secondGroup"
   urn:okta:onprem_app:1.0:user:custom:       isAdmin: false       isOkta: true       departmentName: "Cloud Service"

Deactivate User

This instruction is sent when a user is unassigned from an app instance or a user is deactivated in Okta.

Example HTTP Request and JSON Message Sent by Your Provisioning Agent

PUT /Users/<id>

{
   "schemas":[
      "urn:scim:schemas:core:1.0",
      "urn:scim:schemas:extension:enterprise:1.0",
      "urn:okta:onprem_app:1.0:user:custom"
   ],
   "id":"101",
   "userName":"okta",
   "name":{
      "givenName":"John",
      "familyName":"Smith"
   },
   "emails":[
      {
         "value":"jsmith@example.com",
         "primary":true,
         "type":"work"
      }
   ],
   "active":false,
   "password":"inSecure",
   "groups":[
      {
         "value":"1001",
         "display":"firstGroup"
      },
      {
         "value":"1002",
         "display":"secondGroup"
      }
   ],
   "urn:okta:onprem_app:1.0:user:custom":{
      "isAdmin":false,
      "isOkta":true,
      "departmentName":"Cloud Service"
   }
}

Expected Response from Connector Acting as SCIM Server

schemas: "urn:scim:schemas:core:1.0", "urn:scim:schemas:extension:enterprise:1.0", "urn:okta:onprem_app:1.0:user"   id: "101"   userName: "okta"   name:       formatted: "John Smith"       givenName: "John"       familyName: "Smith"       middleName: "William"
   emails:       value: "jsmith@example.com"       primary: true       type: "work"
   active: false   password: "inSecure"   groups:       value: "1001"       display: "firstGroup"
       value: "1002"       display: "secondGroup"
   urn:okta:onprem_app:1.0:user:custom:       isAdmin: false       isOkta: true       departmentName: "Cloud Service"

Reactivate User

This instruction is sent when a previously deactivated user is activated in Okta  

Example HTTP Request and JSON Message Sent by Your Provisioning Agent

PUT /Users/<id>

Expected Response from Connector Acting as SCIM Server

schemas: "urn:scim:schemas:core:1.0", "urn:scim:schemas:extension:enterprise:1.0", "urn:okta:onprem_app:1.0:user"   id: "101"   userName: "okta"   name:       formatted: "John Smith"       givenName: "John"       familyName: "Smith"       middleName: "William"
   emails:       value: "jsmith@example.com"       primary: true       type: "work"
   active: true   password: "inSecure"   groups:       value: "1001"       display: "firstGroup"
       value: "1002"       display: "secondGroup"
   urn:okta:onprem_app:1.0:user:custom:       isAdmin: false       isOkta: true       departmentName: "Cloud Service"

Push Password Update

This instruction is sent when user changes password on Okta and Sync password user provisioning feature  has been enabled on App provisioning tab in Okta.

Example HTTP Request and JSON Message Sent by Your Provisioning Agent

PUT /Users/<id>

{
   "schemas":[
      "urn:scim:schemas:core:1.0",
      "urn:scim:schemas:extension:enterprise:1.0",
      "urn:okta:onprem_app:1.0:user:custom"
   ],
   "id":"101",
   "userName":"okta",
   "name":{
      "givenName":"John",
      "familyName":"Smith"
   },
   "emails":[
      {
         "value":"jsmith@example.com",
         "primary":true,
         "type":"work"
      }
   ],
   "active":true,
   "password":"this-is-my-new-password",
   "groups":[
      {
         "value":"1001",
         "display":"firstGroup"
      },
      {
         "value":"1002",
         "display":"secondGroup"
      }
   ],
   "urn:okta:onprem_app:1.0:user:custom":{
      "isAdmin":false,
      "isOkta":true,
      "departmentName":"Cloud Service"
   }
}

Expected Response from Connector Acting as SCIM Server

Okta assumes that a non-error response from your connector means the pushPasswordUpdate was successful.

Push Profile Update

This instruction is sent when a user's profile changes in Okta and the update user provisioning feature has been enabled on Okta.

Example HTTP Request and JSON Message Sent by Your Provisioning Agent

PUT request to /Users/101

{
   "schemas":[
      "urn:scim:schemas:core:1.0",
      "urn:scim:schemas:extension:enterprise:1.0",
      "urn:okta:onprem_app:1.0:user:custom"
   ],
   "id":"101",
   "userName":"okta",
   "name":{
      "givenName":"John",
      "familyName":"Taylor"
   },
   "emails":[
      {
         "value":"jtaylor@example.com",
         "primary":true,
         "type":"work"
      }
   ],
   "active":true,
   "password":"inSecure",
   "groups":[
      {
         "value":"1001",
         "display":"firstGroup"
      },
      {
         "value":"1002",
         "display":"secondGroup"
      }
   ],
   "urn:okta:onprem_app:1.0:user:custom":{
      "isAdmin":false,
      "isOkta":true,
      "departmentName":"Cloud Service Management"
   }
}

Expected Response from Connector Acting as SCIM Server

Okta assumes that a non-error response from your connector means the pushProfileUpdate was successful. Provided that the feature to store updates to app users upon creation or update is enabled, the connector sends back the updated user.

Download Groups

This instruction is sent when an admin imports users into Okta.

Example HTTP Request and JSON Message Sent by Your Provisioning Agent

GET request /Groups?startIndex=1&count=100

Expected Response from Connector Acting as SCIM Server

{
   "totalResults":2,
   "schemas":[
      "urn:scim:schemas:core:1.0"
   ],
   "Resources":[
      {
         "schemas":[
            "urn:scim:schemas:core:1.0",
            "urn:okta:custom:group:1.0"
         ],
         "displayName":"firstGroup",
         "id":"1001",
         "members":[
            {
               "value":"101",
               "display":"okta"
            }
         ],
         "urn:okta:custom:group:1.0":{
            "description":"This is the first group"
         }
      },
      {
         "schemas":[
            "urn:scim:schemas:core:1.0"
         ],
         "displayName":"secondGroup",
         "id":"1002",
         "members":[
            {
               "value":"101",
               "display":"okta"
            },
            {
               "value":"102",
               "display":"admin"
            }
         ]
      }
   ]
}

Create Group

This instruction is sent when the Group Push feature is enabled for an app on Okta.

Example HTTP Request and JSON Message Sent by Your Provisioning Agent

POST request to http://localhost:8080/Groups

Expected Response from Connector Acting as SCIM Server

{
   "schemas":[
      "urn:scim:schemas:core:1.0",
      "urn:okta:custom:group:1.0"
   ],
   "displayName":"AppGroup-04",
   "id":"AppGroup-02",
   "members":[
      {
         "value":"101",
         "display":"okta"
      },
      {
         "value":"102",
         "display":"admin"
      }
   ],
   "urn:okta:custom:group:1.0":{
      "description":"This is the second group"
   }
}

updateGroup

This instruction is sent when the Group Push feature is enabled for an app on Okta.

Example HTTP Request and JSON Message Sent by Your Provisioning Agent

PUT request to http://localhost:8080/Groups/1002

Expected Response from Connector Acting as SCIM Server

{
   "schemas":[
      "urn:scim:schemas:core:1.0",
      "urn:okta:custom:group:1.0"
   ],
   "displayName":"AppGroup-Changed",
   "id":"1002",
   "members":[
      {
         "value":"101",
         "display":"okta admin"
      },
      {
         "value":"102",
         "display":"okta user"
      }
   ],
   "urn:okta:custom:group:1.0":{
      "description":"This is the changed first group"
   }
}

deleteGroup

This instruction is sent when the Group Push feature is enabled for an app on Okta.

Example HTTP Request and JSON Message Sent by Your Provisioning Agent

DELETE request to http://localhost:8080/Groups/1003

Expected Response from Connector Acting as SCIM Server

Okta assumes that a non-error response from your connector means the deleteGroup was successful and the group with the Id 1003 was deleted.

Post a Comment