How To
ForgeRock Identity Platform
Does not apply to Identity Cloud

How do I update LDAP user attributes using the REST API in AM (All versions)?

Last updated Feb 24, 2021

The purpose of this article is to provide information on updating LDAP user attributes using the REST API in AM.


4 readers recommend this article

Caution

AM is not designed to be a fully featured user administration tool; the user functionality is intended to be used for validating connectivity to your identity repository. You should use a dedicated tool for managing users such as IDM or DS, depending on your use case.

Overview

LDAP user attributes such as username and email address are already accessible via the REST API. If you want to update user attributes that are not accessible via the REST API (such as custom attributes), you will need to add them to the data store configuration in AM first:

  1. Adding user attribute to the data store configuration
  2. Updating user attribute using the REST API
Note

You must ensure that the user attribute already exists in your LDAP data store and exists as an allowed attribute in an objectclass in your data store; see Setup Guide › Adding User Profile Attributes for further information. Additionally, you must add it to the same realm as the one in which the users you want to update reside.

Adding user attribute to the data store configuration

You can add a user attribute to the data store configuration using either the console or ssoadm:

  • AM 6 and later console: navigate to: Realms > [Realm Name] > Data Stores > [Data Store Name] > User Configuration and add the user attribute to the LDAP User Attributes list.
  • Pre-AM 6 console: navigate to: Realms > [Realm Name] > Data Stores > [Data Store Name] and add the user attribute to the LDAP User Attributes list.
  • ssoadm: use the following process to append a user attribute to the LDAP User Attributes list:
    1. Output the current data store configuration to a text file: $ ./ssoadm show-datastore -e [realmname] -m [datastorename] -u [adminID] -f [passwordfile] > datastoreconfig.txtreplacing [realmname], [datastorename], [adminID] and [passwordfile] with appropriate values.
    2. Remove all other attributes from this text file so you are only left with the sun-idrepo-ldapv3-config-user-attributes ones.
    3. Add the new user attribute to the end of the text file in the following format, where [userAttribute] is the name of your user attribute: sun-idrepo-ldapv3-config-user-attributes=[userAttribute]
    4. Update the LDAP User Attributes list in your data store configuration using the amended text file: $ ./ssoadm update-datastore -e [realmname] -m [datastorename] -u [adminID] -f [passwordfile] -D datastoreconfig.txtreplacing [realmname], [datastorename], [adminID] and [passwordfile] with appropriate values.

Updating user attribute using the REST API

Note

Please observe the following when constructing REST calls:

  • Make the REST call to the actual AM server URL (not lb).
  • Change the name of the iPlanetDirectoryPro header to the name of your actual session cookie.
  • Set this session cookie header to the token returned when you authenticated.
  • Ensure the Accept-API-Version header contains a valid resource version (AM 5 and later).

See How do I avoid common issues with REST calls in AM (All versions)? for further information.

You can update a user attribute using the REST API as follows:

  1. Authenticate as the admin user. For example:$ curl -X POST -H "X-OpenAM-Username: amadmin" -H "X-OpenAM-Password: cangetinam" -H "Content-Type: application/json" -H "Accept-API-Version: resource=2.1" http://host1.example.com:8080/openam/json/realms/root/authenticate?authIndexType=service&authIndexValue=adminconsoleservice Example response:{ "tokenId": "AQIC5wM2LY4SfcxsuvGEjcsppDSFR8H8DYBSouTtz3m64PI.*AAJTSQACMDIAAlNLABQtNTQwMTU3NzgxODI0NzE3OTIwNAEwNDU2NjE0*", "successUrl": "/openam/console", "realm": "/" } 
  2. Update the user attribute. The following example demonstrates updating a user attribute called facsimileTelephoneNumber for the demo user in the employees realm:$ curl -X PUT -H "iPlanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" -H "Content-Type: application/json" -H "Accept-API-Version: resource=3.0,protocol=1.0" -d '{  "facsimileTelephoneNumber":"01179123456"  }' http://host1.example.com:8080/openam/json/realms/root/realms/employees/users/demo Example response:{   "username": "demo",   "realm": "/employees",   "uid": [     "demo"   ],   "mail": [     "demo.star@test.com"   ],   "universalid": [     "id=demo,ou=user,o=employees,ou=services,dc=openam,dc=forgerock,dc=org"   ],   "objectClass": [     "iplanet-am-managed-person",     "inetuser",     "sunFederationManagerDataStore",     "sunFMSAML2NameIdentifier",     "devicePrintProfilesContainer",     "inetorgperson",     "sunIdentityServerLibertyPPService",     "iPlanetPreferences",     "pushDeviceProfilesContainer",     "iplanet-am-user-service",     "forgerock-am-dashboard-service",     "organizationalperson",     "top",     "kbaInfoContainer",     "sunAMAuthAccountLockout",     "person",     "oathDeviceProfilesContainer",     "iplanet-am-auth-configuration-service"   ],   "dn": [     "uid=demo,ou=people,dc=openam,dc=forgerock,dc=org"   ],   "inetUserStatus": [     "Active"   ],   "sn": [     "demoStar"   ],   "facsimileTelephoneNumber": [     "01179123456"   ],   "cn": [     "demo"   ],   "modifyTimestamp": [     "20161004155427Z"   ],   "createTimestamp": [     "20160721105610Z"   ] }

Removing a value

If you want to update a user attribute with a blank value or remove the value for an existing attribute, you should set the value as []. For example, the data element of your REST call would look similar to this:

{"mail": []}

See Also

FAQ: REST API in AM

How do I retrieve user attributes from a session using the REST API in AM (All versions)?

Using the REST API in AM

Data stores in AM

Setup Guide › Identity Management

Getting Started with REST › Specifying Realms in REST API Calls

Allow Users to Update New Attributes 

Related Training

N/A

Related Issue Tracker IDs

OPENAM-5414 (Custom attributes do not appear in XUI end user page)


Copyright and Trademarks Copyright © 2021 ForgeRock, all rights reserved.