REST (ADAP)

The REST interface supports all LDAP operations and the ability to navigate the directory tree. Wrapping these operations and the progressive disclosure capabilities that exist in LDAP directories into a REST interface opens it up to the web. The REST API in RadiantOne is referred to as ADAP (Adaptive Directory Access Protocol).

This section describes how to perform the following functions:

• Authenticate

• Search

• Display an LDAP server’s root naming contexts

• Add

• Replace

• Modify

• Modify RDN

• Move

• Delete

• Perform Bulk Operations

• Working with Complex Attributes

Accessing the RadiantOne RESTFul Web Service

You can access the RadiantOne RESTFul Web Service using the following URL syntax:

http://<RadiantOneService>:8089/adap/<baseDN>

When a REST client performs an operation, it displays one or more codes in its Response section. One of these codes is an HTTP status. (In the Response section of the REST client, look for the numeric value that follows ). The following table describes these HTTP status codes.

This is the number of threads the REST/ADAP interface uses for handling client requests. In other words, this option defines the number of requests REST/ADAP can handle. The default value is 100.

To set the maximum threads value:

1. From the RadiantOne Main Control Panel, go to the Settings tab > Server Front End section > Other Protocols sub-section.

2. On the right side, under the REST/ADAP header, enter a value in the Max Thread field.

Figure 1: Max Thread/requests for REST Clients

1. Click the Save button in the upper right corner.

2. Restart the RadiantOne service. If deployed in a cluster, restart it on all nodes.

Authorization is enforced by the RadiantOne service based on the user who authenticated. The authorization ID (DN) is linked to the authenticated ID (DN) for the same connection. If the Proxy Authorization Control is enabled, the client can switch the user ID for authorization purposes, without having to re-authenticate with a new connection. To use proxy authorization in the REST/ADAP request, define a header named Proxy which contains the value of the user ID (DN) for which authorization should be enforced. An example is shown below where requests are performed on behalf of the user identified by: uid=Adalberto_Flecha,ou=Accounting,o=companydirectory

Figure 2: Proxy Header for Proxy Authorization

Ensure the proxy authorization control is enabled for the RadantOne service and access controls have been defined to indicate who is allowed to impersonate who. For more information on enabling the proxy authorization control and defining access controls, please see the RadiantOne System Administration Guide.

This section discusses password authentication and token authentication.

Basic Password Authentication

All REST operations require a header which is used to bind to the LDAP server. If this header is not populated, it uses anonymous access.

The header must be named “authorization” and the header value is derived by concatenating: Basic base64(dn:password). Use a <space> between Basic and the encoded value.

You can use any base64 encoder to get this value. For example, the base64 encoded value for cn=directory manager and password of secretsecret would be the following.

Y249ZGlyZWN0b3J5IG1hbmFnZXI6c2VjcmV0c2VjcmV0

Resulting in a header of:
<header key="authorization" value="Basic Y249ZGlyZWN0b3J5IG1hbmFnZXI6c2VjcmV0c2VjcmV0"/>

Figure 3: Header used for Basic Authentication

In this section, a simple bind to the RadiantOne REST service is shown in the table below.

Table 1: A Simple Bind to the RadiantOne REST Service

An authentication attempt with the above parameters results in the message {“httpStatus”:200}. This means the credentials check was successful.

Figure 4: Connection Successful

An unsuccessful authentication attempt may result in the status ”401: Unauthorized”.

Figure 5: Connection Failed

Unless otherwise stated, this document assumes the use of password authentication.

Always Authenticate - Avoid Connection Pooling

By default, the REST/ADAP service leverages connection pooling when connecting to the RadiantOne service. To require a new authentication (bind) for every connection to RadiantOne, and not use connection pooling, the Always Authenticate option must be enabled in the REST/ADAP configuration. If Always Authenticate is enabled, there is a single bind to the RadiantOne service for every bind to ADAP and a single bind to with every search to ADAP.

When Always Authenticate is not enabled (which is the default), connection pooling is used. There is a single bind to RadiantOne for every search if the connection is not in the pool, and no bind if the connection is in the pool.

To enable the Always Authenticate option:

1. Go to the Main Control Panel > Settings tab > Server Front End > Other Protocols section.

2. In the REST/ADAP section (requires Expert Mode), check the ‘Always Authenticate’ checkbox.

Figure 6: Enabling the Always Authenticate Option

1. Click Save.

