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.
- Launch a terminal window as
oracle
and navigate to theOUD_ORACLE_HOME
directory.$ cd $OUD_ORACLE_HOME
- Run the
oud-setup
command to set up a directory server instanceoud_rest
with baseDNdc=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 - Navigate to the
$OUD_INSTANCES/oud_rest/OUD/bin
directory and run the following command to update theglobal-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
- Open Postman, and click Import.
- In the Import dialog box, select Import File, choose the OUD_Example_Environment.postman_environment.json , and then click Open.
- Click Manage Environments .
- In the Manage Environments dialog box, to the right of the OUD Example Environment, click Duplicate Environment .
- Click OUD Example Environment copy, which appears below the original environment.
- 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
- 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.
- To import the OUD REST API Postman collection, on the Postman main page, click Import.
- 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.
- On the Collections tab, expand OUD REST API Collection, then OUD REST Data Management.
- Select List Entries (Get all Users from container ou=People). This request makes a GET request to the
/rest/v1/directory
endpoint, searches the containerou=People,dc=example,dc=com,
and lists entries based onattributes=mail
.
- Click Send.
- 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.
- 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 usertestuser1
based on the information in the body:
- Click Send.
- In the response, confirm that the
Status: 201 Created
appears and that the response body displays details about the user created. - 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.
- On the Collections tab, expand OUD SCIM Data Management.
- Select List Users. This request makes a
GET
request to the/iam/directory/oud/scim/v1/Users
endpoint and searches for all users.
- Click Send.
- 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. - 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 touid=testuser1,ou=People,dc=example,dc=com/Oracle123
as defined in section Set the Environment Parameters in Postman:
- Click Send.
- In the response, confirm that the
Status: 200 OK
appears and that the response body displays details about the user. - 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.
- On the Collections tab, expand OUD REST Administration.
- 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:
- Click Send.
- In the response, confirm that the status
200 OK
appears and that the response body displays details about the server instance. - 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 extensionldap-extn-1
as defined in the body:
- Click Send.
- In the response, confirm that the status
201 Created
appears and that the response body displays details about the LDAP extension created. - 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.