See scim Menu
  1. Home >
  2. SCIM >
  3. Step 2. Implement RESTful SCIM APIs for Your App

Step 2. Implement RESTful SCIM APIs for Your App

A key piece to implementing SCIM is building a RESTful API that OneLogin SCIM provisioning can call to provision users to your app. Here are the calls your API should be able to receive from OneLogin SCIM provisioning:

  • Get User with userName filter

  • Create User

  • Get User by ID

  • Update User

  • Get Groups

  • Create Group

  • Patch Group 

  • Delete User

  • Get Users

To learn about how these calls should flow between OneLogin SCIM provisioning and your app, see Example API Flow.

For detailed examples that can guide your SCIM API design, see Example API Reference.

Example API Flow

Use this example flow to understand the OneLogin SCIM provisioning requests that your app’s SCIM API will need to receive and respond to.

Note: With the exception of steps 1 and 2, the flow sequence will vary. This flow is just meant to indicate an example flow of requests and responses. Also, the content type header for all responses must be of type application/json 

  1. Initial connection

    • Request:

      As discussed in Connect Your SCIM Test App to Your SCIM Implementation, the OneLogin SCIM app created for your app needs to connect to your SCIM API’s base URL.

      Upon this initial connection, OneLogin SCIM provisioning makes a Get User by userName request using a userName filter value that it knows is non-existent.

      Note: This initial connection does not invoke any actual provisioning and just makes the Get User request.

    • Response:

      Your SCIM API just needs to respond with an empty array of users or alternately a 404 Not Found status, which upon this initial connection, OneLogin SCIM provisioning interprets as a confirmation that your SCIM API endpoint is valid.

    For details, see Get User by userName API.

  2. Provisioning request

    • Request:

      OneLogin SCIM provisioning makes a Get User by userName request using userName filter values corresponding to each user that has been given access to the OneLogin SCIM app created for your app. This call determines if the user needs to be created or updated in your app.

    • Response:

      Your SCIM API needs to respond with an array containing the matching user record, or an empty array if there is no match.

    For details, see Get User by userName API.

  3. Create User request

    • Request:

      If OneLogin SCIM provisioning receives a empty response to its Get User by userName request, indicating that the user does not exist, it will make a Create User request to create the user.

    • Response:

      To confirm that the user was created, your SCIM API should respond with the SCIM payload of the created user. This payload must include a unique an immutable user id (SCIM user ID) generated and assigned by your API.

      Note: Once this SCIM ID has been created, OneLogin provisioning will use it to uniquely identify the user.

    For details, see Create User API.

  4. Update User

    • Request:

      If OneLogin SCIM provisioning receives a user record in response to its Get User by userName request or to a Get User by ID request, indicating that the user exists, it will make an Update User request to make any necessary modifications, such as to licenses, roles, and entitlements.

      For information about the flow if the request also includes a group value, see Create Group.

    • Response:

      To confirm that the update was made to the user, your SCIM API should include the SCIM payload of the updated user.

    For details, see Update User API.

  5. Create Group

    • Pre-request

      Creating a group involves a few checks before the Create Group request is actually made.

      1. OneLogin SCIM provisioning makes an Update User request that includes a group value.

      2. In response to the request, your SCIM API responds with the updated user payload.

      3. OneLogin SCIM provisioning will check your response to see if the group has been added to the user.

      4. If the group has not been added to the user, OneLogin SCIM provisioning makes a Get User by ID request to make one last check before actually making the Create Group request. If the group does not exist on the user, it makes the Create Group request.

      5. If the group has been added to the user, Onelogin SCIM provisioning makes a Patch Group request to patch the user into the group.

    • Request:

      If OneLogin SCIM provisioning has made an Update User request that includes a group value that it has confirmed does not exist (per the Pre-request section above), it will make a Create Group request.

    • Response:

      Your SCIM API should return the SCIM payload for the newly created group. The payload must include a unique and immutable group id (SCIM group ID) generated and assigned by your API.

    For details, see Create Group API.

  6. Patch User into Group

    • Request:

      Once OneLogin SCIM provisioning has verified that the group to which the user needs to be added exists, it makes a Patch Group request.

    • Response:

      Your SCIM API returns a 204 No Content status to confirm that the user was patched into the group.

    • Post-Response Request:

      OneLogin SCIM provisioning will make a Get User by ID request to verify that the group was added to the user.

    For details, see Patch Group API.

  7. Suspend User

    • Request:

      OneLogin SCIM provisioning makes an Update User request with active:false in the payload.

    • Response:

      To confirm that the user was updated, your SCIM API should include the SCIM payload of the updated user.

    For details, see Update User API.

  8. Delete User

    • Request:

      OneLogin SCIM provisioning makes a Delete User request.

    • Response:

      Your SCIM API should return a 204 No Content status.

      You can choose to delete the user completely, or to just set active:false in the user payload. However, you must return a 404 Not Found for all requests made for the deleted user. You must also not include the deleted user in future query results.

    For details, see Delete User API.