2. Restart the RadiantOne service. If deployed in a cluster, restart the service on all nodes.

OpenID Connect Token Authentication

The RadiantOne REST (ADAP) interface supports token authentication. An OIDC token is recommended and described later on in this section. However, RadiantOne also includes a proprietary token mechanism that can be used if you don't have an OIDC provider. To generate a proprietary token, pass the userDN and password in the Authorization header in a GET request to the following endpoint: https://r1server:8090/adap?bind=token

Table 2: Generating a proprietary token

Figure 7: Header used for Token Authentication

The REST client displays the token value like in the example shown below.

Figure 8: The REST client displays the issued token

Record the token value and use it in the authorization header field (instead of user name and password) for subsequent ADAP requests. An example is shown in the table below.

Table 3: OpenID Connect token authentication

The RadiantOne REST (ADAP) interface supports OpenID Connect token-based authentication. This option provides the security of sending user login credentials to the authentication server, not the application (ADAP). OpenID Connect token authentication allows you to send your username and password just once and then pass the token in the request to ADAP. However, the user cannot use the token authentication to request a new token. Multiple requests can be performed during a token’s lifetime.

A high-level diagram of the different components is shown below. Postman is used as a simple client to illustrate the flow.

Figure 9: OpenID Connect Token Authentication

Authorization Server Configuration

The application’s parameters must be configured on the authorization server that will issue the OpenID Connect tokens. The application in this context is the ADAP service. Configure an application for the ADAP service in your OIDC server and note the client ID and secret that are generated for it.

RadiantOne Configuration

The client/application settings configured in the previous section must be added to the RadiantOne configuration for ADAP to use. The following configuration can be performed on the Main Control Panel.

1. In the Main Control Panel, click the Zookeeper tab (requires Expert Mode).

2. Browse to radiantone/<version>/<cluster_name>/config/vds_server.conf.

3. Click Edit Mode.

4. Set the value for “oidcClientId” to the value recorded in the Client ID field in the previous section.

5. Set the value for “oidcDiscoveryUrl” to the URL of the OpenID Connect Server.

6. Set the value for “oidcClientSecret” to the client secret that was recorded in the previous section.

7. Set the value for "oidcIdAttr" to “sub” (or some other claim based on the scopes configured for the client). This attribute indicates what information/claims ("sub" indicates Subject) in the token (based on scopes requested) can be used to identify the relevant account in the RadiantOne namespace for enforcing authorization on subsequent requests for this connection. The value of this attribute is used as input for the User to DN mapping configured later in the steps below. The standard claims associated with the scopes are shown in the table below.

Table 4: Standard Claims per Scope

1. Click the Save button on the ZooKeeper tab.

2. Click OK.

Figure 10: Configuring the OIDC parameters in RadiantOne

1. (Optional) If you plan on using Proxy Authorization, go to Main Control Panel > Settings > Server Front End > Supported Controls. Check the option to enable the Proxy Authorization Control and click Save.

2. (Optional) If you plan on using Proxy Authorization, go to the Main Control Panel > Settings > Security > Access Controls and define the access control instructions for the proxy users. See the RadiantOne System Administration guide for assistance.

3. To configure mapping rules to associate the token identity to an identity in the RadiantOne namespace (for enforcing authorization), go to the Main Control Panel > Settings > Interception > User to DN Mapping.

4. Click Add and define the rule(s) that will translate the identity from the OpenID Connect token to the identity in the RadiantOne namespace. For example, if a user authenticates to the OpenID connect server (to request a token) as Aaron_Medler, this value is issued as the identifier subject in the token and must be translated into an identity DN in the RadiantOne namespace when requests are sent. Assuming “Aaron_Medler” is the value in the uid attribute and this account is located in the o=companydirectory naming context, the mapping rule shown below would be needed to translate “Aaron_Melder” into the identity represented as: “uid=Aaron_Medler,ou=Accounting,o=companydirectory”

Figure 11: Example User to DN Mapping

1. Click Save.

Obtaining an OpenID Connect Token

In the context of this guide, Postman is the REST client that will issue calls to ADAP. Obtain an OpenID Connect Token for Postman from your OIDC provider. Use the token value in a header configured in your Postman client as follows.

Table 5: Passing an OpenID Connect Token in a Header

Figure 12: Passing an OpenID Connect Token in a Header

If successful, the operation displays results similar to the following.

Figure 13: Successful REST Operation using OpenID Connect Token

Token Lifetime

