38 Managing OUD Directory Data with SCIM REST API
System for Cross-domain Identity Management (SCIM) is a standard protocol for accessing identity information (users, groups, etc) over HTTP(S).
Topics
OUD SCIM interface helps applications in which LDAP is not used to integrate with OUD as their Identity store, or to provision the identity information to OUD.
38.1 Configuring SCIM REST API
You can configure SCIM REST API support for Oracle Unified Directory during the setup.
Oracle Unified Directory exposes SCIM interface through HTTP(S) connection handlers. You can enable these handlers either during an OUD instance setup or through dsconfig for an existing instance.
Configuring Connection Handlers During the OUD Instance Setup
Run the oud-setup
utility from the command line with httpPort
and httpsPort
parameters to configure the SCIM interface while creating the Oracle Unified Directory Server instance.
oud-setup --cli \
--adminConnectorPort 1444 \
--httpAdminConnectorPort 1888 \
--rootUserDN cn=Directory\Manager \
--rootUserPasswordFile /home/oracle/pwd.txt \
--ldapPort 1389 \
--ldapsPort 1636 \
--httpPort 1080 \
--httpsPort 1081 \
--generateSelfSignedCertificate \
--baseDN dc=example,dc=com \
--sampleData 200 \
--serverTuning jvm-default \
--offlineToolsTuning jvm-default \
--no-prompt \
--noPropertiesFile
Configuring Connection Handlers for an Existing OUD Instance
- Run the
dsconfig
command-line utility withcreate-connection-handler
subcommand as follows to create the connection handlers:Note:
If you have already created the HTTP/HTTPS connection handler for the OUD instance, then you can update the existing connection handler using thedsconfig
command-line utility with theset-connection-handler-prop
subcommand.Setting Up HTTP Port:
dsconfig create-connection-handler \ --handler-name "HTTP Connection Handler" \ --type http \ --set enabled:true \ --set listen-port:1080 \ --hostname localhost \ --port 1444 \ --portProtocol LDAP \ --bindDN "cn=Directory Manager" \ --bindPasswordFile /home/oracle/pwd.txt \ --no-prompt
Setting Up HTTPS Port:
dsconfig create-connection-handler \ --handler-name "HTTPS Connection Handler" \ --type http \ --set enabled:true \ --set listen-port:1081 \ --set use-ssl:true \ --set trust-manager-provider:JKS \ --set key-manager-provider:JKS \ --hostname localhost \ --port 1444 \ --portProtocol LDAP \ --bindDN "cn=Directory Manager" \ --bindPasswordFile /home/oracle/pwd.txt \ --no-prompt
- Configure the REST endpoints as follows:
- Enable the
REST Server
extension.dsconfig set-extension-prop \ --Extension-name 'REST Server' \ --set enabled:true \ --hostname localhost \ --port 1444 \ --portProtocol LDAP \ --trustAll \ --bindDN "cn=Directory Manager" \ --bindPasswordFile /home/oracle/pwd.txt \ --no-prompt
- Enable the directory endpoint.
dsconfig set-directory-end-point-prop \ --set enabled:true \ --hostname localhost \ --port 1444 \ --portProtocol LDAP \ --trustAll \ --bindDN "cn=Directory Manager" \ --bindPasswordFile /home/oracle/pwd.txt \ --no-prompt
- Enable the
- Restart the OUD instance.
38.2 Using SCIM REST API
This section provides several sample programs that demonstrate how to make REST API calls through the SCIM interface.
38.2.1 Creating an Entry
You can create an user entry using SCIM API by sending a HTTP request with POST
method.
To create an entry through SCIM interface, send a request to URI /iam/directory/oud/scim/v1/Users
with the following payload.
{ "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User", "urn:ietf:params:scim:schemas:extension:oracle:2.0:OUD:User", "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User" ], "name": [ { "formatted": "First name Last name", "givenName": " First name ", "familyName": " Last name " } ], "password": [ { "value": "password" } ], "urn:ietf:params:scim:schemas:extension:oracle:2.0:OUD:User": { "employeenumber": "727", "objectClass": [ { "value": "top" } ], "mobile": [ { "value": "+1 503 555 0163" } ], "departmentnumber": [ { "value": "1" } ] }, "emails": [ { "value": "First name@example.com" } ], "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": { "department": [ { "value": "1" } ], "employeeNumber": [ { "value": "727" } ] }, "userName": [ { "value": "First name" } ] }
{ "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User", "urn:ietf:params:scim:schemas:extension:oracle:2.0:OUD:User", "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User" ], "name": [ { "formatted": "First name Last name", "givenName": " First name ", "familyName": " Last name " } ], "urn:ietf:params:scim:schemas:extension:oracle:2.0:OUD:User": { "objectClass": [ { "value": "top" }, { "value": "organizationalPerson" }, { "value": "person" }, { "value": "inetOrgPerson" } ], "mobile": [ { "value": "+1 503 555 0163" } ] }, "meta": { "location": "http://localhost:2080/iam/directory/oud/scim/v1/Users/ad55a34a-763f-358f-93f9-da86f9ecd9e4", "resourceType": "User" }, "emails": [ { "value": "First name@example.com" } ], "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": { "department": [ { "value": "1" } ], "employeeNumber": [ { "value": "727" } ] }, "userName": [ { "value": "First name" } ], "id": "ad55a34a-763f-358f-93f9-da86f9ecd9e4" }
38.2.2 Modifying an Entry
You can modify an user entry using SCIM API by sending a HTTP request with PATCH
method.
/iam/directory/oud/scim/v1/Users/<Entry UUID>
with the following payload:
Note:
You can search specific entry details by providing entry UUID. This entry UUID is a unique value generated randomly when an entry is created.{ "schemas": [ "urn:ietf:params:scim:api:messages:2.0:PatchOp" ], "Operations": [ { "op": "replace", "path": "urn:ietf:params:scim:schemas:core:2.0:User:password", "value": [ "password" ] } ] }
{ "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User", "urn:ietf:params:scim:schemas:extension:oracle:2.0:OUD:User", "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User" ], "name": [ { "formatted": " Replaced First name Last name", "givenName": " First name ", "familyName": " Last name " } ], "urn:ietf:params:scim:schemas:extension:oracle:2.0:OUD:User": { "objectClass": [ { "value": "top" }, { "value": "organizationalPerson" }, { "value": "person" }, { "value": "inetOrgPerson" } ], "mobile": [ { "value": "+1 503 555 0163" } ] }, "meta": { "location": "http://localhost:2080/iam/directory/oud/scim/v1/Users/ad55a34a-763f-358f-93f9-da86f9ecd9e4", "resourceType": "User" }, "emails": [ { "value": "First name@example.com" } ], "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": { "department": [ { "value": "1" } ], "employeeNumber": [ { "value": "727" } ] }, "userName": [ { "value": "First name" } ] }