Export and Import Users
The main purpose of SCIM implementation is to export User entities with complex filtering capability, and to import User entities from and into your IDM instance.
info
Referred entities, such as credential types, units, template collections, applications, roles and enterprise roles must exist in the target system, otherwise the import will fail.
The export can be performed using the List of users SCIM REST endpoint, where you can use paging, filtering and ordering.
The exported format is the SCIM 2.0 standard defined list response, where the resources can be incorporated into a bulk request where the operations must create user operation definitions. The body part of create operations can be the same as in the received list users response. The read only attributes are skipped. The target IDM system generates new id attributes for each new user entities. The formatted attributes, such as name.formatted, displayName are processed based on the name.familyName, name.givenName, name.middleName and name.honoricPrefix attributes. The id and all attributes of meta block are processed based on IDM internal identifiers and timestamps after the successful create operation. This means that the id and the meta.location are processed based on the generated new internal identifier in the IDM database. The meta.created and meta.lastModified attributes are processed based on assigned and sorted timestamps.
Limitation
The current implementation supports the following credentials: password, generic and ticket. In case a referred user has any more kinds of credentials, the SCIM mapping fails for these users. All other users are processed successfully.
Export
The following user list request queries the IDM database for users that successfuly logged in since the 1st of April 2022, sorts the output based on login identifiers of users in ascending order, and limits the result to a maximum of 10 resources:
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:SearchRequest"
],
"attributes": [],
"excludedAttributes": [],
"filter": "urn:nevis:idm:scim:schemas:v1:extension:User.credentials.credentialLoginInfo.lastLogin GT '2022-04-01T00:00:00'",
"sortBy": "userName",
"sortOrder": "ascending",
"startIndex": 1,
"count": 10
}
The response looks like the following example:
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:ListResponse"
],
"totalResults": 87,
"itemsPerPage": 10,
"startIndex": 1,
"Resources": [
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User",
"urn:nevis:idm:scim:schemas:v1:extension:User"
],
"id": "230004002",
"externalId": "extid230004003",
"meta": {
"resourceType": "User",
"created": "2000-01-01T00:00:00.000",
"lastModified": "2022-04-29T19:49:27.000",
"location": "http://localhost:8080/nevisidm/api/scim/v1/100/Users/230004002",
"version": "v1"
},
"userName": "ReportingUser1",
"name": {
"formatted": "Reporting1 ReportingUser1",
"familyName": "ReportingUser1",
"givenName": "Reporting1",
"honorificPrefix": "Rep1"
},
"displayName": "Reporting1 ReportingUser1",
"preferredLanguage": "en",
"active": true,
"emails": [
{
"value": "[email protected]",
"type": "work",
"primary": true
}
],
"phoneNumbers": [
{
"value": "12340002",
"type": "telephone",
"primary": true
},
{
"value": "12340003",
"type": "telefax",
"primary": false
},
{
"value": "22340001",
"type": "mobile",
"primary": false
}
],
"addresses": [
{
"formatted": "Budapest 1101 hu",
"locality": "Budapest",
"postalCode": "1101",
"country": "hu",
"primary": true
}
],
"urn:nevis:idm:scim:schemas:v1:extension:User": {
"remarks": "User for testing reporting",
"birthDate": "1983-03-02",
"technical": false,
"templateCollectionName": "Default",
"credentials": [
{
"extId": "extid230010003",
"type": "PASSWORD",
"state": "ACTIVE",
"validFrom": "2014-01-02T00:00:00",
"validTo": "2020-01-02T00:00:00",
"credentialLoginInfo": {
"lastLogin": "2022-04-29T19:49:27.000",
"loginSuccessCount": 1,
"lastFailure": "2022-04-29T19:49:27.000",
"loginFailureCount": 2
},
"password": "{SSHA}MsVwg87xlhHa6UzlRFBzEnRcriEChDVXqpLDWXNe"
}
],
"profiles": [
{
"state": "ACTIVE",
"name": "ReportingUser1_Profile",
"remarks": "Test Profile for Reporting feature",
"extId": "extid230005003",
"defaultProfile": true,
"unitExtId": "extid230002001",
"properties": {
"profile_global_string": "profilePropertyValue"
},
"idmAuthorizations": [
{
"extId": "230007041",
"roleExtId": "32",
"authorizedForAllClients": false,
"authorizedForAllUnits": false,
"authorizedForAllApplications": false,
"authorizedForAllEnterpriseRoles": false,
"authorizedClientExtIds": [
"100"
],
"authorizedApplicationExtIds": [
"extid230003001"
],
"authorizedUnitExtIdSetForClients": {
"100": [
"extid230002002",
"extid230002001"
]
}
}
],
"appAuthorizations": [
{
"extId": "230007002",
"roleExtId": "extid230006001"
},
{
"extId": "230007003",
"roleExtId": "extid230006002"
}
]
}
],
"properties": {
"User_Import_Property1": "userPropertyValue"
},
"loginInfo": {
"lastLogin": "2000-01-01T00:00:00.000"
}
}
},
...
Import
Your collected User entity representations have to be put into the mentioned bulk request as create operations, as shown in the following example:
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:BulkRequest"
],
"Operations": [
{
"method": "POST",
"bulkId": "UserCreate",
"path": "/Users",
"data": {
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User",
"urn:nevis:idm:scim:schemas:v1:extension:User"
],
"externalId": "teslatest",
"userName": "teslatest",
"name": {
"familyName": "teslatest",
"givenName": "teslatest",
"honorificPrefix": "Rep1"
},
"preferredLanguage": "en",
"active": true,
"emails": [
{
"value": "[email protected]",
"type": "work",
"primary": true
}
],
"phoneNumbers": [
{
"value": "12340002",
"type": "telephone",
"primary": true
},
{
"value": "12340003",
"type": "telefax",
"primary": false
},
{
"value": "22340001",
"type": "mobile",
"primary": false
}
],
"addresses": [
{
"locality": "Budapest",
"postalCode": "1101",
"country": "hu",
"primary": true
}
],
"urn:nevis:idm:scim:schemas:v1:extension:User": {
"remarks": "teslatest user",
"birthDate": "1983-03-02",
"technical": false,
"templateCollectionName": "Default",
"credentials": [
{
"extId": "teslatest",
"type": "PASSWORD",
"state": "ACTIVE",
"validFrom": "2014-01-02T00:00:00",
"validTo": "2020-01-02T00:00:00",
"password": "{SSHA}MsVwg87xlhHa6UzlRFBzEnRcriEChDVXqpLDWXNe"
}
],
"profiles": [
{
"state": "ACTIVE",
"name": "teslatest_Profile",
"remarks": "Test Profile for teslatest",
"extId": "teslatest",
"defaultProfile": true,
"validFrom": "2014-01-02T10:11:12",
"validTo": "2020-01-02T11:12:13",
"unitExtId": "extid230002001",
"properties": {
"profile_global_string": "profilePropertyValue"
},
"idmAuthorizations": [
{
"extId": "teslatest",
"roleExtId": "32",
"authorizedForAllClients": false,
"authorizedForAllUnits": false,
"authorizedForAllApplications": false,
"authorizedForAllEnterpriseRoles": false,
"authorizedClientExtIds": [
"100"
],
"authorizedApplicationExtIds": [
"extid230003001"
],
"authorizedUnitExtIdSetForClients": {
"100": [
"extid230002002",
"extid230002001"
]
}
}
]
}
],
"properties": {
"User_Import_Property1": "userPropertyValue"
},
"loginInfo": {
"lastLogin": "2000-01-01T00:00:00.000"
}
}
}
}
]
}
The response of the previous request looks like the following:
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:BulkResponse"
],
"Operations": [
{
"method": "POST",
"bulkId": "UserCreate",
"response": {
"headers": {},
"body": {
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User",
"urn:nevis:idm:scim:schemas:v1:extension:User"
],
"id": "9999999441",
"externalId": "teslatest",
"meta": {
"resourceType": "User",
"created": "2022-05-05T09:47:07.000",
"lastModified": "2022-05-05T09:47:07.000",
"location": "http://localhost:8080/nevisidm/api/scim/v1/100/Users/9999999441",
"version": "v1"
},
"userName": "teslatest",
"name": {
"formatted": "teslatest teslatest",
"familyName": "teslatest",
"givenName": "teslatest",
"honorificPrefix": "Rep1"
},
"displayName": "teslatest teslatest",
"preferredLanguage": "en",
"active": true,
"emails": [
{
"value": "[email protected]",
"type": "work",
"primary": true
}
],
"phoneNumbers": [
{
"value": "12340002",
"type": "telephone",
"primary": true
},
{
"value": "12340003",
"type": "telefax",
"primary": false
},
{
"value": "22340001",
"type": "mobile",
"primary": false
}
],
"addresses": [
{
"formatted": "Budapest 1101 hu",
"locality": "Budapest",
"postalCode": "1101",
"country": "hu",
"primary": true
}
],
"urn:nevis:idm:scim:schemas:v1:extension:User": {
"remarks": "teslatest user",
"birthDate": "1983-03-02",
"technical": false,
"templateCollectionName": "Default",
"credentials": [
{
"extId": "teslatest",
"type": "PASSWORD",
"state": "ACTIVE",
"validFrom": "2014-01-02T00:00:00",
"validTo": "2020-01-02T00:00:00",
"password": "{SSHA}MsVwg87xlhHa6UzlRFBzEnRcriEChDVXqpLDWXNe"
}
],
"profiles": [
{
"state": "ACTIVE",
"name": "teslatest_Profile",
"remarks": "Test Profile for teslatest",
"extId": "teslatest",
"defaultProfile": true,
"validFrom": "2014-01-02T10:11:12",
"validTo": "2020-01-02T11:12:13",
"unitExtId": "extid230002001",
"properties": {
"profile_global_string": "profilePropertyValue"
},
"idmAuthorizations": [
{
"extId": "260002419",
"roleExtId": "1",
"authorizedForAllClients": false,
"authorizedForAllUnits": false,
"authorizedForAllApplications": false,
"authorizedForAllEnterpriseRoles": false
},
{
"extId": "teslatest",
"roleExtId": "32",
"authorizedForAllClients": false,
"authorizedForAllUnits": false,
"authorizedForAllApplications": false,
"authorizedForAllEnterpriseRoles": false,
"authorizedClientExtIds": [
"100"
],
"authorizedApplicationExtIds": [
"extid230003001"
],
"authorizedUnitExtIdSetForClients": {
"100": [
"extid230002002",
"extid230002001"
]
}
}
]
}
],
"properties": {
"User_Import_Property1": "userPropertyValue"
}
}
},
"statusCode": "OK",
"statusCodeValue": 200
},
"status": "OK"
}
]
}
As you can see, the IDM generated a new user internal identifier: "id": "9999999441".
This identifier appears in the location as well: "location": "<http://localhost:8080/nevisidm/api/scim/v1/100/Users/9999999441>".
And as mentioned, the created and lastModified attributes received timestamps of the entity create process:
"created": "2022-05-05T09:47:07.000""lastModified": "2022-05-05T09:47:07.000"
The bulkImportFormat flag
This new flag is introduced to help the export-import process. By default it is false that means the query responses ScimListResponse instance as the standard defines. But, in case this flag is present and true the query responses ScimBulkRequest with prepared user create operations.
If your request looks like on the ...Users/.search endpoint:
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:SearchRequest"
],
"filter": "userName SW 'SCIM'",
"sortBy": "userName",
"sortOrder": "ascending",
"startIndex": 1,
"count": 10,
"bulkImportFormat": true
}
Your response will look like:
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:BulkRequest"
],
"failOnErrors": 10,
"Operations": [
{
"method": "POST",
"bulkId": "SCIMTestUser1",
"path": "Users",
"data": {
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User",
"urn:nevis:idm:scim:schemas:v1:extension:User"
],
"externalId": "SCIMTestUser1",
"userName": "SCIMTestUser1",
"name": {
"formatted": "User 1 SCIM Test",
"familyName": "SCIM Test",
"givenName": "User 1"
},
"displayName": "User 1 SCIM Test",
"preferredLanguage": "en",
"active": true,
"emails": [
{
"value": "[email protected]",
"type": "work",
"primary": true
}
],
"urn:nevis:idm:scim:schemas:v1:extension:User": {
"technical": false,
"templateCollectionName": "Default",
"credentials": [
{
"extId": "SCIMTestUser1Password",
"type": "PASSWORD",
"state": "ACTIVE",
"validFrom": "2022-05-16T12:11:49",
"validTo": "2032-05-13T12:11:49",
"credentialLoginInfo": {
"lastLogin": "2022-05-19T16:13:07.000",
"loginSuccessCount": 1,
"loginFailureCount": 0
},
"password": "{SSHA256}eje4XIkY6sGakInA+loqtNzj+QUo3N7sEIsj3fNge5lzYWx0"
}
],
"profiles": [
{
"state": "ACTIVE",
"name": "Profile-SCIMTestUser1",
"remarks": "Profile for SCIMTestUser1",
"extId": "SCIMTestUser1Profile",
"defaultProfile": true,
"unitExtId": "SCIMTestUnit",
"idmAuthorizations": [
{
"extId": "2845",
"roleExtId": "1",
"authorizedForAllClients": false,
"authorizedForAllUnits": false,
"authorizedForAllApplications": false,
"authorizedForAllEnterpriseRoles": false
}
],
"appAuthorizations": [
{
"extId": "SCIMTestUser1AppAuth111001",
"roleExtId": "111001",
"properties": {
"SCIMTestProperty": "SCIM1"
}
}
]
}
],
"properties": {
"USER_GLOBAL_property_1": "123"
},
"loginInfo": {
"lastLogin": "2022-05-19T16:13:07.000"
}
}
}
},
{
"method": "POST",
"bulkId": "SCIMTestUser2",
"path": "Users",
"data": {
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User",
"urn:nevis:idm:scim:schemas:v1:extension:User"
],
"externalId": "SCIMTestUser2",
"userName": "SCIMTestUser2",
"name": {
"formatted": "User 2 SCIM Test",
"familyName": "SCIM Test",
"givenName": "User 2"
},
"displayName": "User 2 SCIM Test",
"preferredLanguage": "en",
"active": true,
"emails": [
{
"value": "[email protected]",
"type": "work",
"primary": true
}
],
"urn:nevis:idm:scim:schemas:v1:extension:User": {
"technical": false,
"templateCollectionName": "Default",
"credentials": [
{
"extId": "SCIMTestUser2Password",
"type": "PASSWORD",
"state": "ACTIVE",
"validFrom": "2022-05-16T12:15:24",
"validTo": "2032-05-13T12:15:24",
"credentialLoginInfo": {
"lastLogin": "2022-05-19T16:12:27.000",
"loginSuccessCount": 2,
"loginFailureCount": 0
},
"password": "{SSHA256}eje4XIkY6sGakInA+loqtNzj+QUo3N7sEIsj3fNge5lzYWx0"
},
{
"extId": "SCIMTestUser2Ticket",
"type": "TICKET",
"state": "ACTIVE",
"validFrom": "2022-05-16T14:06:53",
"validTo": "2022-05-17T14:06:53",
"ticket": "{SSHA256}xlLYJHcjMt71MHsR+o58zSZLZxvKr4vTJ1B9vKfYbIZzdu4XzGIw7YOq"
}
],
"profiles": [
{
"state": "ACTIVE",
"name": "Profile-SCIMTestUser2",
"remarks": "Automatically generated profile for SCIMTestUser2",
"extId": "SCIMTestUser2Profile",
"defaultProfile": true,
"unitExtId": "SCIMTestUnit",
"idmAuthorizations": [
{
"extId": "2847",
"roleExtId": "1",
"authorizedForAllClients": false,
"authorizedForAllUnits": false,
"authorizedForAllApplications": false,
"authorizedForAllEnterpriseRoles": false
},
{
"extId": "SCIMTestUser2IdmAuth2",
"roleExtId": "2",
"authorizedForAllClients": false,
"authorizedForAllUnits": false,
"authorizedForAllApplications": false,
"authorizedForAllEnterpriseRoles": false,
"authorizedClientExtIds": [
"100"
]
}
],
"appAuthorizations": [
{
"extId": "SCIMTestUser2AppAuth111001",
"roleExtId": "111001"
}
]
}
],
"properties": {
"USER_GLOBAL_property_1": "123"
},
"loginInfo": {
"lastLogin": "2022-05-19T16:12:27.000"
}
}
}
}
]
}