Administering Oracle Unified Directory Using REST API

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"
                ]
            }
        }
    ]
}