Before You Begin

This tutorial shows you how to configure REST Application Programming Interface (API) support for Oracle Unified Directory (OUD). It also shows how to make REST API calls to Oracle Unified Directory using Postman, software typically used for REST API tests. This tutorial takes approximately 15 minutes to complete.

Background

The OUD REST APIs provide a way to integrate OUD with REST clients so that they can administer the OUD configuration and manage directory data. OUD provides REST API's for OUD Administration at <httpAdminConnectorPort>/rest/v1/admin, OUD REST Data Managment at <httpsPort>/rest/v1/directory, and for OUD SCIM Data Management at <httpsPort>/iam/directory/oud/scim/v1.

What Do You Need?

• An environment with at least 16 GB of physical memory, Oracle Enterprise Linux 6.6 or later, and oracle credentials
• A basic understanding of Linux
• Familiarity with the REST architecture style
  
• Oracle Unified Directory 12c
• Native Postman client installed
• The json files OUD_REST_API.postman_collection.json, OUD_Example_Environment.postman_environment.json
• The pwd.txt file contains the Directory Manager's password needed during the OUD setup
• This tutorial assumes that you have already defined the following environment variables:
  • OUD_ORACLE_HOME=/u01/app/oracle/product/oud/oud
  • OUD_INSTANCES=/u01/app/oracle/config/oud_instances

Set Up a Directory Server Instance

In this section, you'll use the oud-setup utility to set up an Oracle Unified Directory server instance.

1. Launch a terminal window as oracle and navigate to the OUD_ORACLE_HOME directory.

   $ cd $OUD_ORACLE_HOME

2. Run the oud-setup command to set up a directory server instance oud_rest with baseDN dc=example,dc=com:

   ./oud-setup --cli \
   --hostname host01.example.com \
   --adminConnectorPort 4444 \
   --httpAdminConnectorPort 8444 \
   --instancePath ../../../config/oud_instances/oud_rest/OUD \
   --rootUserDN "cn=Directory Manager" \
   --rootUserPasswordFile ~/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

   The output should look similar to this:

   Oracle Unified Directory 12.2.1.4.0 Please wait while the setup program initializes...
   Creating instance directory
   /u01/app/oracle/config/oud_instances/oud_rest/OUD..... Done.
   See /u01/app/oracle/config/oud_instances/oud_rest/OUD/logs for a detailed log of this operation.
   Configuring Directory Server ..... Done.
   Configuring Certificates ..... Done.
   Importing Automatically-Generated Data (200 Entries) ....... Done.
   Starting Directory Server ........ Done.
   To see basic server configuration status and configuration you can launch
   /u01/app/oracle/config/oud_instances/oud_rest/OUD/bin/status 

3. Navigate to the $OUD_INSTANCES/oud_rest/OUD/bin directory and run the following command to update the global-aci so users can access directory entries about themselves:

   ./dsconfig set-access-control-handler-prop \
   --hostname host01.example.com \
   --port 4444  \
   --trustAll  \
   --bindDN "cn=Directory Manager"  \
   --bindPasswordFile ~/pwd.txt \
   --add global-aci:'(targetattr!="userPassword||authPassword")(version 3.0; acl "Self read access"; allow (read,search,compare) userdn="ldap:///self";)' \
   --no-prompt

   Note: This is required for running requests in the Postman collection that access the /iam/directory/oud/scim/v1/Me endpoint.
   

Set the Environment Parameters in Postman

1. Open Postman, and click Import.
2. In the Import dialog box, select Import File, choose the OUD_Example_Environment.postman_environment.json , and then click Open.
3. Click Manage Environments .
4. In the Manage Environments dialog box, to the right of the OUD Example Environment, click Duplicate Environment  .
5. Click OUD Example Environment copy, which appears below the original environment.
6. To update the environment variables, enter the following values for Initial Value and Current Value, then click Update and then X:
• Environment Name: OUD Environment for REST API Testing
• HOST: Oracle Unified Directory address for the httpsPort, for example, https://host01.example.com:1081. The port should be set to the same port as passed in the parameter --httpsPort in the oud-setup command.
• USER_LOGIN: cn=Directory Manager
• USER_PW: <password> where <password> is the password defined in the ~/pwd.txt file.
• ADMINHOST: Oracle Unified Directory address for the httpAdminConnector port; for example, https://host01.example.com:8444. The port should be set to the same port as passed in the parameter --httpAdminConnectorPort in the oud-setup command.
• ME_LOGIN: uid=testuser1,ou=People,dc=example,dc=com
• ME_PW: Oracle123





