SCIM messages for on-premises provisioning

Okta uses a subset of available SCIMSystem for Cross-domain Identity Management (SCIM) is an open standard that allows for the automation of user provisioning. It was created in 2011 as it became clear that the technology of the future would be cloud-based. SCIM communicates user identity data between identity providers (such as companies with multiple individual users) and service providers requiring user identity information (such as enterprise SaaS apps). In short, SCIM makes user data more secure and simplifies the user experience by automating the user identity lifecycle management process. messages to send provisioning instructions to a SCIM server. These are the Okta SCIM provisioning messages:

Get implemented user management capabilities

This instruction is sent during appAn abbreviation of application. Essentially, it is a web-based site used to perform any number of specific tasks, and requires authentication from end users by signing in. 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.

Provisioning agent HTTP request and JSON message example

GET /ServiceProviderConfigs

Example

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

Expected response from acting SCIM server connector

{

  "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 a 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.

Provisioning agent HTTP request and JSON message example

GET /Users?filter=userName%20eq%20%22myemail%40domain.com%22&startIndex=1&count=100

Expected response from acting SCIM server connector

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

{

"schemas": [

"urn:scim:schemas:core:1.0"

],

"totalResults": 0,

"startIndex": 1,

"itemsPerPage": 0,

"Resources": []

}

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": "adminAn abbreviation of administrator. This is the individual(s) who have access to the Okta Administrator Dashboard. They control the provisioning and deprovisioning of end users, the assigning of apps, the resetting of passwords, and the overall end user experience. Only administrators have the Administration button on the upper right side of the My Applications page.",

    "password": "god",

    "active": false,

    "name": {

      "formatted": "Barbara Jensen",

      "givenName": "Barbara",

      "familyName": "Jensen"

    },

    "emails": [

      {

        "value": "bjensen@example.com",

        "primary": true,

        "type": "work"

      }

    ],

    "groupsGroups allow you to organize your end users and the apps they can access. Assigning apps to large sets of end users is made easier with groups.": [

      {

        "value": "1002",

        "display": "secondGroup"

      }

    ],

    "urn:okta:onprem_app:1.0:user:custom": {

      "isAdmin": true,

      "isOkta": false,

      "departmentName": "Administration"

    }

    }

  ]

}

Provisioning agent HTTP request and JSON message example

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@domainA domain is an attribute of an Okta organization. Okta uses a fully-qualified domain name, meaning it always includes the top-level domain (.com, .eu, etc.), but does not include the protocol (https)..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 acting SCIM server connector

