1. Administering Oracle Unified Directory
  2. REST Interfaces
  3. Managing OUD Directory Data with SCIM REST API

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

  1. Run the dsconfig command-line utility with create-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 the dsconfig command-line utility with the set-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
  2. Configure the REST endpoints as follows:
    1. 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
    2. 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
  3. 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"
    }
  ]
}
The following response body is generated when you create an entry with above mentioned 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 "
        }
    ],
    "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.

To modify an entry through SCIM interface, send a request to URI /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" ]
    }
  ]
}
The following response body is generated when you modify an entry with above mentioned 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": " 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"
        }
    ]
}