By default the token lifetime is set to 10 hours. To configure the token timeout:

1. Go to the Main Control Panel > Settings tab > Server Front End > Other Protocols section.

2. In the REST/ADAP sectoin (requires Expert Mode), edit the value in the Token Timeout field.

3. Click Save.

4. Restart the RadiantOne service. If deployed in a cluster, restart the service on all nodes.

Figure 14: Editing the Token Timeout value

When an expired or unrecognized token is used, the Response section displays the message “Authentication failed: Unknown token”.

Figure 15: Error Related to Unrecognized or Expired Token

Examples

The examples below describe how to issue REST queries for search, insert, update, and delete operations.

Search

In this section, a search is performed using the REST client parameters and values shown in the table below.

Table 6: Search Operation

Figure 16: Search Operation

Figure 17: Example Search Results

Optional Search Parameters

You can use the following search parameters: filter, attributes, scope, startIndex, count, sizelimit, paging, context, context filter, return mode, special character encoding, and derefAliases. The & sign is the parameter delimiter in the URL. These options are described in this section.

LDAP Filter -> Corrected URL
(&(objectclass=)(cn=a)) -> (%26(objectclass=)(cn=a))

Filter

The filter option allows you to search for entries with a specific attribute value. The value defined for this option is translated into an LDAP filter when the query is issued to the RadiantOne LDAP service. In the following example, a search is performed for records with the value Manager for the employeeType attribute within o=companydirectory.

Table 7: Search Operation with Filter Attributes

An example is shown below.

Figure 18: Search Results with Filter Attributes

By default, all attributes associated with the matching entries are returned. The attributes option allows you to indicate which attributes you want returned in the search result. Separate attribute names with a comma in the URL. The value defined for this option is translated into requested attributes in the LDAP query issued to the RadiantOne service. The example shown below expects the objectclass and cn attributes returned for each entry.

Table 8: Search Operation Returning ObjectClass and CN

Scope

This option defines how many levels beneath the base DN to search for entries. The value defined for this option is translated into the scope for the LDAP query issued to the RadiantOne service. The options include the following.

• Base (the base DN only)

• One (the level beneath the base DN only)

• Sub (all levels beneath the base DN)

Table 9: Search Operation with Scope Parameter

StartIndex (Paging Results)

This option defines the number used for the paged search, and indicates the first entry to return from all the matched entries. This option should be used in conjunction with the ‘count’ option described in the next section. StartIndex dictates the behavior at the client level and is not passed to the RadiantOne service in the LDAP query.  

Table 10: Search Operation using StartIndex Parameter

Count

This option should be passed with StartIndex (described above) and defines the number of successive entries displayed in a paged search, starting with the one previously defined using the StartIndex search parameter. Count dictates the behavior at the client level and is not passed to the RadiantOne service in the LDAP query.

For example, to return the attribute “cn” for entries number 101 and 102 located under o=companydirectory, the configuration is indicated in the following table.

Table 11: Search Operation using Count Parameter

An example is shown below.

Figure 19: Search Results with Count

The ‘totalResults’ field displays one of the following values. The following table explains each of these values.

Table 12: Total Results Descriptions

The “count” value represents the number of results actually returned in the response and was set when “count=2” was added to the URL in the example above. Otherwise, the count value would have been equal to the total number of entries returned without the use of paging.

SizeLimit

SizeLimit indicates the maximum number of entries to request from the RadiantOne service. The value defined for this option is translated into the sizelimit property passed in the LDAP query to RadiantOne. The default sizelimit is set at 1000, meaning that only 1000 entries will be returned by the RadiantOne LDAP sevice for a request. If the REST client is expecting all entries, sizelimit should be set to 0.

In the example used for the “count” parameter described previously, the query to return the attribute “cn” for entries number 101 and 102 located under o=companydirectory is:

http://localhost:8080/webservices/o=companydirectory?attributes=cn&startIndex=101&count=2

However, even if the REST interface only returns entries 101 and 102, it requests all entries from the RadiantOne LDAP service. Then, post filtering is performed using the values for the “startIndex” and “count” parameters.

A more efficient way to get entries 101 and 102 is by using SizeLimit. SizeLimit could be set to the maximum number of entries required in order to retrieve the desired 101 and 102. This example is shown in the table below.

Table 13: Search Operation using SizeLimit Parameter

Paging