Example API Reference

Use this API reference as a guide to designing your SCIM APIs to respond to requests from OneLogin SCIM provisioning per the API Flow.

For detailed SCIM API standards, see System for Cross-Domain Identity Management:Protocol 1.1: API.

Get User by userName

Resource URL

GET /Users?filter=userName eq ""

Header Parameter

Authorization: Bearer 

Sample Responses

200 OK - User Exists
{
   "totalResults":1,
   "itemsPerPage":10,
   "startIndex":1,
   "schemas":[
      "urn:scim:schemas:core:1.0"
   ],
   "Resources":[
      {
         "schemas":[
            "urn:scim:schemas:core:1.0"
         ],
         "id":"XU0JCG4EGJX",
         "externalId":"",
         "meta":{
            "created":"2016-01-13T11:07:57-08:00",
            "location":"https://api.scimapp.com/scim/v1/Users/XU0JCG4EGJX"
         },
         "userName":"ttoure@example.com",
         "nickName":"Titi",
         "name":{
            "givenName":"Taylor",
            "familyName":"Toure"
         },
         "displayName":"Taylor Toure",
         "profileUrl":"https://example.app.com/team/Titi",
         "title":"Director of Swagger",
         "timezone":"Pacific Standard Time",
         "active":true,
         "emails":[
            {
               "value":"ttoure@example.com",
               "primary":true
            }
         ],
         "photos":[
            {
               "value":"https://avatars.app-edge.com/2016-01-14/62c25b4f8ced246b0_192.png",
               "type":"photo"
            }
         ],
         "groups":[
            {
               "value":"XS0DHQNXPX",
               "display":"Group_from_custom"
            }
         ]
      }
   ]
}
200 OK - User Does Not Exist
{
   "totalResults":0,
   "itemsPerPage":10,
   "startIndex":1,
   "schemas":[
      "urn:scim:schemas:core:1.0"
   ],
   "Resources":[

   ]
}

Create User

Resource URL

POST /Users

Header Parameters

  • Authorization: Bearer 

  • Content-Type: application/json

Sample Request

{
   "schemas":[
      "urn:scim:schemas:core:1.0"
   ],
   "externalId":"",
   "userName":"jbibinka2@example.com",
   "nickName":"Bibi2",
   "name":{
      "givenName":"Justin",
      "familyName":"Bibinka"
   },
   "displayName":"jbibinka",
   "profileUrl":"https://example.app.com/team/justin",
   "title":"Director of Sanging",
   "timezone":"Pacific Standard Time",
   "active":true,
   "emails":[
      {
         "value":"jbibinka2@example.com",
         "primary":true
      }
   ],
   "photos":[
      {
         "value":"https://secure.gravatar.com/avatar/506c1f645ad2266f2353a50230c52f84.jpg",
         "type":"photo"
      }
   ],
   "groups":[

   ]
}

Sample Responses

201 Created
{
   "schemas":[
      "urn:scim:schemas:core:1.0"
   ],
   "id":"XU0JFMAFB7X",
   "externalId":"",
   "meta":{
      "created":"2016-01-14T12:40:59-08:00",
      "location":"https://api.app.com/scim/v1/Users/XU0JFMAFB7X"
   },
   "userName":"jbibinka2@example.com",
   "nickName":"Bibi2",
   "name":{
      "givenName":"Justin",
      "familyName":"Bibinka"
   },
   "displayName":"Justin Bibinka",
   "profileUrl":"https://example.app.com/team/Bibi2",
   "title":"Director of Sanging",
   "timezone":"Pacific Standard Time",
   "active":true,
   "emails":[
      {
         "value":"jbibinka2@example.com",
         "primary":true
      }
   ],
   "photos":[
      {
         "value":"https://secure.gravatar.com/avatar/506c1f645ad2266f2353a50230c52f84.jpg",
         "type":"photo"
      }
   ],
   "groups":[

   ]
}

Get User by ID (SCIM ID)

Resource URL

GET /Users/ 

Header Parameter

Authorization: Bearer 

Sample Responses

