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

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

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

See API Specs for complete details.

REST Response Status Codes

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.

Maximum Requests

This is the number of threads the REST/ADAP interface uses for handling client requests. 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

3. Click Save in the upper right corner.

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

Proxy Authorization

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 Access Controls.

Access Controls.

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 (cn=directory manager: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.

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.

For normal SSL communications, where the only requirement is that the client trusts the server, no additional configuration is necessary (as long as both entities trust each other). For mutual authentication, where there is a reciprocal trust relationship between the client and the server, the client must generate a certificate containing his identity and private key in his keystore. The client must also make a version of the certificate containing his identity and public key, which RadiantOne must store in its truststore. In turn, the client needs to trust the server; this is accomplished by importing the server's CA certificate into the client truststore.

Figure 7: Mutual Authentication

The RadiantOne ADAP service receives the client connection request (via HTTPS) and optionally verifies that the certificate is valid and hasn’t been revoked (If CRL checking is enabled). If the certificate is valid, ADAP evaluates the configured client certificate to DN mapping rules to get the target DN (the user identified in the RadiantOne namespace). Then, ADAP connects to the RadiantOne LDAP service via LDAPS and uses the Proxy Authorization Control to request access on behalf of the user identified by the client certificate to DN mapping rule. All subsequent requests from the ADAP client are sent to the RadiantOne LDAP service on behalf of this user and it is this account that authorization is enforced for.

To configure support for mutual authentication to ADAP, follow the steps below.

1. Log into the Main Control Panel as a member of the Directory Administrators group.

2. Go to the Settings tab > Server Front End > Supported Controls and verify Enable Proxy Authorization is checked. If not, enable it and click Save.

3. If you had to enable the Proxy Authorization control, restart the RadiantOne service (on all nodes if you are deployed in a cluster).

4. Go to the Settings tab > Security > Access Control.

5. Verify Allow Directory Manager to impersonate other users is checked. If not, enable it and click Save.

6. Go to the Settings tab > Security > Client Certificate Truststore and verify the client public key certificate has been added to the truststore. You should only need to do this if the client certificate has not been signed by a known/trusted certificate authority. For details on the Client Certificate Trust Store, see the RadiantOne System Administration Guide.

7. Go to the Settings tab > Security > SSL section and verify the Certificate Revocation List checking you want to use (if any) has been enabled/configured. For details on the CRL options available, see the RadiantOne System Administration Guide.

8. In the SSL section, select the desired type of Mutual Authentication you want to support. If mutual authentication is required, choose the Required option. If this option is selected, it forces a mutual authentication. If the client fails to provide a valid certificate which can be trusted by RadiantOne ADAP, authentication fails, and the TCP/IP connection is dropped. If mutual authentication is not required, but you would like the ADAP service to request a certificate from the client, choose the Requested option. In this scenario, if the client provides a valid certificate, a mutual authentication connection is established. If the certificate presented is invalid, the authentication fails. If no certificate is presented, the connection continues, but is not mutual authentication.

9. In the SSL section, click the Change button next to Client Certificate DN Mapping. This is the mapping between the client certificate subject/SAN and the target/mapped DN in the RadiantOne namespace. Authorization is enforced by the RadiantOne service based on the target/mapped DN that is the result of your mapping rules. For details on how to define client certificate DN mapping, see the RadiantOne System Administration Guide.

10. Click Save and restart the RadiantOne service. If RadiantOne is deployed in a cluster, restart the service on all nodes.

There are two types of tokens that can be used for REST/ADAP authentication. Using a token generated by the RadiantOne internal service or using a token generated by an OIDC token provider.

RadiantOne Internal Token Service

RadiantOne includes an internal token service that can be used for generating an ADAP access token. This is generally advised for testing only. For production deployments, using an external OIDC token provider is advised.

Token authentication allows you to send your username and password just once and then pass the token for authentication during subsequent requests. However you are not able to use token authentication to request a new token. Multiple requests can be performed during a token’s lifetime.

In this section, a token is requested from RadiantOne internal service using the REST client parameters and values shown in the table below.

The REST response includes the generated token. An example is shown below.

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.

Token lifetime (timeout) is configurable from Main Control Panel > Settings > Front End Settings > Other Protocols, REST/ADAP section on the right.

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

External token validators allow applications to use an access token to call an API on behalf of itself. The API then responds with the requested data. This section assumes that your OIDC provider is already set up and that you know your client ID and secret to test getting a token.

Getting an Access Token

This section describes using the Postman REST client to obtain an access token.

1. Start a new request.

2. Click the Auth tab.

3. From the Type drop down menu, select OAuth 2.0. The Current Token section displays.

2. In the Configure New Token section, enter the Client ID and client secret.

   Note

   These values were created during the OIDC provider configuration process.

3. Provide the access token URL.

   Note

   This value can be found using the using the metadata URL from the Authorization Server.

4. Click Get New Access Token. The new access token's details are displayed.

5. Copy this token and decode it for the values needed for configuring a mapping between the token contents and a unique identity in the RadiantOne namespace. You can do this at https://jwt.io/.

RadiantOne Configuration

This section describes configuring proxy authorization, configuring an ADAP external token validator, and Claims to FID User Mapping.

Configuring Proxy Authorization

The RadiantOne ADAP service queries the RadiantOne LDAP service using proxy authorization.

To configure proxy authorization:

1. In the Main Control Panel, navigate to Settings > Server Front End > Supported Controls.

2. Enable Proxy Authorization and click Save.

3. Navigate to Settings > Security > Access Control.

4. Enable the “Allow Directory Manager to impersonate other users” option and click Save.

Configuring External Token Validators

To add an external token validator:

1. In the Main Control Panel, navigate to Settings > Security > External Token Validators.
2. Click Add. The New ADAP External Token Validator page displays.

1. Name the external token validator.
2. Toggle the Enable switch to On.
3. Select an OIDC provider from the drop-down menu (if applicable, to assist with populating the Discovery URL syntax). Otherwise, skip this step and enter your own Discovery URL.
4. If the Discovery URL is not loaded automatically, paste the Metadata URI from your OIDC authorization server into the Discovery URL field.
5. Click Discover. The JSON Web Key Set URI auto-populates.
6. Use the Expected Audience from your OIDC provider configuration to populate the Expected Audience field.
7. Enter the expected Scope.This property determines 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 Claims to FID User Mapping configured later in the steps below. The standard claims associated with the scopes are shown in the table below.

1. Other values can be obtained from the decoded access token. See the Getting An Access Token section for more information.

1. Click Edit next to Claims to FID User Mapping. The OIDC to FID User Mappings page displays.
2. Click Add. Use either a Simple DN Expression or a Search Expression to map a uniquely identifying attribute to a corresponding claim value in the token (refer to the Getting An Access Token section for more information). In the following image, a Search Expression is used to map the attribute mail to the claim value email.

1. Click OK.
2. Click OK again to close the OIDC to FID User Mappings window.
3. Click Save.

Querying RadiantOne REST API (ADAP) with a Token

In this example, 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 a Postman client as follows.

1. Request a new access token (see Getting An Access Token).
2. Click Use Token. This inserts an Authorization header that inserts your bearer token.

1. Send the bearer token to the REST (ADAP) endpoint. In this example, a basic search is performed.

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

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

Table 6: Search Operation

Figure 17: Search Operation

Figure 18: Example Search Results

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 19: 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 20: 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 21: Enabling Paged Results

Figure 22: 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 23: 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, the client consumes enough pages to retrieve all of the RadiantOne service’s search results, or it can be stopped manually using pageSize=0 shown in the table below.

Table 17: Manually Stopping a paged search

The absolute number of paged searches that can be supported by the RadiantOne service concurrently is defined in the Max Paged Searches property configured in Main Control Panel > Settings > Server Frontend > Other Protocols, REST/ADAP section. This limit controls how many concurrent active paged searches the RadiantOne service maintains state for. Once this limit is reached, no new paged searches can be processed until one of the existing paged search requests is closed. This limit does not impact clients from paging through the results for searches that have already been started.

Figure 24: Max Concurrent Paged Searches

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 25: 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 26: 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. The options include the following.

• array (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.)

• ldapschema (the RadiantOne server LDAP schema is checked for each attribute. If the attribute schema is single-valued, a JSON String is used. If the attribute schema is multi-valued, a JSON array is used.)

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 24: 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 25: 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

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.

Table 27: Add Operation

Figure 29: 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 30: Add Failure Response Example

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

Table 28: Replacing an Entry

Figure 31: Example PUT Request

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

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 29: Adding and Replacing Attributes

Figure 32: 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.

Table 30: 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.

Table 31: 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”.

Table 32: REST Operation to add group members

Figure 33: 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.

Table 33: REST operation to replace group members

Figure 34: Example PATCH Request – Replace Group Members

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

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

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

Figure 35: Example PATCH – Modify RDN

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

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 35: REST Operation to move an entry

Figure 36: Example PATCH – Move Entry

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

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 36: REST Operation to delete an entry

Figure 37: Example DELETE Request

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

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 38: 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 37: REST Operation to Delete a Node Containing Sub-nodes

Figure 39: Deleing a Node Containing Sub-nodes

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 branch (and any sub-branches) 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.

Table 38: REST Operation to Perform Bulk Operation

Figure 40: 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.

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 40: REST Operation Searching for Complex Attributes

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

Figure 42: 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 41: Complex Attribute Search Using a Filter

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

Figure 43: 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”.

Table 42: Adding an entry with complex attributes

Figure 44: 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.

Table 43: 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.

Table 44: 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.

Table 45: 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.

Table 46: 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.

Table 47: Modifying Multiple Complex Attributes in an Operation