The PageSize option indicates paging via the Paged Results Control should be passed in the query to the RadiantOne LDAP service. The PageSize value entered when passing the initial search defines the number of entries displayed per page. This reduces the initial loading time and memory requirement when performing a search, making this option especially useful when the total search result count is high.

For REST access, the paging functionality leverages a session cookie which is linked to the original LDAP connection. Since this requires the same connection/session to work properly, paging through the REST interface does not work against a RadiantOne cluster deployment because subsequent requests could be directed to a RadiantOne node that is not associated with the original session cookie. If paging is required for cluster deployments, it is recommended to use source address affinity persistence in your load balancer.

Figure 20: Enabling Paged Results

Figure 21: Configuring Cookie Timeout

If you try to use the PageSize option without paging enabled in RadiantOne, the REST interface ignores paging and performs a non-paged search against RadiantOne with SizeLimit equal to the PageSize parameter.

A search displaying, for example, five results per page is started using the parameters shown in the table below.

Table 14: Search Operation using PageSize Parameter

Figure 22: Example Paged Search Results

The totalResults’ field displays one of three values. The following table explains each of these values.

Table 15: TotalResults Values

The next page of search results is displayed using the parameters shown in the table below. In this example, the value for the second search parameter, cookie, is derived from the value in the cookie field in the search results displayed above.

Table 16: Search Operation using Cookie Parameter

A paged search stops automatically after five minutes of inactivity, or it can be stopped manually using the parameters shown in the table below.

Table 17: Manually Stopping a paged search

Context

The context option allows you to display a hierarchical view of an entry’s ancestor(s) when performing a search. By adding “context=true” to the URL of a standard REST search operation, you activate this context search option. Optional search parameters that can be used in conjunction with a context search include filter, scope, and sizelimit.

Table 18: Example Response for Context Search

Figure 23: Performing a Context Search

In the figure above, starting at the bottom, the bottom box contains the uid that matches the search criteria defined in the URL. The next box up contains the parent entry that uid=Aaron Medler belongs to, ou=Accounting. The top box contains the top entry, o=companydirectory.

Context Filter

The context filter option allows you to pass a filtered search to the REST interface, which returns only the entries that match each of the search criteria filters. Wildcards can be used in the filters, as shown in the Example URL field below. The optional search parameters ‘attributes’ and ‘context’ can also be used with this search option. You can define the scope of each context filter search as follows.

/ sets a filter’s scope to one level

// sets a filter’s scope to the entire subtree

Table 19: Search Operation using Context Filter

Figure 24: Example Search Result Leveraging Context Filter

Return Mode

This option allows you to parse search results so they can be more easily interpreted by applications. By adding “?returnMode=array” to the URL of a standard search operation, you activate this option. With this option, attribute values are arranged in an array, regardless of the quantity of attribute values. Without this option, attribute values are arranged in an array only if there are two or more attribute values.

Table 20: Return Mode

Special Character Encoding

To pass an LDAP filter in the request, or any filter that contains special characters, encode the characters as outlined in the table below.

Table 21: Special Character Encoding

An example LDAP filter of: (|(cn=Lisa Grady)(sAMAccountName=Lisa Grady)(uid=Lisa Grady))
Would need converted to:
(%7C(cn%3DLisa%20Grady)(sAMAccountName%3DLisa%20Grady)(uid%3DLisa%20Grady))

Dereferencing Alias Entries

RadiantOne Universal Directory stores supports alias entries as defined in RFC 22521. Alias entries point to/reference another entry in the directory. The attribute containing the location of the target entry (DN) is aliasedObjectName and the object class associated with these entries is alias. When a client requests an alias entry, they can indicate if they want the alias dereferenced or not. The indicators are outlined in the table below.

Table 22: Dereferencing Alias Entries

The default behavior of the REST/ADAP service is to never dereference aliases. If the REST client wants an alias entry dereferenced, they must pass the search parameter derefaliases as described below.

Table 23: Passing the derefealiases parameter

When a client requests derefAliases=3, RadiantOne automatically dereferences the alias entry and returns the entry it points to. In this example, the search dereferences “ou=Headquarters,o=companydirectory”, which is an alias entry, and returns “ou=Information Technology,o=companydirectory” as shown below.

Figure 25: Example Result Dereferencing Aliases

Display LDAP server’s root naming contexts

To display a list of the LDAP server’s root naming contexts, pass rootdse as part of the URL.

Table 24: Displaying LDAP Server's Root Naming Contexts

An example of the list displayed by this command is shown below.