{

"id": "d0dd58e43ded4293a61a8760fcba0458",

"externalId": "00ustvXq1A8UAuobW0f5",

"meta": {

"created": "04-17-2020 00:00:00",

"lastModified": "04-17-2020 00:00:00",

"version": "v1.0"

},

"schemas": [

"urn:scim:schemas:core:1.0",

"urn:scim:schemas:extension:okta:1.0"

],

"userName": "steph@warriors.com",

"displayName": " Steph Curry",

"preferredLanguage": "en",

"locale": "en-US",

"timezone": "America/Los_Angeles",

"active": true,

"password": "VFhsSlpHVnVkR2wwZVVselRYbFFZWE56ZDI5eVpBPT0=",

"emails": [

{

"value": "steph@warriors.com",

"type": "work",

"primary": true

}

],

"groups": [],

"name": {

"familyName": "Curry",

Create a pending user

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

Provisioning agent HTTP request and JSON message example

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 acting SCIM server connector

{

"id": "d0dd58e43ded4293a61a8760fcba0458",

"externalId": "00ustvXq1A8UAuobW0f5",

"meta": {

"created": "04-17-2020 00:00:00",

"lastModified": "04-17-2020 00:00:00",

"version": "v1.0"

},

"schemas": [

"urn:scim:schemas:core:1.0",

"urn:scim:schemas:extension:okta:1.0"

],

"userName": "steph@warriors.com",

"displayName": " Steph Curry",

"preferredLanguage": "en",

"locale": "en-US",

"timezone": "America/Los_Angeles",

"active": true,

"password": "VFhsSlpHVnVkR2wwZVVselRYbFFZWE56ZDI5eVpBPT0=",

"emails": [

{

"value": "steph@warriors.com",

"type": "work",

"primary": true

}

],

"groups": [],

"name": {

"familyName": "Curry",

"givenName": "Steph"

},

"urn:scim:schemas:extension:okta:1.0": {

"employeeNumber": "30",

"manager": {

"value": "Steve Kerr"

}

}

}

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

Import users from an on-premises application into Okta

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

Note: Your provisioning agentA software agent is a lightweight program that runs as a service outside of Okta. It is typically installed behind a firewall and allows Okta to tunnel communication between an on-premises service and Okta's cloud service. Okta employs several agent types: Active Directory, LDAP, RADIUS, RSA, Active Directory Password Sync, and IWA. For example, users can install multiple Active Directory agents to ensure that the integration is robust and highly available across geographic locations. might make multiple requests to your connector if multiple pages of users exist.

Provisioning agent HTTP request and JSON message example

GET /Users?startIndex=1&count=100

Expected response from acting SCIM server connector

{

"schemas": [

"urn:scim:schemas:core:1.0"

],

"totalResults": 3,

"startIndex": 1,

"itemsPerPage": 3,

"Resources": [

{

"id": "ce454761d63f4ce4904db3d4b9cc4cc4",

"externalId": "00uinactiveAuobW0f8",

"meta": {

"created": "04-09-2020 00:00:00",

"lastModified": "10-14-2016 00:00:00",

"version": "v1.0"

},

"schemas": [

"urn:scim:schemas:core:1.0"

],

"userName": "InactiveScim1User1@scimone.com",

"displayName": "Inactive Scim1 Test User",

"preferredLanguage": "en",

"locale": "en_US",

"timezone": "America/Los_Angeles",

"active": false,

"password": "UVdKalpERXlNelE9",

"emails": [

{

"value": "InactiveScim1User1@scimone.com",

"type": "work",

"primary": true

}

],

"groups": [],

"name": {

"familyName": "User",

"givenName": "Inactive Scim1 Test"

}

},

{

"id": "d0dd58e43ded4293a61a8760fcba0458",

"externalId": "00ustvXq1A8UAuobW0f5",

"meta": {

"created": "04-17-2020 00:00:00",

"lastModified": "04-17-2020 00:00:00",

"version": "v1.0"

},

"schemas": [

"urn:scim:schemas:core:1.0",

"urn:scim:schemas:extension:okta:1.0"

],

"userName": "steph@warriors.com",

"displayName": " Steph Curry",

"preferredLanguage": "en",

"locale": "en-US",

"timezone": "America/Los_Angeles",

"active": true,

"password": "VFhsSlpHVnVkR2wwZVVselRYbFFZWE56ZDI5eVpBPT0=",

"emails": [

{

"value": "steph@warriors.com",

"type": "work",

"primary": true

}

],

"groups": [],

"name": {

"familyName": "Curry",

"givenName": "Steph"

},

"urn:scim:schemas:extension:okta:1.0": {

"employeeNumber": "30",

"manager": {

"value": "Steve Kerr"

}

}

},

{

"id": "45c5f5187556447186bd5a710ba439e9",

"externalId": "00usabcdeAuobW0f8",

"meta": {

"created": "04-09-2020 00:00:00",

"lastModified": "10-14-2016 00:00:00",

"version": "v1.0"

},

"schemas": [

"urn:scim:schemas:core:1.0",

"urn:scim:schemas:extension:okta:1.0"

],

"userName": "scim1User1@scimone.com",

"displayName": "Scim1 Test User",

"preferredLanguage": "en",

"locale": "en_US",

"timezone": "America/Los_Angeles",

"active": true,

"password": "UVdKalpERXlNelE9",

"emails": [

{

"value": "scim1User1@scimone.com",

"type": "work",

"primary": true

}

],

"groups": [

{

"value": "8306945c760d4b0e8fae3e806614a19a",

"display": "ScimOne Group A"

}

],

"name": {

"familyName": "User",

"givenName": "Scim1 Test"

},

"urn:scim:schemas:extension:okta:1.0": {

"employeeNumber": "11253"

}

}

]

}

Import a user profile

Provisioning agent HTTP request and JSON message example

GET /Users/<Id>

Expected response from acting SCIM server connector

{

"id": "d0dd58e43ded4293a61a8760fcba0458",

"externalId": "00ustvXq1A8UAuobW0f5",

"meta": {

"created": "04-17-2020 00:00:00",

"lastModified": "04-17-2020 00:00:00",

"version": "v1.0"

},

"schemas": [

"urn:scim:schemas:core:1.0",

"urn:scim:schemas:extension:okta:1.0"

],

"userName": "steph@warriors.com",

"displayName": " Steph Curry",

"preferredLanguage": "en",

"locale": "en-US",

"timezone": "America/Los_Angeles",

"active": true,

"password": "VFhsSlpHVnVkR2wwZVVselRYbFFZWE56ZDI5eVpBPT0=",

"emails": [

{

"value": "steph@warriors.com",

"type": "work",

"primary": true

}

],

"groups": [],

"name": {

"familyName": "Curry",

"givenName": "Steph"

},

"urn:scim:schemas:extension:okta:1.0": {

"employeeNumber": "30",

"manager": {

"value": "Steve Kerr"

}

}

}

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 a user

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

Provisioning agent HTTP request and JSON message example

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 acting SCIM server connector

{

"id": "45c5f5187556447186bd5a710ba439e9",

"externalId": "00usabcdeAuobW0f8",

"meta": {

"created": "10-14-2016 00:00:00",

"lastModified": "10-14-2016 00:00:00",

"version": "v1.0"

},

"schemas": [

"urn:scim:schemas:core:1.0",

"urn:scim:schemas:extension:okta:1.0"

],

"userName": "scim1User1@scimone.com",

"displayName": "Scim1 Test User",

"preferredLanguage": "en",

"locale": "en_US",

"timezone": "America/Los_Angeles",

"active": true,

"password": "VlZaa1MyRnNjRVZTV0d4T1pXeEZPUT09",

"emails": [

{

"value": "scim1User1@scimone.com",

"type": "work",

"primary": true

}

],

"groups": [

{

"value": "8306945c760d4b0e8fae3e806614a19a",

"display": "ScimOne Group A"

}

],

"name": {

"familyName": "User",

"givenName": "Scim1 Test"

},

"urn:scim:schemas:extension:okta:1.0": {

"employeeNumber": "11253"

}

}

Deactivate user

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

Provisioning agent HTTP request and JSON message example

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 acting SCIM server connector

{

"id": "45c5f5187556447186bd5a710ba439e9",

"externalId": "00usabcdeAuobW0f8",

"meta": {

"created": "10-14-2016 00:00:00",

"lastModified": "10-14-2016 00:00:00",

"version": "v1.0"

},

"schemas": [

"urn:scim:schemas:core:1.0",

"urn:scim:schemas:extension:okta:1.0"

],

"userName": "scim1User1@scimone.com",

"displayName": "Scim1 Test User",

"preferredLanguage": "en",

"locale": "en_US",

"timezone": "America/Los_Angeles",

"active": false,

"password": "VlZaa1MyRnNjRVZTV0d4T1pXeEZPUT09",

"emails": [

{

"value": "scim1User1@scimone.com",

"type": "work",

"primary": true

}

],

"groups": [

{

"value": "8306945c760d4b0e8fae3e806614a19a",

"display": "ScimOne Group A"

}

],

"name": {

"familyName": "User",

"givenName": "Scim1 Test"

},

"urn:scim:schemas:extension:okta:1.0": {

"employeeNumber": "11253"

}

}

Reactivate a user

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

Provisioning agent HTTP request and JSON message example

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

{

"id": "45c5f5187556447186bd5a710ba439e9",

"externalId": "00usabcdeAuobW0f8",

"meta": {

"created": "10-14-2016 00:00:00",

"lastModified": "10-14-2016 00:00:00",

"version": "v1.0"

},

"schemas": [

"urn:scim:schemas:core:1.0",

"urn:scim:schemas:extension:okta:1.0"

],

"userName": "scim1User1@scimone.com",

"displayName": "Scim1 Test User",

"preferredLanguage": "en",

"locale": "en_US",

"timezone": "America/Los_Angeles",

"active": true,

"password": "VlZaa1MyRnNjRVZTV0d4T1pXeEZPUT09",

"emails": [

{

"value": "scim1User1@scimone.com",

"type": "work",

"primary": true

}

],

"groups": [

{

"value": "8306945c760d4b0e8fae3e806614a19a",

"display": "ScimOne Group A"

}

],

"name": {

"familyName": "User",

"givenName": "Scim1 Test"

},

"urn:scim:schemas:extension:okta:1.0": {

"employeeNumber": "11253"

}

}

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.

Provisioning agent HTTP request and JSON message example

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 acting SCIM server connector

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.

Provisioning agent HTTP request and JSON message example

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 acting SCIM server connector

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.

Provisioning agent HTTP request and JSON message example

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"

}

]

}

]

}

Expected response from acting SCIM server connector

{

"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.

Provisioning agent HTTP request and JSON message example

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"

}

}

Update Group

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

Provisioning agent HTTP request and JSON message example

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

Expected response from acting SCIM server connector

{

"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"

}

}

Delete Group

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

Provisioning agent HTTP request and JSON message example

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

Expected response from acting SCIM server connector

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

See also

Top