SCIM messages for on-premises provisioning
Okta uses a subset of available SCIM messages to send provisioning instructions to a SCIM server. These are the Okta SCIM provisioning messages:
- Get implemented user management capabilities
- Create a user
- Create a pending user
- Import users from an on-premises app into Okta
- Import recently changed users from an on-premises app into Okta
- Import a user profile
- Activate a user
- Deactivate user
- Reactivate a user
- Push password update
- Push profile update
- Download groups
- Create a group
- Update a group
- Delete a group
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, the app integration supports appropriate provisioning features.
Okta 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 user
This instruction is sent when you assign a new user to an on-premises app.
Okta sends two messages. The first one determines whether the user exists in the on-premises app. If the user doesn't exist in the on-premises app, Okta sends another message to create the user.
Okta Provisioning Agent HTTP request and JSON message example
GET /Users?filter=userName%20eq%20%22myemail%40example.com%22&startIndex=1&count=100
Expected response from acting SCIM server connector
The following example shows a return when the user doesn't 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": "admin", "password": "fakepassword", "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" } } ] }
Okta 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@example.com", "emails":[ { "primary":true, "value":"myemail@example.com", "type":"primary" }, { "primary":false, "value":"mypersonalemail@example.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.c@example.com", "displayName": " Steph Curry", "preferredLanguage": "en", "locale": "en-US", "timezone": "America/Los_Angeles", "active": true, "password": "VFhsSlpHVnVkR2wwZVVselRYbFFZWE56ZDI5eVpBPT0=", "emails": [ { "value": "steph.c@example.com", "type": "work", "primary": true } ], "groups": [], "name": { "familyName": "Curry",
Create a pending user
This instruction is sent when an Okta user, who hasn't been activated yet in Okta, is assigned to an on-premises app.
This call is similar to the preceding call that creates a user, with the addition of the active field.
Okta Provisioning Agent HTTP request and JSON message example
POST /Users { "schemas":[ "urn:scim:schemas:core:1.0" ], "userName":"myemail-pending@example.com", "emails":[ { "primary":true, "value":"myemail-pending@example.com", "type":"primary" }, { "primary":false, "value":"mypersonalemail-pending@example.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.c@example.com", "displayName": " Steph Curry", "preferredLanguage": "en", "locale": "en-US", "timezone": "America/Los_Angeles", "active": true, "password": "VFhsSlpHVnVkR2wwZVVselRYbFFZWE56ZDI5eVpBPT0=", "emails": [ { "value": "steph.c@example.com", "type": "work", "primary": true } ], "groups": [], "name": { "familyName": "Curry", "givenName": "Steph" }, "urn:scim:schemas:extension:okta:1.0": { "employeeNumber": "30", "manager": { "value": "Steve Kerr" } } }
Import users from an on-premises app into Okta
This instruction is sent when an admin imports users from an on-premises app into Okta.
Okta Provisioning Agent might make multiple requests to your connector if multiple pages of users exist.
Okta 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@example.com", "displayName": "Inactive Scim1 Test User", "preferredLanguage": "en", "locale": "en_US", "timezone": "America/Los_Angeles", "active": false, "password": "UVdKalpERXlNelE9", "emails": [ { "value": "InactiveScim1User1@example.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.c@example.com", "displayName": " Steph Curry", "preferredLanguage": "en", "locale": "en-US", "timezone": "America/Los_Angeles", "active": true, "password": "VFhsSlpHVnVkR2wwZVVselRYbFFZWE56ZDI5eVpBPT0=", "emails": [ { "value": "steph.c@example.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@example.com", "displayName": "Scim1 Test User", "preferredLanguage": "en", "locale": "en_US", "timezone": "America/Los_Angeles", "active": true, "password": "UVdKalpERXlNelE9", "emails": [ { "value": "scim1User1@example.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 recently changed users from an on-premises app into Okta
This instruction is sent when an admin runs an incremental import of users from an on-premises app into Okta.
Okta Provisioning Agent might make multiple requests to your connector if multiple pages of users exist.
Okta Provisioning Agent HTTP request and JSON message example
GET /Users?filter=meta.lastModified gt "2020-04-07T14:19:34Z"&startIndex=1&count=100
Expected response from acting SCIM server connector
{ "schemas": [ "urn:scim:schemas:core:1.0" ], "totalResults": 1, "startIndex": 1, "itemsPerPage": 1, "Resources": [ { "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.c@example.com", "displayName": " Steph Curry", "preferredLanguage": "en", "locale": "en_US", "timezone": "America/Los_Angeles", "active": true, "password": "VFhsSlpHVnVkR2wwZVVselRYbFFZWE56ZDI5eVpBPT0=", "emails": [ { "value": "steph.c@example.com", "type": "work", "primary": true } ], "groups": [], "name": { "familyName": "Curry", "givenName": "Steph" } "urn:scim:schemas:extension:okta:1.0": { "employeeNumber": "30", "manager": { "value": "Steve Kerr" } } }, ] }
Import a user profile
Okta 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.c@example.com", "displayName": " Steph Curry", "preferredLanguage": "en", "locale": "en-US", "timezone": "America/Los_Angeles", "active": true, "password": "VFhsSlpHVnVkR2wwZVVselRYbFFZWE56ZDI5eVpBPT0=", "emails": [ { "value": "steph.c@example.com", "type": "work", "primary": true } ], "groups": [], "name": { "familyName": "Curry", "givenName": "Steph" }, "urn:scim:schemas:extension:okta:1.0": { "employeeNumber": "30", "manager": { "value": "Steve Kerr" } } }
During provisioning, when Okta discovers that a user exists in the on-premises app, Okta either pushes the user profile to the on-premises app or imports the profile. This depends on whether you have the Push Profile Update option enabled. If the option is enabled, Okta pushes the profile of the user to the on-premises app. If it's not enabled, Okta imports the user profile.
Activate a user
This instruction is sent when a user who was previously provisioned in the inactive state is activated in Okta.
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@example.com", "displayName": "Scim1 Test User", "preferredLanguage": "en", "locale": "en_US", "timezone": "America/Los_Angeles", "active": true, "password": "VlZaa1MyRnNjRVZTV0d4T1pXeEZPUT09", "emails": [ { "value": "scim1User1@example.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 the Okta app integration or a user is deactivated in Okta.
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@example.com", "displayName": "Scim1 Test User", "preferredLanguage": "en", "locale": "en_US", "timezone": "America/Los_Angeles", "active": false, "password": "VlZaa1MyRnNjRVZTV0d4T1pXeEZPUT09", "emails": [ { "value": "scim1User1@example.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
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@example.com", "displayName": "Scim1 Test User", "preferredLanguage": "en", "locale": "en_US", "timezone": "America/Los_Angeles", "active": true, "password": "VlZaa1MyRnNjRVZTV0d4T1pXeEZPUT09", "emails": [ { "value": "scim1User1@example.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 a user changes their password on Okta and Sync Password is enabled under To App on the Provisioning tab for the app.
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 Update User Attributes is enabled for the app. See Automatically update user attributes.
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. If Create Users and Update User Attributes are enabled to update on-premises app users upon their creation or update, then the connector sends back the updated user. See Configure provisioning for an app integration.
Download groups
This instruction is sent when an admin imports users into Okta.
Okta Provisioning Agent HTTP request and JSON message example
GET request /Groups?startIndex=1&count=100
Expected response from the connector acting as a 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 a group
This instruction is sent when the Group Push feature is enabled for an app integration in Okta. See Enable Group Push.
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 a group
This instruction is sent when Group Push is enabled for an app integration in Okta. See Enable Group Push.
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 a group
This instruction is sent when Group Push is enabled for an app integration in Okta. See Enable Group Push.
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.