Figure 26: Example Search Returning Root Naming Contexts

Add

In this section, a new entry is added to RadiantOne using the parameters shown in the table below. The value in the Request Body field contains the information for the entry to be added.

{ "params" : { 
"dn" : "uid=alice,cn=config", 
"attributes" : { "objectClass" : [ "top", 
"person", 
"organizationalPerson", 
"inetOrgPerson" ], 
"cn" : "Alice Wonderland", 
"sn" : "Wonderland", 
"uid" : "alice" } } 
}

Table 25: Add Operation

Figure 27: Add Request Example

If successful, the Response section displays the message “{"httpStatus":200}”.

If unsuccessful, the Response section displays the message “{"httpStatus":400}”, as well as additional information about the request’s failure.

Figure 28: Add Failure Response Example

Replace (PUT)

In this section, an existing entry is replaced using the parameters shown in the table below.

Table 26: Replacing an Entry

Figure 29: Example PUT Request

If successful, the Response section displays the message “{"httpStatus":200}”.

Modify (PATCH)

This section explains how to add, delete, and replace an entry’s attributes and includes many examples.

Add and Replace Attributes

In the first example, an attribute is added to a user entry identified as “uid=alice,cn=config”, and another is replaced using the parameters shown in the table below.

Table 27: Adding and Replacing Attributes

Figure 30: Example PATCH Request

If successful, the Response section displays the message “{"httpStatus":200}”.

Delete Attribute Value

In this example an attribute (e.g. email) containing a specified value (e.g. [email protected]) is deleted by using the parameters shown in the table below.

{
    "params": {
        "mods": [
            {
                "attribute": "email",
                "type": "DELETE",
                "values": [[email protected]]
            }
        ]
    }
}

Table 28: REST Operation to Delete an Attribute Value

If successful, the Response section displays the message “{"httpStatus":200}”.

Delete Attribute

In this example, an attribute is deleted, regardless of its attribute values, using the parameters shown in the table below. This is an example of removing all values for the email attribute.

{
    "params": {
        "mods": [
            {
                "attribute": "email",
                "type": "DELETE",
                "values": []
            }
        ]
    }
}

Table 29: REST Operation to Delete an Attribute

If successful, the Response section displays the message “{"httpStatus":200}”.

Add Group Member

In this example, a group entry identified as “cn=operator,ou=globalgroups,cn=config” is updated to add a member identified as “uid=Adalberto_Flecha,ou=Accounting,o=companydirectory”.

	{
  "params": {
    "mods": [
      {
        "attribute": "uniquemember",
        "type": "ADD",
        "values": [
          "uid=Adalberto_Flecha,ou=Accounting,o=companydirectory"
        ]
      }
    ]
  }
}

Table 30: REST Operation to add group members

Figure 31: Example PATCH Request – Add Group Members

If successful, the Response section displays the message “{"httpStatus":200}”.

Replace Group Members

In this example, a group entry’s members are replaced by a new member.

{
  "params": {
    "mods": [
      {
        "attribute": "uniquemember",
        "type": "REPLACE",
        "values": [
          "uid=Adele_Kucan,ou=Accounting,o=companydirectory"
        ]
      }
    ]
  }
}

Table 31: REST operation to replace group members

Figure 32: Example PATCH Request – Replace Group Members

If successful, the Response section displays the message “{"httpStatus":200}”.

Modify RDN

This section explains how to modify the RDN of an entry using the parameters shown in the table below.

Table 32: REST Operation to modify an entry's RDN

Figure 33: Example PATCH – Modify RDN

If successful, the Response section displays the message “{"httpStatus":200}”.

Move

This section explains how to move the entry "uid=Adalberto_Flecha,ou=Accounting,o=companydirectory" to "ou=Administration,o=companydirectory", keeping the same RDN name.

Table 33: REST Operation to move an entry

Figure 34: Example PATCH – Move Entry

If successful, the Response section displays the message “{"httpStatus":200}”.

Delete

This section explains how to delete an entry in RadiantOne using the parameters shown in the table below. “baseDN” is the DN of the targeted entry.

Table 34: REST Operation to delete an entry

Figure 35: Example DELETE Request

If successful, the Response section displays the message “{"httpStatus":200}”.

Deleting a Node and Its Sub-Nodes

This section explains how to delete a node and its sub-nodes. When attempting to perform a standard deletion on a node that contains sub-nodes, the operation fails because of those sub-nodes. The Response section displays the message “Entry not deleted”.