7. Click the Environment drop-down list, and then select the updated environment from the list:
   
   

   

Import the Postman Collection

In this section you will import the OUD Postman collection. The collection contains example REST API's for OUD REST Data Management, OUD SCIM Data management, and OUD REST Administration.

1. To import the OUD REST API Postman collection, on the Postman main page, click Import.
2. In the Import dialog box, select Import File, choose the file OUD_REST_API.postman_collection.json, and then click Import.
   
   The collection should display as follows:

   

Test the REST API's for OUD REST Data Management

In this section you will run some of the requests in the Postman collection for OUD REST Data Management.

Note: To prevent SSL certificate verifcation errors, navigate to File > Settings, and in the General tab set SSL certificate verification to OFF.

1. On the Collections tab, expand OUD REST API Collection, then OUD REST Data Management.
2. Select List Entries (Get all Users from container ou=People). This request makes a GET request to the /rest/v1/directory endpoint, searches the container ou=People,dc=example,dc=com, and lists entries based on attributes=mail.
   

   

3. Click Send.

4. In the response, confirm that the Status: 200 OK appears and that the response body displays details about the users stored in Oracle Unified Directory based on the mail attribute.
   
5. On the Collections tab, under OUD REST Data Management, select Create an Entry. This request makes a POST request to the /rest/v1/directory endpoint, and creates a user testuser1 based on the information in the body:
   

   

6. Click Send.
7. In the response, confirm that the Status: 201 Created appears and that the response body displays details about the user created.
8. Test other OUD REST Data Management API calls as required. Note: If you run Delete Entry to remove testuser1, create the user again using Create an Entry, as testuser1 is used in the next section.

Test the REST API's for OUD SCIM Data Management

In this section you will run some of the requests in the Postman collection for OUD SCIM Data Management.

1. On the Collections tab, expand OUD SCIM Data Management.
2. Select List Users. This request makes a GET request to the /iam/directory/oud/scim/v1/Users endpoint and searches for all users.
   

   

3. Click Send.
4. In the response, confirm that the Status: 200 OK appears and that the response body displays details about the users stored in Oracle Unified Directory.
5. On the Collections tab, under OUD SCIM Data Management, select Me. This request makes a GET request to the /iam/directory/oud/scim/v1/Me endpoint to fetch details about the end user defined in the Authorization tab. In this case the variables {{ME_LOGIN}} and {{ME_PW}} which correspond to uid=testuser1,ou=People,dc=example,dc=com/Oracle123 as defined in section Set the Environment Parameters in Postman:
   

   

6. Click Send.
7. In the response, confirm that the Status: 200 OK appears and that the response body displays details about the user.
8. Test other OUD REST Data Management API calls as required.
   

Test the REST API's for OUD REST Administration

In this section you will run some of the requests in the Postman collection for OUD REST Administraton.

1. On the Collections tab, expand OUD REST Administration.
2. Select Get Server Instance Details. This request makes a GET request to the /rest/v1/admin endpoint, and searches for details of the OUD server instance:
   

   

3. Click Send.
4. In the response, confirm that the status 200 OK appears and that the response body displays details about the server instance.
5. In the Collections tab, under OUD REST Administration, select Create Extension. This request makes a POST request to the /rest/v1/admin endpoint and creates an LDAP extension ldap-extn-1 as defined in the body:
   

   

6. Click Send.
7. In the response, confirm that the status 201 Created appears and that the response body displays details about the LDAP extension created.
8. Test other OUD REST Administration API calls as required.

Want to Learn More?

REST API for Oracle Unified Directory Administration
REST API for Oracle Unified Directory Data Management
SCIM REST API for Oracle Unified Directory

Feedback

To provide feedback on this tutorial, please contact Identity Management User Assistance.