37 Administering Oracle Unified Directory Using REST API
Oracle Unified Directory allows the users to perform administration and configuration through REST APIs. Admin REST APIs are exposed through HTTP Administration Connector.You can perform basic operations using HTTP methods GET, POST, PATCH or DELETE.
37.1 Configuring Admin REST API
You can configure the REST API support for OUD Admin interface during the setup of OUD instance. You need to configure the HTTP Administration Connector port during the setup of OUD instance to expose REST APIs for administering OUD instance.
For more information on HTTP Administration Connector, see HTTP Administration Connector.
Configuring HTTP Administrator Connector Port During OUD Instance Setup
Run oud-setup
utility from the command line with httpAdminConnectorPort
parameter to configure the Admin interface while creating the Oracle Unified Directory Server instance.
oud-setup --cli
--adminConnectorPort 1444
--httpAdminConnectorPort 1888
--rootUserDN cn=Directory\ Manager
--rootUserPasswordFile password.file
--ldapPort 1389
--ldapsPort 1636
--generateSelfSignedCertificate
--baseDN dc=example,dc=com
--addBaseEntry
--serverTuning jvm-default
--offlineToolsTuning jvm-default
--no-prompt
--noPropertiesFile
Configuring HTTP Administration Connector Port for an Existing OUD Instance
Run the dsconfig
command-line utility with set-administration-connector-prop
subcommand to update an existing OUD instance to expose HTTP Administration Connector to support Admin REST APIs.
dsconfig set-administration-connector-prop \ --connector-name HTTP \ --set listen-port:1888 \ --set enabled:true \ --hostname localhost\ --port 1444 \ --portProtocol LDAP \ --trustAll \ --bindDN cn=Directory\ Manager \ --bindPasswordFile password.file \ --no-prompt
37.2 Invoking the OUD Admin REST API
You can invoke OUD Admin REST API using the cURL command to send a request to https://<OUD HOST>:<HTTP Admin Connector Port>/rest/v1/admin
with the specific payload to perform administration tasks.
Following is an example for cURL command to invoke OUD Admin REST API:
curl -X POST -k -u '<root User DN>':<Password for root User DN> https://<OUD Host>:<HTTP Admin Connector Port>/rest/v1/admin -H 'cache-control: no-cache' -H 'content-type: application/json' -d '<Payload>'
37.3 Using Admin REST API
This section includes several sample programs that demonstrate how to perform administrative tasks using the Admin Rest API interface.
37.3.1 Searching a Network Group
You can search a particular network group by sending a HTTP request using POST
method.
To obtain details about a specific network group, send a request to https://<OUD HOST>:<HTTP Admin Connector Port>/rest/v1/admin
with the following payload:
{ "msgType" : "urn:ietf:params:rest:schemas:oracle:oud:1.0:SearchRequest", "dn" : "cn=network-group,cn=Network Groups,cn=config", "scope" : "sub", "filter" : "(objectclass=*)", "requiredAttributes" : [ "ds-cfg-priority", "ds-cfg-enabled" ], "base" : "cn=Network Groups,cn=config" }
The following response body is generated when you search for a network group with above mentioned payload:
{ "msgType": "urn:ietf:params:rest:schemas:oracle:oud:1.0:SearchResponse", "totalResults": 2, "searchResultEntries": [ { "dn": "cn=Network Groups,cn=config", "attributes": {} }, { "dn": "cn=network-group,cn=Network Groups,cn=config", "attributes": { "ds-cfg-priority": "1", "ds-cfg-enabled": "true" } } ] }
37.3.2 Adding a Network Group
You can add a particular network group by sending a HTTP request using POST
method.
To add a specific network group RestNetworkGroup
, send a request to https://<OUD HOST>:<HTTP Admin Connector Port>/rest/v1/admin
with the following payload:
{ "msgType" : "urn:ietf:params:rest:schemas:oracle:oud:1.0:AddRequest", "dn" : "cn=RestNetworkGroup,cn=Network Groups,cn=config", "attributes" : { "objectclass" : ["top", "ds-cfg-network-group"], "ds-cfg-priority" : ["0"], "ds-cfg-enabled" : ["true"], "cn" : ["RestNetworkGroup"] } }
The following response body is generated when you add RestNetworkGroup
using the above mentioned payload:
{ "msgType": "urn:ietf:params:rest:schemas:oracle:oud:1.0:AddResponse", "totalResults": 1, "searchResultEntries": [ { "dn": "cn=RestNetworkGroup,cn=Network Groups,cn=config", "attributes": { "ds-cfg-enabled": "true", "cn": "RestNetworkGroup", "ds-cfg-priority": "0", "objectClass": [ "top", "ds-cfg-network-group" ] } } ] }
37.3.3 Deleting a Network Group
You can delete a particular network group by sending a HTTP request using POST
method.
To delete a network group, send a request to https://<OUD HOST>:<HTTP Admin Connector Port>/rest/v1/admin
with the following payload:
{ "msgType" : "urn:ietf:params:rest:schemas:oracle:oud:1.0:DeleteRequest", "dn" : "cn=RestNetworkGroup,cn=Network Groups,cn=config" }
There is no response body generated since this is a delete operation.
37.3.4 Comparing a Network Group
You can compare a particular network group by sending a HTTP request using POST
method.
To compare a network group, send a request to https://<OUD HOST>:<HTTP Admin Connector Port>/rest/v1/admin
with the following payload:
{ "msgType" : "urn:ietf:params:rest:schemas:oracle:oud:1.0:CompareRequest", "dn" : "cn=RestNetworkGroup,cn=Network Groups,cn=config", "assertion" : "ds-cfg-enabled:true" }
The following response body is generated when a compare operation is performed with the above mentioned payload:
{ "msgType": "urn:ietf:params:rest:schemas:oracle:oud:1.0:CompareResponse", "compareResult": true }
37.3.5 Modifying a Network Group
You can modify a network group by sending a HTTP request using POST
method.
To modify a network group, send a request to https://<OUD HOST>:<HTTP Admin Connector Port>/rest/v1/admin
with the following payload:
{ "msgType" : "urn:ietf:params:rest:schemas:oracle:oud:1.0:ModifyRequest", "operations" : [ { "opType" : "replace", "attribute" : "ds-cfg-enabled", "values" : ["false"] } ] }
The following response body is generated when a modify operation is performed with the above mentioned payload:
{ "msgType": "urn:ietf:params:rest:schemas:oracle:oud:1.0:ModifyResponse", "totalResults": 1, "searchResultEntries": [ { "dn": "cn=RestNetworkGroup,cn=Network Groups,cn=config", "attributes": { "ds-cfg-enabled": "false", "cn": "RestNetworkGroup", "ds-cfg-priority": "0", "objectClass": [ "top", "ds-cfg-network-group" ] } } ] }
37.3.6 Searching a Network Group using GET method
You can search a particular network group by sending an HTTP request to https://rest/v1/admin/cn=RestNetworkGroup,cn=Network Groups,cn=config
using GET
method.
No request body for GET.
The following response body is generated when a search operation is performed:
{ "msgType": "urn:ietf:params:rest:schemas:oracle:oud:1.0:SearchResponse", "totalResults": 1, "searchResultEntries": [ { "dn": "cn=RestNetworkGroup,cn=Network Groups,cn=config", "attributes": { "ds-cfg-enabled": "true", "cn": "RestNetworkGroup", "ds-cfg-priority": "0", "objectClass": [ "top", "ds-cfg-network-group" ] } } ] }