200 OK - User Exists
{
   "schemas":[
      "urn:scim:schemas:core:1.0"
   ],
   "id":"XU0JFNGLPNX",
   "externalId":"",
   "meta":{
      "created":"2016-01-14T13:09:56-08:00",
      "location":"https://api.app.com/scim/v1/Users/XU0JFNGLPNX"
   },
   "userName":"hgolightly@example.com",
   "nickName":"hollyg",
   "name":{
      "givenName":"",
      "familyName":""
   },
   "displayName":"hollyg",
   "profileUrl":"https://example.app.com/team/hollyg",
   "title":"Director of Optimism",
   "timezone":"Pacific Standard Time",
   "active":true,
   "emails":[
      {
         "value":"hgolightly@example.com",
         "primary":true
      }
   ],
   "photos":[
      {
         "value":"https://avatars.app-edge.com/2016-01-14/cc991ae100d17acb6390_192.png",
         "type":"photo"
      }
   ],
   "groups":[

   ]
}

Update User

Resource URL

PUT /Users/{id}

Parameters

  • Authorization: Bearer 

  • Content-Type: application/json

  • active: When a user is created, this parameter is set to true. To suspend a user, set this parameter to false.

Sample Request

{
   "schemas":[
      "urn:scim:schemas:core:1.0"
   ],
   "externalId":"",
   "userName":"taylor.toure@example.com",
   "nickName":"Titi",
   "name":{
      "givenName":"Taylor",
      "familyName":"Toure"
   },
   "displayName":"ttoure",
   "profileUrl":"https://example.app.com/team/taylor",
   "title":"Director of Swagger",
   "timezone":"Pacific Standard Time",
   "active":true,
   "emails":[
      {
         "value":"ttoure@example.com",
         "primary":true
      }
   ],
   "photos":[
      {
         "value":"https://avatars.app-edge.com/2016-01-14/cc991ae100d17acb6390_192.png",
         "type":"photo"
      }
   ],
   "groups":[

   ]
}

Sample Response

200 OK
{
   "schemas":[
      "urn:scim:schemas:core:1.0"
   ],
   "id":"XU0JCG4EGJX",
   "externalId":"",
   "meta":{
      "created":"2016-01-13T11:07:57-08:00",
      "location":"https://api.app.com/scim/v1/Users/XU0JCG4EGJX"
   },
   "userName":"ttoure@example.com",
   "nickName":"Titi",
   "name":{
      "givenName":"Taylor",
      "familyName":"Toure"
   },
   "displayName":"Taylor Toure",
   "profileUrl":"https://example.app.com/team/Titi",
   "title":"Director of Swagger",
   "timezone":"Pacific Standard Time",
   "active":true,
   "emails":[
      {
         "value":"ttoure@example.com",
         "primary":true
      }
   ],
   "photos":[
      {
         "value":"https://avatars.app-edge.com/2016-01-14/62c25b4f8982ced246b0_192.png",
         "type":"photo"
      }
   ],
   "groups":[
      {
         "value":"XS0DHQNXPX",
         "display":"Group_from_custom"
      }
   ]
}

Get Groups

Resource URL

GET /Groups 

Header Parameter

Authorization: Bearer 

Sample Response

200 OK
{
   "totalResults":2,
   "itemsPerPage":10,
   "startIndex":1,
   "schemas":[
      "urn:scim:schemas:core:1.0"
   ],
   "Resources":[
      {
         "schemas":[
            "urn:scim:schemas:core:1.0"
         ],
         "id":"XS0DCDLW5DX",
         "displayName":"Admins",
         "members":[
            {
               "value":"XU0DCDLVSTX",
               "display":"Adminatrix"
            }
         ],
         "meta":{
            "created":"2015-10-28T10:57:28-07:00",
            "location":"https://api.app.com/scim/v1/Groups/S0DCDLW5D"
         }
      },
      {
         "schemas":[
            "urn:scim:schemas:core:1.0"
         ],
         "id":"XS0DCECG1GX",
         "displayName":"Default",
         "members":[
            {
               "value":"XU0DC7MQMAX",
               "display":"John Imonlydancing"
            },
            {
               "value":"XU0DCDLVSTX",
               "display":"Jean Genie"
            },
            {
               "value":"XU0DCYSWBSX",
               "display":"Major Tom Space"
            }
         ],
         "meta":{
            "created":"2015-10-28T10:57:28-07:00",
            "location":"https://api.app.com/scim/v1/Groups/XS0DCECG1GX"
         }
      }
   ]
}

Create Group

Resource URL

POST /Groups

