The objective of this post is to show the differences and similarities of the two REST APIs offered by OIM – the SCIM REST API and the OIG REST API.
OIM Java APIs have been available in OIM for many versions now (since OIM 9.x or earlier), although each successive version has added new Java APIs to provide access to new functionality. The SCIM REST web services were newly introduced in 22.214.171.124. My previous blog post contains some discussions of the pros and cons of each API and when to use each one.
In Bundle Patch 126.96.36.199.161018 (Patch 24326201), a third option has been introduced – the OIG REST API. The OIG REST API is not automatically installed with the bundle patch but is a separate installation procedure (see the bundle patch README for details). It is documented here.
Note that while the two REST APIs differ both in their capabilities and in the syntax used to invoke those capabilities, one area of commonality is security. Both APIs delegate their security to OWSM and use the same OWSM policy, so they are secured identically. On that topic please see, in addition to this post, my colleague Pulkit's post on securing OIM REST APIs.
The table below provides a side-by-side comparison of the SCIM REST API with the OIG REST API:
|SCIM REST||OIG REST|
|Availability||OIM 188.8.131.52.0 and later (installed out-of-the-box)||OIM 184.108.40.206.161018 and later (additional installation step required)|
|Documentation||SCIM REST API Docs||OIG REST API Docs|
|Standardization||Industry standard (RFC7642, RFC7643, RFC7644) with Oracle extensions||Oracle proprietary|
|Capabilities||More limited overall than OIG REST||Richer overall than SCIM REST|
|Security model||Based on OWSM using oracle/multi_token_noauth_rest_service_policy||Based on OWSM using oracle/multi_token_noauth_rest_service_policy|
|Metadata||SCIM schemas (/Schemas resource)||Swagger|
|SCIM REST||OIG REST|
|My Profile||/Me||No direct equivalent (but same functionality is implementable in an indirect way)|
|Password reset using challenges||/PasswordResetterWithChallenges||/unauthservice/passwordreset|
|Validate password||/PasswordValidator||No direct equivalent (but password will be validated while being set)|
|User name generation||/UserNameGenerator||No direct equivalent (but username generation can be invoked by creating a user without specifying a username)|
|User name recovery||/UserNameRecoverer||/unauthservice/forgotusername|
|User name validation||/UserNameValidator||No direct equivalent (but username will be validated during user creation)|
|Password policies||/PasswordPolicies||Not supported|
|Username policies||Not supported||/policies|
|Access policies||Not supported||/policies|
|Approval policies||Not supported||/policies|
|Notification templates||/NotificationTemplates||Not supported|
|System properties||/SystemProperties||Not supported|
|Admin roles||Not supported||AdminRole|
|Identity Audit||Not supported||Identity Audit|
|Provisioning tasks||Not supported||ProvisioningTask|
|Request management||Not supported||Requests|
As you can see from the above, there are some capabilities both APIs have in common and there are also some capabilities unique to one or the other. However, overall, it is clear that the OIG REST API offers a richer selection of capabilities than the SCIM REST API does.
Note that the JSON Web Token (JWT) issuance endpoints strictly speaking form part of the OIG REST API, but the tokens they generate are equally usable with the SCIM REST API.
Obviously, if you need the additional functionality that the OIG REST API alone provides, then the OIG REST API is the answer. If you don't need that additional functionality, then the standardisation and cloud interoperability that the SCIM REST API provides could be a good reason to choose the SCIM REST API.
Note that it is possible to use both APIs in the one application. However, if you choose to do that, you should make sure you are choosing which API to use in each case based on rational criteria rather than random whims. For example, you might decide that you want to use the SCIM REST API wherever possible, and only use the OIG REST API when you need the additional functionality which the OIG REST API alone provides.