Figure 36: Failure to Delete Entry Containing Sub-nodes

To delete a node that contains sub-nodes, perform a deletion using the parameters shown in the table below. “baseDN” is the DN of the targeted entry.

Table 35: REST Operation to Delete a Node Containing Sub-nodes

Figure 37: Deleting a Node Containing Sub-nodes

Performing Bulk Operations

Performing large quantities of REST requests may affect your network’s workload. This section explains how to perform bulk operations, which bundle multiple operations into one REST request, reducing your network’s workload. In the example below, the following are performed inside of one operation:

• A new entry is added to the directory

• A node (and its sub-nodes) is deleted

• An existing directory entry is replaced

• An entry’s attribute is modified

• An entry is deleted from the directory

A bulk operation contains unique fields in its syntax. The “method” field indicates the type of REST operation performed, and the “dn” field indicates the DN of the entry the operation applies to.

{
  "Operations": [
    {
      "method": "POST",
      "dn": "uid=alice,cn=config",
      "params": {
        "attributes": {
          "objectClass": [
            "top",
            "person",
            "organizationalPerson",
            "inetOrgPerson"
          ],
          "cn": "Alice Wonderland",
          "sn": "Wonderland",
          "uid": "alice"
        }
      }
    },
    {
      "method": "PUT",
      "dn": "uid=Adalberto_Karoly,ou=Accounting,o=companydirectory",
      "params": {
        "attributes": {
          "objectClass": [
            "top",
            "person",
            "organizationalPerson",
            "inetOrgPerson"
          ],
          "cn": "Alice Wonderland2",
          "sn": "Wonderland2",
          "uid": "alice"
        }
      }
    },
    {
      "method": "PATCH",
      "dn": "uid=Aaron_Medler,ou=Accounting,o=companydirectory",
      "params": {
        "mods": [
          {
            "attribute": "telephoneNumber",
            "type": "ADD",
            "values": [
              "911"
            ]
          }
        ]
      }
    },
    {
      "method": "DELETE",
      "dn": "uid=Adan_Organista,ou=Accounting,o=companydirectory"
    }
  ]
}

Table 36: REST Operation to Perform Bulk Operation

Figure 38: Sample Response from Bulk Operations

In the image above, starting at the top, in the top box, the addition of a new entry to the directory is confirmed. In the second box, the replacement of an existing directory entry is confirmed. In the third box, the modification of an entry’s attribute is confirmed. In the fourth box, the deletion of an entry is confirmed.

Delete Nodes and Their Sub-Nodes

This section explains how to delete nodes and their sub-nodes. When attempting to perform a standard deletion on a node that contains sub-nodes, the operation fails because of those sub-nodes. The value in the Example Request Body field below contains the information needed to delete the nodes.

 {
    "params": [
        {
            "method": "DELETE",
            "dn": "ou=Human Resources,o=companydirectory",
            "deletetree": true
        },
        {
            "method": "DELETE",
            "dn": "ou=Information Technology,o=companydirectory",
            "deletetree": false
        },
        {
            "method": "DELETE",
            "dn": "ou=Inventory,o=companydirectory",
            "deletetree": true
        }
    ]
}

Table 37: REST Bulk Operation to Delete Nodes and Their Sub-nodes

Figure 39: Sample Response from Bulk Deletion of Nodes and Their Sub-Nodes

In the image above, starting at the top, in the top box, the deletion of this node is confirmed. In the second box, this node was not deleted because deletetree it had a value of false in the body of the request. In the third box, the deletion of this node is confirmed.

Working with Complex Attributes

Complex attributes are those that contain one or more sub-attributes. With the REST interface, you can search for and modify “complex” attributes. Complex attributes are not compatible with bulk operations.

This section explains how to perform the following operations.

Search for complex attributes

Add an entry with complex attributes

Add complex attributes to an existing entry

Replace an entry’s complex attributes

Delete an entry’s complex attributes

Modify multiple complex attributes in an operation

Search for Complex Attributes

The complex attribute search allows you to indicate which attributes you want returned in the search result. Separate attribute names with a comma in the URL. The value defined for this option is translated into requested attributes in the LDAP query issued to RadiantOne. The example shown below expects the attribute address and its sub-attributes returned for each entry.

Table 37: REST Operation Searching for Complex Attributes

An example complex attribute search result is shown in the image below.

Figure 40: Example Complex Attribute Search Results