Header Parameters

  • Authorization: Bearer 

  • Content-Type: application/json

Sample Request

{
   "schemas":[
      "urn:scim:schemas:core:1.0"
   ],
   "displayName":"Contractors",
   "members":[

   ]
}

Sample Response

201 Created

<

div class=”copy-container”>

{
   "schemas":[
      "urn:scim:schemas:core:1.0"
   ],
   "id":"XS0JG2QFLGX",
   "displayName":"Contractors",
   "members":[

   ],
   "meta":{
      "created":"2016-01-14T14:46:19-08:00",
      "location":"https://api.app.com/scim/v1/Groups/XS0JG2QFLGX"
   }
}
400 Bad Request
{
   "Errors":{
      "description":"name_already_exists",
      "code":400
   }
}

Patch Group

Resource URL

PATCH /Groups/{id}

Parameters

  • Authorization: Bearer 

  • Content-Type: application/json

  • "operation": "delete" Include this member attribute to remove a user from a group.

Sample Request

Add a member
{
   "schemas":[
      "urn:scim:schemas:core:1.0"
   ],
   "members":[
      {
         "value":"XU0JCG4EGJX"
      }
   ]
}
Remove a member
{
 "schemas":[
 "urn:scim:schemas:core:1.0"
 ],
 "members":[
 {
 "value":"XU0JCG4EGJX",
 "operation":"remove"
 }
 ]
}
}

Delete User

Resource URL

DELETE /Users/{id}

Header Parameter

Authorization: Bearer 

Sample Response

A response with a 204 No Content status code indicates a successful request.

You can choose to delete the user completely, or to just set active:false in the user payload. However, you must return a 404 Not Found for all requests made for the deleted user. You must also not include the deleted user in future query results.

Get Users

Resource URL

GET /Users

Note: itemsPerPage and startIndex query parameters can be used for pagination. For example, use a URL like the following to return two records starting with the third record in the list of results: /Users?count=2&startIndex=3

Header Parameter

Authorization: Bearer 

Sample Responses

200 OK
{
   "totalResults":37,
   "itemsPerPage":2,
   "startIndex":3,
   "schemas":[
      "urn:scim:schemas:core:1.0"
   ],
   "Resources":[
      {
         "schemas":[
            "urn:scim:schemas:core:1.0"
         ],
         "id":"XU0JCG4EGJX",
         "externalId":"",
         "meta":{
            "created":"2016-01-13T11:07:57-08:00",
            "location":"https://api.app.com/scim/v1/Users/XU0JCG4EGJX"
         },
         "userName":"ttoure@example.com",
         "nickName":"Titi",
         "name":{
            "givenName":"Taylor",
            "familyName":"Toure"
         },
         "displayName":"Taylor Toure",
         "profileUrl":"https://example.app.com/team/Titi",
         "title":"Director of Swagger",
         "timezone":"Pacific Standard Time",
         "active":true,
         "emails":[
            {
               "value":"ttoure@example.com",
               "primary":true
            }
         ],
         "photos":[
            {
               "value":"https://avatars.app-edge.com/2016-01-14/df656bace122f230f_192.png",
               "type":"photo"
            }
         ],
         "groups":[
            {
               "value":"XS0DHQNXPX",
               "display":"Group_from_custom"
            }
         ]
      },
      {
         "schemas":[
            "urn:scim:schemas:core:1.0"
         ],
         "id":"XU0JJGU16EX",
         "externalId":"",
         "meta":{
            "created":"2016-01-15T11:35:27-08:00",
            "location":"https://api.app.com/scim/v1/Users/U0JJGU16E"
         },
         "userName":"jjalloh@example.com",
         "nickName":"JJ",
         "name":{
            "givenName":"Justin",
            "familyName":"Jalloh"
         },
         "displayName":"Justin Jalloh",
         "profileUrl":"https://exampledev.app.com/team/JJ",
         "title":"Director of Justice",
         "timezone":"Pacific Standard Time",
         "active":true,
         "emails":[
            {
               "value":"jjalloh@example.com",
               "primary":true
            }
         ],
         "photos":[
            {
               "value":"https://avatars.app-edge.com/2016-01-15/af5d7e463c7cfff6c_192.png",
               "type":"photo"
            }
         ],
         "groups":[

         ]
      }
   ]
}

Have a Question?

Found a problem or a bug? Submit a support ticket.

Looking for walkthroughs or how-to guides on OneLogin's user and admin features? Check out the documentation in our Knowledge Base.

Have a product idea or request? Share it with us in our Ideas Portal.