When using a complex attribute in a filter, you can search for entries with a specific sub-attribute value. The value defined for this option is translated into an LDAP filter when the query is issued to RadiantOne. In the following example, a search is performed for records with the value NY for the “state” sub-attribute within cn=config.

Table 39: Complex Attribute Search Using a Filter

An example complex attribute search result is shown in the image below.

Figure 41: Complex Attribute Search Result with Specified Sub-attributes

Add an Entry with Complex Attributes

In this section, an entry with complex attributes is added using the parameters shown in the table below. The value in the Example Request Body field contains the information for the entry to be added. The “phone” attribute contains the sub-attributes “type” and “value”, and the “address” attribute contains the sub-attributes “state”, “country”, and “streetNumber”.

{
    "params": {
        "dn": "uid=alice,cn=config",
        "attributes": {
            "objectClass": [
                "top",
                "person",
                "organizationalPerson",
                "inetOrgPerson"
            ],
            "cn": "Alice Wonderland",
            "sn": "Wonderland",
            "uid": "alice",
            "phone": {
                "type": "home",
                "value": "123"
            },
            "address": [
                {
                    "state": "NY",
                    "country": "US",
                    "streetNumber": "35"
                },
                {
                    "country": "france",
                    "state": "ain"
                }
            ]
        }
    }
}

Table 40: Adding an entry with complex attributes

Figure 42: Adding an entry with complex attributes

Add Complex Attributes to an Existing Entry

In this section, complex attributes are added to an existing user entry using the parameters shown in the table below. The value in the Example Request Body field contains the information for the attributes to be added to the entry.

{
    "params": {
        "mods": [
            {
                "attribute": "phone",
                "type": "ADD",
                "values": [
                    {
                        "type": "home",
                        "value": "456"
                    },
                    {
                        "type": "mobile",
                        "value": "111"
                    }
                ]
            }
        ]
    }
}

Table 41: Adding Complex Attributes to an Existing Entry

If you attempt to add an attribute that has an already existing, identical value, the REST client displays LDAP code 20 (the provided attribute contains a value that would result in duplicate value in the entry). If this happens, the entire request is ignored by the REST client.

Replace an Entry’s Complex Attributes

In this section, new attributes are added to an existing user entry using the parameters shown in the table below. The value in the Example Request Body field contains the information for the attributes to be added to the entry.

{
    "params": {
        "mods": [
            {
                "attribute": "phone",
                "type": "REPLACE",
                "values": [
                    {
                        "type": "work",
                        "value": "123"
                    },
                    {
                        "type": "work",
                        "value": "456",
                        "brand": "orange"
                    }
                ]
            }
        ]
    }
}

Table 42: Replacing an Entry’s Complex Attributes

Delete an Entry’s Complex Attributes

In this section, sub-attributes are deleted from an existing entry using the parameters shown in the table below. The value in the Example Request Body field contains the information for the sub-attributes to be deleted from the entry.

{
    "params": {
        "mods": [
            {
                "attribute": "phone",
                "type": "DELETE",
                "values": [
                    {
                        "type": "home",
                        "value": "123"
                    }
                ]
            }
        ]
    }
}

Table 43: Deleting an Entry’s Complex Attributes

In the following example, all values for the attribute “address” are deleted using the parameters in the table below. The value in the Example Request Body field contains the information for the sub-attributes to be deleted from the entry.

{
    "params": {
        "mods": [
            {
                "attribute": "address",
                "type": "DELETE",
                "values": [
                    {}
                ]
            }
        ]
    }
}

Table 44: Deleting Sub-attributes

Modify Multiple Complex Attributes in an Operation

In this section, the sub-attributes “streetNumber” and “country” are added to an existing user entry and sub-attributes “type”, “value”, and “brand” are replaced using the parameters shown in the table below. The value in the Example Request Body field contains the information for the attributes to be modified in the entry.

{
    "params": {
        "mods": [
            {
                "attribute": "phone",
                "type": "REPLACE",
                "values": [
                    {
                        "type": "work",
                        "value": "123"
                    },
                    {
                        "type": "work",
                        "value": "456",
                        "brand": "orange"
                    }
                ]
            },
            {
                "attribute": "address",
                "type": "ADD",
                "values": [
                    {
                        "streetNumber": "123",
                        "country": "US"
                    }
                ]
            }
        ]
    }
}

Table 45: Modifying Multiple Complex Attributes in an Operation