Using the REST API in AM/OpenAM

This book provides information on using the REST API in AM/OpenAM and includes known issues (including solutions).


How do I know which endpoint to use for REST calls in newer versions of AM/OpenAM?

The purpose of this article is to provide a single point of reference for evolving REST endpoints; you can use it to determine which endpoints should be used for REST calls in newer versions of AM/OpenAM, where known endpoints (such as /identities/attributes) have been deprecated or removed in later versions of AM/OpenAM. Deprecated endpoints are not supported and you should move to the replacement endpoints at your earliest convenience.

Deprecated / removed endpoints (AM 6)

No endpoints were deprecated or removed in AM 6.

Deprecated endpoints (AM 5.5)

The following endpoint is deprecated in AM 5.5; you should use the replacement endpoint going forward:

Deprecated endpoints Replacement endpoints
/oauth2/connect/register /oauth2/register

Deprecated endpoints (AM 5)

The following endpoints are deprecated in AM 5; you should use the replacement endpoints going forward:

Deprecated endpoints Replacement endpoints
/json/realms /json/global-service/realms
/frrest/oauth2/token /oauth2/token

/json/sessions/?_action=getTimeLeft

/json/sessions/?_action=getMaxSessionTime

/json/sessions/?_action=getMaxIdle

/json/sessions/?_action=getIdle

/json/sessions/?_action=getSessionInfo
/json/sessions/?_action=isActive&refresh=true /json/sessions/?_action=refresh

/json/sessions/?_action=getPropertyNames

/json/sessions/?_action=getProperty

/json/sessions/?_action=getSessionProperties
/json/sessions/?_action=setProperty /json/sessions/?_action=updateSessionProperties

Deprecated endpoints (OpenAM 13.5)

The following endpoints are deprecated in OpenAM 13.5; you should use the replacement endpoints going forward:

Deprecated endpoints Replacement endpoints
/json/sessions/?_action=getMaxTime /json/sessions/?_action=getTimeLeft
/json/users/_action=register /json/selfservice/userRegistration
/json/users/?_action=confirm /json/selfservice/userRegistration
/json/users/?_action=anonymousCreate /json/selfservice/userRegistration
/json/users/?_action=forgotPassword /json/selfservice/forgottenPassword
/json/users/?_action=forgotPasswordReset /json/selfservice/forgottenPassword

Removed endpoints (OpenAM 13)

The following endpoints are removed in OpenAM 13; you should use the replacement endpoints going forward (where they are available):

Removed endpoints Replacement endpoints
/ws/1/entitlement/decision, /ws/1/entitlement/decisions, /ws/1/entitlement/entitlement, /ws/1/entitlement/entitlements /json/policies?_action=evaluate, /json/policies?_evaluateTree
/identity/log --
/identity/getCookieNamesForToken --
/identity/getCookieNamesToForward --
/json/[realm/]referrals --
/ws/1/entitlement/listener --
/ws/1/entitlement/privilege --
/ws/1/token​ --

Unsupported action values

The following _action values are unsupported in OpenAM 13 for the /json/users endpoint since they relate to the legacy user self service features:

/json/users/?_action=register 
/json/users/?_action=confirm 
/json/users/?_action=anonymousCreate 
/json/users/?_action=forgotPassword 
/json/users/?_action=forgotPasswordReset

See OpenAM 13 Release Notes › Important Changes to Existing Functionality for further information about this change, which was introduced in Version 3.0 of the /json/users endpoint.

You should use the new user self-service features instead as detailed in User Self Service Guide › Implementing User Self Service. This includes the use of the new /json/selfservice endpoints.

Deprecated endpoints (OpenAM 12)

The following endpoints are deprecated in OpenAM 12; you should use the replacement endpoints going forward:

Deprecated endpoints Replacement endpoints
/identity/authorize /json/policies?_action=evaluate, /json/policies?_evaluateTree
/identity/isTokenValid /json/sessions/tokenId?_action=validate
/ws/1/entitlement/decision, /ws/1/entitlement/decisions, /ws/1/entitlement/entitlement, /ws/1/entitlement/entitlements /json/policies?_action=evaluate, /json/policies?_evaluateTree

See Also

Development Guide › Developing with the REST API

Development Guide › Developing with the REST API › Introducing the API Explorer

AM 5.5 Release Notes › Deprecated Functionality

AM 5 Release Notes › Deprecated Functionality

OpenAM 13.5 Release Notes › Deprecated Functionality

OpenAM 13 Release Notes › Removed Functionality

OpenAM 12 Release Notes › Deprecated Functionality

Related Training

N/A

Related Issue Tracker IDs

OPENAM-3877 (Changing password through new REST endpoint fails if default AuthN chain needs more than just the password to authenticate)


How do I avoid common issues with REST calls in AM/OpenAM (All versions)?

The purpose of this article is to provide information on some common issues encountered with REST calls in AM/OpenAM. It also provides some tips to help you troubleshoot issues and use REST more effectively.

Common issues

The following common issues (with solutions) are seen when using REST calls:

  • Used the wrong session cookie name in the REST call.
  • Made the REST call to the load balancer URL.
  • Used the wrong authenticate endpoint in the REST call.

Used the wrong session cookie name in the REST call

If you have changed your AM/OpenAM session cookie name as recommended for securing your installation, you will need to use the new cookie name in REST calls. For example, if your new cookie is called exampleCookie, you would change the following header in your REST calls:

  • From:
    -H "iPlanetDirectoryPro: AQIC5..."
  • To:
    -H "exampleCookie: AQIC5..."

If you are unsure what your session cookie name is, you can check it with the following REST call:

$ curl -s 'http://host1.example.com:8080/openam/json/serverinfo/*' | tr ',' '\n' | grep cookieName
"cookieName":"iPlanetDirectoryPro"

Made the REST call to the load balancer URL

If you make a REST call to the load balancer URL, the call can go to any AM/OpenAM instance, which may not be the intended server. You can avoid this issue as follows:

  • Always use the actual AM/OpenAM server (FQDN) URL in your REST call to ensure the call goes to the correct instance (recommended). 
  • Add the following cookie header to your REST call to identify the required instance providing your load balancer uses session stickiness (amlbcookie):
    -H "Cookie: amlbcookie=<serverid>"

Used the wrong authenticate endpoint in the REST call 

If you have changed the Organization Authentication Configuration setting from ldapService to a non-DataStore module based chain, the amadmin user will not be able to authenticate using the /authenticate endpoint as they must authenticate via the DataStore module. See Authentication and Single Sign-On Guide › To Set the Default Authentication Tree or Chain for further information. This issue may also affect you if you use a DNS name to map to a different realm. 

To ensure the amadmin user can authenticate in this scenario, you must append the /authenticate endpoint with ?authIndexType=service&authIndexValue=adminconsoleservice. For example:

  • AM 5 and later:
    http://host1.example.com:8080/openam/json/realms/root/authenticate?authIndexType=service&authIndexValue=adminconsoleservice
  • Pre-AM 5:
    http://host1.example.com:8080/openam/json/authenticate?authIndexType=service&authIndexValue=adminconsoleservice
    

The adminconsoleservice service uses the authentication chain defined for the administrator (Administrator Authentication Configuration).

Troubleshooting tips

When you use curl for REST calls, there are a couple of useful options you can include for troubleshooting:

  • -v, --verbose - the verbose option provides useful debugging information to help you understand what is happening with your curl command.
  • -k, --insecure - the insecure option is useful when you have SSL/TLS enabled (HTTPS) and want to eliminate connection issues as a result of certificates etc. By using this option, curl will connect to your server using an insecure connection. In this way, you can isolate whether you are experiencing issues with SSL connectivity or more general issues with your curl command.

See curl.1 man page for further information on all the available curl options.

Example verbose output when authenticating over REST

* Connected to host1.example.com (192.0.2.255) port 8080 (#0)
> POST /openam/json/authenticate HTTP/1.1
> User-Agent: curl/7.35.0
> Host: host1.example.com:8080
> Accept: */*
> Cache-Control: no-cache
> Content-Type: application/json
> X-OpenAM-Password: cangetinam
> X-OpenAM-Username: amadmin
>
< HTTP/1.1 200 OK
* Server Apache-Coyote/1.1 is not blacklisted
< Server: Apache-Coyote/1.1
< X-Frame-Options: SAMEORIGIN
< Set-Cookie: amlbcookie=01; Domain=host1.example.com; Path=/
< Set-Cookie: iPlanetDirectoryPro="AQIC5wM2LY4SfcwGDl0FeGy0XdsRtoRSuPndpzVIxxrFUrM.*AAJTSQACMDEAAlNLABM2MTk5NjgwMzk2MTQxOTA2OTIxAAJTMQAA*"; Domain=host1.example.com; Path=/
< Cache-Control: no-cache, no-store, must-revalidate
< Content-API-Version: resource=2.1
< Expires: 0
< Pragma: no-cache
< Content-Type: application/json;charset=UTF-8
< Content-Length: 159
< Date: Wed, 25 Apr 2018 11:20:29 GMT
<
* Connection #0 to host host1.example.com left intact
{"tokenId":"AQIC5wM2LY4SfcwGDl0FeGy0XdsRtoRSuPndpzVIxxrFUrM.*AAJTSQACMDEAAlNLABM2MTk5NjgwMzk2MTQxOTA2OTIxAAJTMQAA*","successUrl":"/openam/console","realm":"/"}

Usage tips

The following suggestions will help you identify REST calls and improve usability:

  • API Explorer - as of AM 5, you can use the API Explorer to locate REST API endpoints as detailed in Development Guide › Introducing the API Explorer.
  • Postman - you can use Postman to make REST calls, which allows you swap parameters easily and save commonly used calls. ForgeRock provides some Postman collections for its customers to use to perform tasks as detailed in How do I use the Postman collections that are provided for AM/OpenAM (All versions)? (this article is only available to customers/partners).
  • jq - you can use jq on the command line in conjunction with curl commands to parse the JSON response. One of the most common uses is to prettify the response for readability. 
Note

These are third-party tools that we suggest can be used with REST calls but are not supported by ForgeRock.

jq

You can install jq as outlined in Download jq.

The simplest jq option is to prettify a response on the command line by adding | jq . at the end of the command. Consider the following examples:

  • Standard curl command:
    $ curl -X POST -H "X-OpenAM-Username: amadmin" -H "X-OpenAM-Password: cangetinam" -H "Content-Type: application/json" -H "Accept-API-Version: resource=2.0, protocol=1.0" http://host1.example.com:8080/openam/json/realms/root/authenticate
    
    Example response:
    {"tokenId":"AQIC5wM2LY4Sfcz1vWJU7s6oqwudOhVVJN4P6P1dFbrBH_s.*AAJTSQACMDEAAlNLABM0MDk5ODM5MDk5MTEzNzUxMzg4AAJTMQAA*","successUrl":"/openam/console","realm":"/"}
    
  • Curl command with jq pretty-print option:
    $ curl -X POST -H "X-OpenAM-Username: amadmin" -H "X-OpenAM-Password: cangetinam" -H "Content-Type: application/json" -H "Accept-API-Version: resource=2.0, protocol=1.0" http://host1.example.com:8080/openam/json/realms/root/authenticate | jq .
    
    Example response:
    {
      "realm": "/",
      "successUrl": "/openam/console",
      "tokenId": "AQIC5wM2LY4Sfcz1vWJU7s6oqwudOhVVJN4P6P1dFbrBH_s.*AAJTSQACMDEAAlNLABM0MDk5ODM5MDk5MTEzNzUxMzg4AAJTMQAA*"
    }
    

See Also

Using the REST API in AM/OpenAM

Login to AM/OpenAM console (All versions) fails for amadmin user

How do I change the session cookie name for AM/OpenAM and Policy Agents (All versions)?

Installation Guide › Securing Installations

Related Training

N/A

Related Issue Tracker IDs

N/A


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

The purpose of this article is to provide information on retrieving user attributes and session properties from a session using the REST API. User attributes and session properties are considered protected properties and can only be retrieved via REST as of OpenAM 13.5. The method varies according to whether you are using AM or OpenAM.

Overview

This process demonstrates retrieving a user's last name and email address from a session using REST, where the LDAP user attributes are:

  • sn - last name
  • mail - email address

If you want to retrieve LDAP user attributes from a session, you must first map them to session attributes and then add them to the whitelist. If you want to retrieve other session properties, you do not need to map them; you just need to add them to the whitelist. See FAQ: REST API in AM/OpenAM (Q. Can I query protected session properties using the REST API?) for a list of available session properties. 

Configuring the user attributes / whitelist

Note

You may need to add the Session Property Whitelist Service if it is not listed under Services by clicking Add a Service and then selecting Session Property Whitelist Service. If you are using ssoadm, you can replace set-realm-svc-attrs in the ssoadm command with add-svc-realm to add this service and set the attributes with the same command.

You can configure user attributes / whitelist as follows, where step 1 is only needed if you want to retrieve LDAP user attributes from a session:

  1. Map the required LDAP user attributes to session attributes using either the console or ssoadm:
    • Console: navigate to: Realms > [Realm Name] > Authentication > Settings > Post Authentication Processing > User Attribute Mapping to Session Attribute and specify the map in the following format: userAttribute|sessionAttribute, where sessionAttribute is a name of your choosing. Create individual mappings for each attribute; for example, to map the sn and mail attribute, you would enter something similar to:
      sn|lastName 
      mail|user.mail
    • ssoadm: enter the following command:
      $ ./ssoadm set-realm-svc-attrs -s iPlanetAMAuthService -e [realmname] -u [adminID] -f [passwordfile] -a sunAMUserAttributesSessionMapping="[userAttribute|sessionAttribute]"
      replacing [realmname], [adminID], [passwordfile] and [userAttribute|sessionAttribute] with appropriate values, where the sunAMUserAttributesSessionMapping attribute must be specified for each individual mapping. For example, to map the sn and mail attribute, you would use the following command:
      $ ./ssoadm set-realm-svc-attrs -s iPlanetAMAuthService -e / -u amadmin -f pwd.txt -a sunAMUserAttributesSessionMapping="sn|lastName" sunAMUserAttributesSessionMapping="mail|user.mail"
  2. Add the user attributes you just specified / other session properties to the whitelist using either the console or ssoadm:
    • Console: navigate to: Realms > [Realm Name] > Services > Session Property Whitelist Service > Whitelisted Session Property Names and enter each session attribute individually with a prefix of am.protected., for example:
      am.protected.lastName
      am.protected.user.mail
      
    • ssoadm: enter the following command:
      $ ./ssoadm set-realm-svc-attrs -s SessionPropertyWhitelistService -e [realmname] -u [adminID] -f [passwordfile] -a forgerock-session-property-whitelist=[sessionAttribute]
      
      replacing [realmname], [adminID], [passwordfile] and [sessionAttribute] with appropriate values, where the forgerock-session-property-whitelist attribute must be specified for each individual session attribute. For example, you would use the following command to add the session attributes used in this example:
      $ ./ssoadm set-realm-svc-attrs -s SessionPropertyWhitelistService -e / -u amadmin -f pwd.txt -a forgerock-session-property-whitelist=am.protected.lastName forgerock-session-property-whitelist=am.protected.user.mail

Retrieving the user attributes / session properties (AM 5 and later)

In AM 5 and later, you should use the json/sessions/?_action=getSessionProperties endpoint. You do not need to specify the --data option with this endpoint; all properties in your whitelist are returned.

You can retrieve these user attributes / session properties as follows: 

  1. Authenticate as the user for whom you want to retrieve user attributes / session properties; you must use the actual AM server URL (not lb). For example:
    $ curl -X POST -H "X-OpenAM-Username: demo" -H "X-OpenAM-Password: changeit" -H "Content-Type: application/json" -H "Accept-API-Version: resource=2.0, protocol=1.0" http://host1.example.com:8080/openam/json/realms/root/authenticate
    Example response:
    { "tokenId": "AQIC5wM2LY4SfcxsuvGEjcsppDSFR8H8DYBSouTtz3m64PI.*AAJTSQACMDIAAlNLABQtNTQwMTU3NzgxODI0NzE3OTIwNAEwNDU2NjE0*", "successUrl": "/openam/console", "realm": "/" } 
    
  2. Retrieve the user attributes / session properties for this user using the following curl command against the actual AM server URL (not lb), where the iPlanetDirectoryPro header (default AM session cookie name) is set to the token returned when you authenticated:
    $ curl -X POST -H "Content-Type: application/json" -H "Accept-API-Version: resource=2.0, protocol=1.0" -H "iPlanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" http://host1.example.com:8080/openam/json/realms/root/sessions/?_action=getSessionProperties
    Example response:  
    {"am.protected.lastName": "doe", "am.protected.user.mail": "jdoe@example.com"}
    

Retrieving the user attributes / session properties (OpenAM 13.5)

In OpenAM 13.5, you should use the json/sessions/?_action=getProperty endpoint and specify the properties you want to retrieve in the --data option. This endpoint is deprecated in AM 5.

You can retrieve these user attributes / session properties as follows: 

  1. Authenticate as the user for whom you want to retrieve user attributes / session properties; you must use the actual OpenAM server URL (not lb). For example:
    $ curl -X POST -H "X-OpenAM-Username: demo" -H "X-OpenAM-Password: changeit" -H "Content-Type: application/json" http://host1.example.com:8080/openam/json/authenticate
    Example response:
    { "tokenId": "AQIC5wM2LY4SfcxsuvGEjcsppDSFR8H8DYBSouTtz3m64PI.*AAJTSQACMDIAAlNLABQtNTQwMTU3NzgxODI0NzE3OTIwNAEwNDU2NjE0*", "successUrl": "/openam/console" }
    
  2. Retrieve the user attributes / session properties for this user using the following curl command against the actual OpenAM server URL (not lb), where the iPlanetDirectoryPro header (default OpenAM session cookie name) is set to the token returned when you authenticated:
    $ curl -X POST -H "Content-Type: application/json" -H "iPlanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" -d '{
         "properties": ["am.protected.lastName", "am.protected.user.mail"]
    }' http://host1.example.com:8080/openam/json/sessions/?_action=getProperty
    Example response:  
    {"am.protected.lastName": "doe", "am.protected.user.mail": "jdoe@example.com"}
    

See Also

How do I validate session tokens and obtain session details using the REST API in AM (All versions)?

FAQ: REST API in AM/OpenAM

How do I unlock a user's account using the REST API in AM/OpenAM (All versions)?

How do I change a user's password using the REST API in AM/OpenAM (All versions)?

Using the REST API in AM/OpenAM

Authentication and Single Sign-On Guide › Validating Sessions

Authentication and Single Sign-On Guide › Specifying Realms in REST API Calls

Related Training

N/A

Related Issue Tracker IDs

OPENAM-9129 (Expose the AuthLevel property using newer REST endpoints )


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

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

Caution

AM/OpenAM 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/OpenIDM or DS/OpenDJ, 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/OpenAM 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 and Maintenance Guide › Customizing 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.
  • AM 5.x / OpenAM 13.x console: navigate to: Realms > [Realm Name] > Data Stores > [Data Store Name] and add the user attribute to the LDAP User Attributes list.
  • Pre-OpenAM 13 console: navigate to: Access Control > [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.txt
      replacing [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.txt
      replacing [realmname], [datastorename], [adminID] and [passwordfile] with appropriate values.

Updating user attribute using the REST API

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

  1. Authenticate as the admin user. The URL to authenticate changes depending on which version you are using; you must use the actual AM/OpenAM server URL (not lb). For example:
    • AM 5 and later:
      $ curl -X POST -H "X-OpenAM-Username: amadmin" -H "X-OpenAM-Password: cangetinam" -H "Content-Type: application/json" -H "Accept-API-Version: resource=2.0, protocol=1.0" http://host1.example.com:8080/openam/json/realms/root/authenticate
      
    • Pre-AM 5:
      $ curl -X POST -H "X-OpenAM-Username: amadmin" -H "X-OpenAM-Password: cangetinam" -H "Content-Type: application/json" http://host1.example.com:8080/openam/json/authenticate
    Example response:
    { "tokenId": "AQIC5wM2LY4SfcxsuvGEjcsppDSFR8H8DYBSouTtz3m64PI.*AAJTSQACMDIAAlNLABQtNTQwMTU3NzgxODI0NzE3OTIwNAEwNDU2NjE0*", "successUrl": "/openam/console", "realm": "/" } 
    
  2. Update the user attribute using one of the following curl commands against the actual AM/OpenAM server URL (not lb), where the iPlanetDirectoryPro header (default AM/OpenAM session cookie name) is set to the token returned when you authenticated. The following examples demonstrate updating a user attribute called facsimileTelephoneNumber for the demo user in the employees realm:
    • AM 5 and later:
      $ 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
      
    • Pre-AM 5:
      $ curl -X PUT -H "iPlanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" -H "Content-Type: application/json" -d '{ 
           "facsimileTelephoneNumber":"01179123456" 
      }' http://host1.example.com:8080/openam/json/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/OpenAM

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

Using the REST API in AM/OpenAM

Data stores in AM/OpenAM

Setup and Maintenance Guide › Setting Up Realms › Identity Management

Setup and Maintenance Guide › Setting Up Identity Data Stores › Customizing Profile Attributes

Authentication and Single Sign-On Guide › About the REST API › Specifying Realms in REST API Calls

Related Training

N/A

Related Issue Tracker IDs

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


How do I assign password policies to a user when creating the user via the REST API in AM/OpenAM (All versions)?

The purpose of this article is to provide information on assigning password policies to a user when creating the user via the REST API in AM/OpenAM. These password policies are also enforced at the point you create the user to ensure the user's password complies with the password policy. This article assumes you are using DS/OpenDJ for your user store.

Caution

AM/OpenAM 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/OpenIDM or DS/OpenDJ, depending on your use case.

Overview

There are two approaches to this depending on your use case:

  • Single password policy that applies to all users. This is a very simple process as follows:
    1. Create your password policy in DS/OpenDJ (either as a global policy or assigned to a specific branch, such as : dc=example,dc=com or ou=employees,dc=example,dc=com). See Administration Guide › Assigning Password Policies for further information.
    2. Create your users in AM/OpenAM via the REST API using the users/?_action=create endpoint as normal. The password policy is automatically assigned to the user because of the subtree the user is created on.
  • Multiple password policies with users having different policies. This process requires additional configuration but gives you more flexibility as you choose which password policy to assign to the user when you create them. See the Assigning password policies to a user section for further information.

If you want end users to receive a meaningful message when they change their password and it does not comply with the password policy, you must use the LDAP authentication module and enable LDAP Behera Password Policy Support within this module. See Authentication and Single Sign-On Guide › LDAP Authentication Module for further information on this authentication module. The default DataStore module does not report these messages to the end user. 

Assigning password policies to a user

The following example process walks you through creating two different password policies and assigning one of them to a user using the REST API. This process includes steps to verify the password policies are working as expected:

  1. Create your password policies in DS/OpenDJ as described in Administration Guide › Configuring Password Policies. In this example, the following two password policies have been created: 
    dn: cn=Dictionary,cn=Password Policies,cn=config
    objectClass: ds-cfg-password-policy
    objectClass: top
    objectClass: ds-cfg-authentication-policy
    ds-cfg-default-password-storage-scheme: cn=SHA-1,cn=Password Storage Schemes,cn=config
    cn: Dictionary
    ds-cfg-java-class: org.opends.server.core.PasswordPolicyFactory
    ds-cfg-password-validator: cn=Dictionary,cn=Password Validators,cn=config
    ds-cfg-password-attribute: userPassword
    
    dn: cn=Repeated,cn=Password Policies,cn=config
    objectClass: ds-cfg-password-policy
    objectClass: top
    objectClass: ds-cfg-authentication-policy
    ds-cfg-default-password-storage-scheme: cn=SHA-1,cn=Password Storage Schemes,cn=config
    cn: Repeated
    ds-cfg-java-class: org.opends.server.core.PasswordPolicyFactory
    ds-cfg-password-validator: cn=Repeated Characters,cn=Password Validators,cn=config
    ds-cfg-password-attribute: userPassword
    
  2. Test the password policy is working on the DS/OpenDJ side by creating a user who does not meet the password policy conditions:
    1. Create an LDIF file (newuser.ldif) with a password that is in the dictionary and assign that Dictionary password policy to the user, for example:
      dn: uid=newuser,ou=People,dc=example,dc=com
      uid: newuser
      objectClass: person
      objectClass: organizationalPerson
      objectClass: inetOrgPerson
      objectClass: top
      cn: New User
      sn: User
      ou: People
      mail: newuser@example.com
      userPassword: password
      ds-pwp-password-policy-dn: cn=Dictionary,cn=Password Policies,cn=config
      
    2. Add the user with the Dictionary password policy using the ldapmodify command and observe that it fails:
      $ ./ldapmodify --port 1349 --hostname localhost --bindDN "cn=Directory Manager" --bindPassword password --defaultAdd newuser.ldif
      Processing ADD request for uid=newuser,ou=People,dc=example,dc=com
      
      ADD operation failed
      
      Result Code:  19 (Constraint Violation)
      
      Additional Information:  The password value for attribute userPassword was found to be unacceptable: The provided password contained a word from the server's dictionary
      
      In pre-DS 5, you need to include --filename in this command before newuser.ldif.
  3. Add the ds-pwp-password-policy-dn attribute to the data store configuration using the console (see How do I update LDAP user attributes using the REST API in AM/OpenAM (All versions)? for instructions on doing this via ssoadm): 
    • AM 6 and later console: navigate to: Realms > [Realm Name] > Data Stores > [Data Store Name] > User Configuration and add the ds-pwp-password-policy-dn attribute to the LDAP User Attributes list.
    • AM 5.x / OpenAM 13.x console: navigate to: Realms > [Realm Name] > Data Stores > [Data Store Name] and add the ds-pwp-password-policy-dn attribute to the LDAP User Attributes list.
    • Pre-OpenAM 13 console: navigate to: Access Control > [Realm Name] > Data Stores > [Data Store Name] and add the ds-pwp-password-policy-dn attribute to the LDAP User Attributes list.
  4. Restart the web application container in which AM/OpenAM runs to apply these configuration changes.
  5. Authenticate as an admin user. The URL changes depending on which version you are using; you must use the actual AM/OpenAM server URL (not lb). For example:
    • AM 5 and later:
      $ curl -X POST -H "X-OpenAM-Username: amadmin" -H "X-OpenAM-Password: cangetinam" -H "Content-Type: application/json" -H "Accept-API-Version: resource=2.0, protocol=1.0" http://host1.example.com:8080/openam/json/realms/root/authenticate
      
    • Pre-AM 5:
      $ curl -X POST -H "X-OpenAM-Username: amadmin" -H "X-OpenAM-Password: cangetinam" -H "Content-Type: application/json" http://host1.example.com:8080/openam/json/authenticate
    Example response:
    { "tokenId": "AQIC5wM2LY4SfcxsuvGEjcsppDSFR8H8DYBSouTtz3m64PI.*AAJTSQACMDIAAlNLABQtNTQwMTU3NzgxODI0NzE3OTIwNAEwNDU2NjE0*", "successUrl": "/openam/console", "realm": "/" } 
    
  6. Create a user with a password that complies with the password policy using one of the following curl commands against the actual AM/OpenAM server URL (not lb), where the iPlanetDirectoryPro header (default AM/OpenAM session cookie name) is set to the token returned when you authenticated and ds-pwp-password-policy-dn is set to the required password policy (this should be in the same realm as the one you updated in step 3). For example:
    • AM 5 and later:
      $ curl -X PUT -H "iPlanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" -H "Content-Type: application/json" -H "Accept-API-Version: resource=3.0, protocol=1.0" -H "If-None-Match: *" -d '{ "username": "newuser1", "userpassword": "secret1234", "ds-pwp-password-policy-dn": "cn=Dictionary,cn=Password Policies,cn=config" }' http://host1.example.com:8080/openam/json/realms/root/users/newuser1
      
    • Pre-AM 5:
      $ curl -X PUT -H "iPlanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" -H "Content-Type: application/json" -H "If-None-Match: *" -d '{ "username": "newuser1", "userpassword": "secret1234", "ds-pwp-password-policy-dn": "cn=Dictionary,cn=Password Policies,cn=config" }' http://host1.example.com:8080/openam/json/users/newuser1
    Example response:
    {
      "username": "newuser1",
      "realm": "/",
      "uid": [
        "newuser1"
      ],
      "universalid": [
        "id=newuser1,ou=user,dc=example,dc=com"
      ],
      "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=newuser1,ou=user,dc=example,dc=come"
      ],
      "inetUserStatus": [
        "Active"
      ],
      "sn": [
        "newuser1"
      ],
      "cn": [
        "newuser1"
      ],
      "modifyTimestamp": [
        "20161004155427Z"
      ],
      "createTimestamp": [
        "20160721105610Z"
      ]
    }
    
  7. Test that user creation fails with a password that violates the password policy by creating a user with a password such as aaaaaaaaa (which is against the second password policy of Repeat Characters in this example) and observe that it fails. For example:
    • AM 5 and later:
      $ curl -X PUT -H "iPlanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" -H "Content-Type: application/json" -H "Accept-API-Version: resource=3.0, protocol=1.0" -H "If-None-Match: *" -d '{ "username": "newuser2", "userpassword": "aaaaaaaaa", "ds-pwp-password-policy-dn": "cn=Repeated,cn=Password Policies,cn=config" }' http://host1.example.com:8080/openam/json/realms/root/users/newuser2
      
    • Pre-AM 5:
      $ curl -X PUT -H "iPlanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" -H "Content-Type: application/json" -H "If-None-Match: *" -d '{ "username": "newuser2", "userpassword": "aaaaaaaaa", "ds-pwp-password-policy-dn": "cn=Repeated,cn=Password Policies,cn=config" }' http://host1.example.com:8080/openam/json/users/newuser2
    Example response:
    {"code":400,"reason":"Bad Request","message":"Bad Request"}
Note

In AM 5, OpenAM 13, 13.5, you will get a Bad Request response if the user cannot be created because the password is against the password policy. A more meaningful message will be shown in the IdRepo logs if you use the LDAP authentication module since this handles the Behera messages. This is a known issue: OPENAM-9009 (When using REST endpoint "json/users/?_action=create" with password policy violation, AM returns HTTP 400 "bad request", reason "Bad Request" , Message "Bad Request" rather than a more meaningful error message), which is fixed in AM 5.5 and OpenAM 13.5.1.

See Also

FAQ: Users in AM/OpenAM

How do I change a user's password using the REST API in AM/OpenAM (All versions)?

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

How do I enable account lockout in AM/OpenAM (All versions)?

Administrator and user accounts in AM/OpenAM

Data stores in AM/OpenAM

Administration Guide › Configuring Password Policy

Setup and Maintenance Guide › Creating Identities

Authentication and Single Sign-On Guide › Specifying Realms in REST API Calls

Related Training

N/A

Related Issue Tracker IDs

OPENAM-9009 (When using REST endpoint "json/users/?_action=create" with password policy violation, AM returns HTTP 400 "bad request", reason "Bad Request" , Message "Bad Request" rather than a more meaningful error message)


How do I unlock a user's account using the REST API in AM/OpenAM (All versions)?

The purpose of this article is to provide information on using the REST API to unlock user accounts in AM/OpenAM. The REST API can be used to unlock a user's account that has been locked using either physical lockout or memory lockout (if you use authentication chains) or the Account lockout node (if you use authentication trees in AM 6 and later).

Background information

The way in which a user account can be unlocked using the REST API depends on how it has been locked in the first place. You can lock user accounts using physical lockout, memory lockout or the Account lockout node as detailed in How do I enable account lockout in AM/OpenAM (All versions)?

Physical lockout and Account lockout node

The ability to unlock a user's account that has been physically locked or locked via the Account lockout node relies on resetting the inetUserStatus attribute to Active. When a user is physically locked out or locked via the Account lockout node, their user status (the inetUserStatus attribute) is changed to Inactive in the user store (both the attribute and status value are configurable). 

See the Unlocking a user's account (physical lockout and Account lockout node) section for details on unlocking a user's account using the REST API.

Memory lockout

The ability to unlock a user's account that is locked via memory lockout relies on using the Store Invalid Attempts in Data Store option. When the Store Invalid Attempts in Data Store option is enabled, AM/OpenAM stores information about invalid authentication attempts in the user's profile. By default, this information is stored in the sunAMAuthInvalidAttemptsData attribute; however, you can store this information in a different attribute by setting the Invalid Attempts Data Attribute Name field to the required attribute (this must be a valid attribute in the user data store).

The purpose of the Store Invalid Attempts in Data Store option is primarily to allow other AM/OpenAM servers to determine the lockout state across a cluster; however, you can also delete the value of this attribute to manually unlock a user's account. Since memory lockout is being used, the inetUserStatus attribute is not changed and remains set to Active even when the user's account is locked.

In summary, you must set at least the following Account Lockout options to be able to use the REST API to unlock user accounts:

  • Login Failure Lockout Mode - enabled.
  • Login Failure Lockout Duration - set to a value greater than 0 to enable memory lockout.
  • Store Invalid Attempts in Data Store - enabled.

See the Unlocking a user's account (memory lockout) section for details on unlocking a user's account using the REST API.

Unlocking a user's account (physical lockout and Account lockout node)

The following example assumes you are using the default inetUserStatus attribute; if you have changed it, substitute your attribute for the inetUserStatus attribute in the curl command. 

The commands used vary between AM/OpenAM versions:

AM 5 and later

  1. Authenticate as an admin user; you must use the actual AM server URL (not lb). 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.0, protocol=1.0"  http://host1.example.com:8080/openam/json/realms/root/authenticate
    
    Example response:
    { "tokenId": "AQIC5wM2LY4SfcxsuvGEjcsppDSFR8H8DYBSouTtz3m64PI.*AAJTSQACMDIAAlNLABQtNTQwMTU3NzgxODI0NzE3OTIwNAEwNDU2NjE0*", "successUrl": "/openam/console", "realm": "/" } 
    
  2. Unlock the user's account (in this example, demo) using the following curl command against the actual AM server URL (not lb), where the iPlanetDirectoryPro header (default AM session cookie name) is set to the token returned when you authenticated:
    $ curl -X PUT -H "iPlanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" -H "Content-type: application/json" -H "Accept-API-Version: resource=2.0, protocol=1.0" -d'{
        "inetUserStatus": "Active"
    }' http://host1.example.com:8080/openam/json/realms/root/users/demo
    Example response:
    {
      "username": "demo",
      "realm": "/",
      "uid": [
        "demo"
      ],
      "universalid": [
        "id=demo,ou=user,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": [
        "demo"
      ],
      "cn": [
        "demo"
      ],
      "iplanet-am-user-auth-config": [
        "ldapService"
      ],
      "createTimestamp": [
        "20160721105610Z"
      ],
      "modifyTimestamp": [
        "20160727134147Z"
      ]
    }
    

Pre-AM 5 

The commands differ in earlier versions of OpenAM, but the responses are similar to the ones shown above:

  1. Authenticate as an admin user; you must use the actual OpenAM server URL (not lb). For example:
    $ curl -X POST -H "X-OpenAM-Username: amadmin" -H "X-OpenAM-Password: cangetinam" -H "Content-Type: application/json" http://host1.example.com:8080/openam/json/authenticate
  2. Unlock the user's account (in this example, demo) using the following curl command against the actual OpenAM server URL (not lb), where the iPlanetDirectoryPro header (default OpenAM session cookie name) is set to the token returned when you authenticated:
    $ curl -X PUT -H "iPlanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" -H "Content-type: application/json" -d'{
        "inetUserStatus": "Active"
    }' http://host1.example.com:8080/openam/json/users/demo

Unlocking a user's account (memory lockout)

The following example assumes you are using the default sunAMAuthInvalidAttemptsData attribute; if you have changed it, substitute your attribute for the sunAMAuthInvalidAttemptsData attribute in the curl command. The commands used vary between AM/OpenAM versions:

AM 5 and later

  1. Authenticate as an admin user; you must use the actual AM server URL (not lb). 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.0, protocol=1.0"  http://host1.example.com:8080/openam/json/realms/root/authenticate
    
    Example response:
    { "tokenId": "AQIC5wM2LY4SfcxsuvGEjcsppDSFR8H8DYBSouTtz3m64PI.*AAJTSQACMDIAAlNLABQtNTQwMTU3NzgxODI0NzE3OTIwNAEwNDU2NjE0*", "successUrl": "/openam/console", "realm": "/" } 
    
  2. Unlock the user's account (in this example, demo) using the following curl command against the actual AM server URL (not lb), where the iPlanetDirectoryPro header (default AM session cookie name) is set to the token returned when you authenticated:
    $ curl -X PUT -H "iPlanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" -H "Content-type: application/json" -H "Accept-API-Version: resource=2.0, protocol=1.0" -d'{
        "sunAMAuthInvalidAttemptsData": []
    }' http://host1.example.com:8080/openam/json/realms/root/users/demo
    Example response:
    {
      "username": "demo",
      "realm": "/",
      "uid": [
        "demo"
      ],
      "universalid": [
        "id=demo,ou=user,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": [
        "demo"
      ],
      "cn": [
        "demo"
      ],
      "iplanet-am-user-auth-config": [
        "ldapService"
      ],
      "createTimestamp": [
        "20160721105610Z"
      ],
      "modifyTimestamp": [
        "20160727134147Z"
      ]
    }
    

Pre-AM 5 

The commands differ in earlier versions of OpenAM, but the responses are similar to the ones shown above:

  1. Authenticate as an admin user; you must use the actual OpenAM server URL (not lb). For example:
    $ curl -X POST -H "X-OpenAM-Username: amadmin" -H "X-OpenAM-Password: cangetinam" -H "Content-Type: application/json" http://host1.example.com:8080/openam/json/authenticate
  2. Unlock the user's account (in this example, demo) using the following curl command against the actual OpenAM server URL (not lb), where the iPlanetDirectoryPro header (default OpenAM session cookie name) is set to the token returned when you authenticated:
    $ curl -X PUT -H "iPlanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" -H "Content-type: application/json" -d'{
        "sunAMAuthInvalidAttemptsData": []
    }' http://host1.example.com:8080/openam/json/users/demo
    

See Also

How do I enable account lockout in AM/OpenAM (All versions)?

Minimum password length is 8 error in AM (All versions) when updating identities using the REST API

Authentication and Single Sign-On Guide › Account Lockout

Authentication and Single Sign-On Guide › Account lockout Node

Authentication and Single Sign-On Guide › Specifying Realms in REST API Calls

Related Training

N/A

Related Issue Tracker IDs

OPENAM-11052 (Minimum password length is 8 error in AM 5.0 when updating identities using the REST API)


How do I change a user's password using the REST API in AM/OpenAM (All versions)?

The purpose of this article is to provide information on changing a user's password in AM/OpenAM using the REST API. The method varies according to which version of AM/OpenAM you are using.

Overview

To change a user's password, you must authenticate and include the returned token ID in the curl command. The URL to authenticate changes depending on which version you are using; you must use the actual AM/OpenAM server URL (not lb). For example:

  • AM 5 and later:
    $ curl -X POST -H "X-OpenAM-Username: amadmin" -H "X-OpenAM-Password: cangetinam" -H "Content-Type: application/json" -H "Accept-API-Version: resource=2.0, protocol=1.0"  http://host1.example.com:8080/openam/json/realms/root/authenticate
    
  • Pre-AM 5:
    $ curl -X POST -H "X-OpenAM-Username: amadmin" -H "X-OpenAM-Password: cangetinam" -H "Content-Type: application/json" http://host1.example.com:8080/openam/json/authenticate

Example response:

{ "tokenId": "AQIC5wM2LY4SfcxsuvGEjcsppDSFR8H8DYBSouTtz3m64PI.*AAJTSQACMDIAAlNLABQtNTQwMTU3NzgxODI0NzE3OTIwNAEwNDU2NjE0*", "successUrl": "/openam/console", "realm": "/" }

Changing a user's password

You (or the user) can change a user's password using the following curl commands according to which version of AM/OpenAM you are using. The user's old password is required; however, admin users do not need to supply the user's old password from OpenAM 12.0.3 onwards.

AM 5 and later

You can use the following curl command against the actual AM server URL (not lb), where the iPlanetDirectoryPro header (default AM session cookie name) is set to the token returned when you authenticated and you supply the user's old password: 

$ curl -X POST -H "iPlanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" -H "Content-Type: application/json" -H "Accept-API-Version: resource=3.0, protocol=1.0" -d '{ "currentpassword":"changeit", "userpassword":"newPassword" }' http://host1.example.com:8080/openam/json/realms/root/users/demo?_action=changePassword {}

An admin user can change the password for a non-admin user without supplying the old password by using a HTTP PUT request instead:

$ curl -X PUT -H "iPlanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" -H "Content-Type: application/json" -H "Accept-API-Version: resource=3.0, protocol=1.0" -d '{ "userpassword":"newPassword" }' http://host1.example.com:8080/openam/json/realms/root/users/demo

Pre-AM 5

You can use the following curl command against the actual OpenAM server URL (not lb), where the iPlanetDirectoryPro header (default OpenAM session cookie name) is set to the token returned when you authenticated and you supply the user's old password: 

$ curl -X POST -H "iPlanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" -H "Content-Type: application/json" -d '{ "currentpassword":"changeit", "userpassword":"newPassword" }' http://host1.example.com:8080/openam/json/users/demo?_action=changePassword {}

Since OpenAM 12.0.3, admin users can change the password for a non-admin user without supplying the old password by using a HTTP PUT request instead:

$ curl -X PUT -H "iPlanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" -H "Content-Type: application/json" -d '{ "userpassword":"newPassword" }' http://host1.example.com:8080/openam/json/users/demo

See Also

FAQ: Users in AM/OpenAM

FAQ: REST API in AM/OpenAM

Setup and Maintenance Guide › Changing Passwords

Authentication and Single Sign-On Guide › Specifying Realms in REST API Calls

Related Training

N/A

Related Issue Tracker IDs

OPENAM-3877 (Changing password through new REST endpoint fails if default AuthN chain needs more than just the password to authenticate)

OPENAM-5695 (Allow admin users to update user's password without the old password)


How do I force REST API responses to always use lower case for attribute names in AM/OpenAM (All versions)?

The purpose of this article is to provide information on forcing responses returned by the REST API to always use lower case for attribute names in AM/OpenAM. Attribute names included in responses preserve the original case used in the request by default.

Using lower case for attribute names

You can force REST API responses to use lower case for attribute names using either the console or ssoadm:

  • AM / OpenAM 13.5 console: navigate to: Configure > Server Defaults > Advanced > org.forgerock.openam.idm.attribute.names.lower.case and change to true.
  • Pre-OpenAM 13.5 console: navigate to: Configuration > Servers and Sites > Default Server Settings > Advanced > org.forgerock.openam.idm.attribute.names.lower.case and change to true.
  • ssoadm: enter the following command:
    $ ./ssoadm update-server-cfg -s default -u [adminID] -f [passwordfile] -a org.forgerock.openam.idm.attribute.names.lower.case=true
    replacing [adminID] and [passwordfile] with appropriate values.
Note

You must restart the web application container in which AM/OpenAM runs to apply these configuration changes. 

See Also

FAQ: REST API in AM/OpenAM

Related Training

N/A

Related Issue Tracker IDs

OPENAM-3159 (Difference in case between results of identity/json/attributes REST API between first and subsequent calls)


FAQ: REST API in AM/OpenAM

The purpose of this FAQ is to provide answers to commonly asked questions regarding the REST API in AM/OpenAM.

Frequently asked questions

Note

The format of the URL in the REST call has changed in AM 5; realm paths must be absolute and include the top-level realm as detailed in Development Guide › Specifying Realms in REST API Calls. The examples given in this article use this format.

Microsoft® Windows®

If you are using Microsoft Windows, you should be aware that & is treated as a special character. If it is included in a URL, you should either put the URL in quotes or escape the & using ^&. For example, to authenticate to the LDAP module, you could do one of the following:

$ curl -X POST -H "X-OpenAM-Username: demo" -H "X-OpenAM-Password: changeit" -H "Content-Type: application/json" -H "Accept-API-Version: resource=2.0, protocol=1.0" "http://host1.example.com:8080/openam/json/realms/root/authenticate/&authIndexType=module&authIndexValue=LDAP"

$ curl -X POST -H "X-OpenAM-Username: demo" -H "X-OpenAM-Password: changeit" -H "Content-Type: application/json" -H "Accept-API-Version: resource=2.0, protocol=1.0" http://host1.example.com:8080/openam/json/realms/root/authenticate/^&authIndexType=module^&authIndexValue=LDAP

Q. How can I access the REST APIs?

A. The REST APIs are built on the same underlying CRUDPAQ model that is used in DS/OpenDJ and IDM/OpenIDM.

You can access the REST APIs under /json where you deployed AM/OpenAM, for example: http://host1.example.com:8080/openam/json

See How do I know which endpoint to use for REST calls in newer versions of AM/OpenAM? for a single point of reference for evolving REST endpoints.

Q. What is the correct format of the URL for specifying realms in a REST call?

A. To specify a realm in a rest call, you should insert the realm name just before the endpoint; the URL changes depending on which version you are using. For example:

  • AM 5 and later:
    http://host1.example.com:8080/openam/json/realms/root/realms/myRealm/authenticate
  • Pre-AM 5:
    http://host1.example.com:8080/openam/json/myRealm/authenticate

This is detailed in Development Guide › Specifying Realms in REST API Calls and OpenAM 13 Developer's Guide › Developing Client Applications › Specifying Realms in REST API Calls along with other options.

Q. Does a user need to be an admin user to use the REST API?

A. No, any user can use the REST API providing they authenticate first. Upon authenticating, they will receive a valid token, which can be used to access many REST endpoints. However, requests to the /json/sessions endpoint must be done by the amadmin user. See How do I validate session tokens and obtain session details using the REST API in AM (All versions)? and Development Guide › Developing with the REST API for further information.

If you want an administrator to perform certain tasks within REST, such as configuring policies, you can set up delegated administration as described in How do I create an admin user in AM/OpenAM (All versions) with amadmin privileges? and Setup and Maintenance Guide › Delegating Realm Administration Privileges.

Q. Is there a way to check if a token is valid over REST?

A. Yes, you can perform a HTTP POST to the resource URL (/json/sessions/tokenId) using the validate action to check if a token is valid, as demonstrated in the following example:

$ curl -X POST -H "Content-Type: application/json"
http://host1.example.com:8080/openam/json/realms/root/sessions/AQIC5wM2LY4SfcxIygmYg8WE2ZHa8d-xnxLcXcy0JcRJGf8.*AAJTSQACMDEAAlNLABMxMzUwNjIzMzg0NTg3NDMxMjMw*?_action=validate 

Example response:

{"valid":true,"uid":"demo","realm":"/"}

Q. Can I retrieve total number of active sessions at a given point in time from AM/OpenAM using the REST API?

A. Yes, you can use a REST call to get session information, as demonstrated in the following example, where the iPlanetDirectoryPro cookie value is the one returned when you successfully authenticated:

$ curl -X GET -H "Content-Type: application/json" -H "Accept-API-Version: resource=1.1, protocol=1.0" -H "iPlanetDirectoryPro:AQIC5wM2LY4Sfcxs...EwNDU2NjE0*"  http://host1.example.com:8080/openam/json/realms/root/sessions/?_queryID=all
Note

There is a known issue which limits the maximum number of sessions returned by this interface to 120: OPENAM-2200 (json/sessions/?_queryID=all only returning 120 sessions).

Q. How can I check session details using REST?

A. You can check session details (such as the remaining session time and the idle session time) using the /json/sessions endpoint. You can also use this endpoint to validate session tokens.

See How do I validate session tokens and obtain session details using the REST API in AM (All versions)? for further information.

Note

Requests to the /json/sessions endpoint must be done by the amadmin user.

Q. Can I query protected session properties using the REST API?

A. As of OpenAM 13.5, protected session properties can be read via the REST API; you must add the session property to the Session Property Whitelist first to allow it to be read. See Reference › Configuration Reference › Session Property Whitelist Service for further information.

Protected session properties are any that have the am.protected prefix or any of the following:

  • HOST
  • HOST_NAME
  • AuthLevel
  • AuthType
  • Principal
  • UserId
  • UserToken
  • Organization
  • cookieSupport
  • authInstant
  • Principals
  • loginURL
  • FullLoginURL
  • Role
  • Service
  • SessionTimedOut
  • SESSION_HANDLE_PROP
  • TOKEN_RESTRICTION_PROP
  • AM_MAX_IDLE_TIME
  • AM_MAX_SESSION_TIME
  • Constants.AM_CTX_ID
  • Constants.UNIVERSAL_IDENTIFIER

You can read them using the getSessionInfo or getProperty action (depending on version) as demonstrated for AuthLevel in How do I validate session tokens and obtain session details using the REST API in AM (All versions)? (Checking the authentication level) and for other protected properties in How do I retrieve user attributes from a session using the REST API in AM (All versions) and OpenAM 13.5?

Note

You cannot set or delete these session properties via REST.

Resolved RFE: OPENAM-9129 (Expose the AuthLevel property using newer REST endpoints )

Q. How can I use a query to return selected users?

A. You can use the _queryFilter parameter. For example, to return the demo user:

$ curl -X GET -H "Content-Type: application/json" -H "Accept-API-Version: resource=3.0, protocol=1.0" -H "iPlanetDirectoryPro:AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" --data-urlencode '_queryFilter=uid eq "demo"' http://host1.example.com:8080/openam/json/realms/root/users

See Development Guide › Developing with the REST API › Query for further information.

Q. How can I get the properties for a user in a realm using the REST API?

A. You can use the following REST call to retrieve properties for a user in a realm, where the iPlanetDirectoryPro cookie value is the one returned when you successfully authenticated and myRealm is the name of your realm:

$ curl -X GET -H "Content-Type: application/json" -H "Accept-API-Version: resource=3.0, protocol=1.0" -H "iPlanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" http://host1.example.com:8080/openam/json/realms/root/realms/myRealm/users/demo

Q. How can I update a user attribute with a blank value?

You can update a user attribute with a blank value or remove the value for an existing attribute by setting the value to []. For example, to remove the current value for the mail attribute, you would specify the following in the data element of your REST call:

{"mail": []}

Q. Can I specify the tree, module or chain to use for authentication in a REST call?

A. Yes, you can by making use of the authIndexType and authIndexValue parameters. For example:

  • To authenticate using a specific tree:
    http://host1.example.com:8080/openam/json/realms/root/realms/myRealm/authenticate/&authIndexType=service&authIndexValue=authTree
  • To authenticate using a specific chain:
    http://host1.example.com:8080/openam/json/realms/root/realms/myRealm/authenticate/&authIndexType=service&authIndexValue=authChain
  • To authenticate using a specific module:
    http://host1.example.com:8080/openam/json/realms/root/realms/myRealm/authenticate/&authIndexType=module&authIndexValue=moduleName

See Development Guide › Authentication and Logout for further information on these parameters. 

Q. Can I create a realm using the REST API?

A. Yes, you can create a realm using the REST API, but it will not work until you also create the associated services because these are not created when a realm is created via REST. It is recommended that you create a realm using either the console or ssoadm.

See Setup and Maintenance Guide › Setting Up Realms for further information.

Q. Can I configure agents using the REST API?

A. Yes, you can add and update agent profiles using the REST API as detailed in How do I create and update an agent in AM/OpenAM (All versions) using the REST API? This article also provides a Postman collection to make it easier to create and update agents.

See Setup and Maintenance Guide › Creating Identities for further information; most of the examples are for identities but also work for other objects such as policy agent profiles.

Q. How do I create groups using the REST API?

A. You can use POST or PUT requests to create a variety of objects including groups. There are examples in Setup and Maintenance Guide › Creating Identities for creating a group called newGroup using a POST request and a group called anotherGroup using a PUT request. 

Q. Does AM/OpenAM support REST-STS?

A. Yes the RESTful Security Token Service (REST-STS) is supported in AM/OpenAM.

See the following articles and documentation links for further information:

Q. How can I protect a REST endpoint?

A. You can protect a REST endpoint using one of the following approaches:

  • Put a Java Servlet Filter in front of the REST endpoint.
  • Provide another endpoint that acts as a proxy, meaning the flow would be as follows:
    User -> REST -> proxyEndpoint (which does the filtering ) -> REST -> actualEndpoint
  • Use IG/OpenIG to protect the REST endpoint.

Q. How can I authenticate over REST and get a tokenID using zero page login?

A. You can achieve this by passing the username in a X-OpenAM-Username header and the password in a X-OpenAM-Password header as demonstrated in the example below:

$ curl -X POST -H "X-OpenAM-Username: demo" -H "X-OpenAM-Password: changeit" -H "Content-Type: application/json" -H "Accept-API-Version: resource=2.0, protocol=1.0"http://host1.example.com:8080/openam/json/realms/root/authenticate

Example response:

{ "tokenId": "AQIC5wM2LY4SfcyPCKVhaca6lRav2ZgOyGf8KWmyDdu80tc.*AAJTSQACMDIAAlNLABQtMjIyNDg0MTYzNTQ3ODg2NzI1MwACUzEAAjAx*", "successUrl": "/openam/console", "realm": "/" }

The response you receive shows the tokenId that corresponds to the user session. The successUrl is the URI to which the user would normally be redirected.

Note

 "zero page login" mechanism works only for name/password authentication. More examples can be found in the Development Guide › Authentication and Logout

See Also

How do I create a policy in AM/OpenAM (All versions) using the REST API?

How do I change a user's password using the REST API in AM/OpenAM (All versions)?

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

How do I force REST API responses to always use lower case for attribute names in AM/OpenAM (All versions)?

Using the REST API in AM/OpenAM

Development Guide › Developing with the REST API

REST - for the rest of us

Related Training

ForgeRock Access Management Core Concepts (AM-400)


REST - for the rest of us

The purpose of this article is to provide information on REST to help you understand what it is, what it is used for and how ForgeRock products add security to REST.

What does REST stand for?

REST = REpresentational State Transfer

REST is an architectural style (design rules) of the Web introduced by Dr. Roy Fielding in his dissertation. Using a web browser to cruise the web is utilizing an environment that is an implementation of a REST-based design style. The protocol used by the web browser and the servers that deliver content to the browser are using HTTP. REST is the design style; HTTP is an example of an implementation using REST principles. If you use the ‘net you’ve experienced REST.

The following came from a presentation put together by Jody Bleyle and Jennifer Rondeau:

By the mid 1990’s, the Web had become the most successful distributed system in history. Roy Fielding was a computer scientist working on defining HTTP. He figured it would be a good idea to be able to describe what made the Web so successful so he and other people could use the information to make good decisions as the Web grew. So he set out to describe the architectural style of the Web. He called that architectural style “REST.” You’ll hear the parts of the style called “REST constraints” or “REST principles” or “REST design rules.” 

What is a RESTful API? An API that uses the REST architectural style (which is the foundation of the Web). REST is not a technology.  RESTful APIs use technologies built using REST principles. Web API designers want the same scalability and extensibility that makes the web itself so successful. So they decided to use the REST principles.

Absolutely marvelous! When would a normal (assuming a fairly loose definition of “normal”) user like me ever encounter REST?

Click here: http://www.forgerock.com (another browser window will be opened). There now you just used HTTP, an implementation of a protocol based on REST principles. Ready to go a bit further? Try this link: http://go.forgerock.com/Sales-and-Pricing-Inquiry.html (another browser window will also be opened).

You should see the SUBMIT button on the bottom of the form. If you filled out the form and clicked on SUBMIT, well pat yourself on the back because you just used a REST-based design style again. That's twice now and the day is young.

A design style you say. What other types of design styles are there?

Distributed computing has been forced to evolve over time due to different usage patterns. Back in the 80s and 90s distributed computing was confined to internal networks with a finite set of systems. With the arrival of the Internet, cloud-computing, mobile devices, and a global user community the old stuff just could not cut it. Technologies like DCOM and CORBA have been superseded by SOAP and REST. A few hundred desktop PCs communicating with a corporate server have been superseded by millions of smart devices (tablets, phones, watches, etc.) communicating with hundreds of thousands of applications and services.

Is it SOAP and REST -- or -- SOAP versus REST?

Generally versus. Plenty of content scattered across the web on the topic of REST vs SOAP. The general statement of “unless there is a compelling reason to use SOAP then use REST” is the guideline. Those who work directly with REST (developers) feel that a REST-based model is lighter weight and faster than SOAP. The trend for increased adoption of REST, regardless of the programming language used, has only gone up with the advent of mobile devices.​

There are still a few realms where SOAP has a role such as in back-end financial services or payment gateways (http://nordicapis.com/rest-vs-soap-nordic-apis-infographic-comparison/). But REST is the design style for practically everything else. Even though REST is not a standard per se, most RESTful implementations make use of standards such as HTTP, URI, JSON, and XML.

To remain competitive and relevant in an era of smart devices organizations need a fast and flexible model to build and deliver content and services. REST provides this model. Programmers can continue to program in their language of choice. IT Operations can continue to manage their environments to deliver the services and content over HTTP like they've been doing for years. While REST is not perfect it is certainly a good model for today's needs. What about tomorrow you ask. Working on the “Crystal Ball” app right now. And yes, it will be REST-based.

REST design principles? What are they?

Ok, you asked but join the club if the following make zero sense:

  • Client - server: Two separate components communicating with each other over a network. One provides a service (the server), the other requests it (the client). 
  • Stateless: Sessions last for one request. The server doesn’t know the client exists except when the client makes a request.
  • Cacheable: Server responses indicate whether or not they can be cached.
  • Layered system: Components like proxy servers and gateways can exist between the client and the resources.
  • Uniform interface:
    • Resources: Have URLs and are endpoints.
    • Representations: Resources aren’t transferred directly between client and server, representations of them at a particular state are transferred over HTTP.
    • Self-descriptive Messages: Requests and responses contain all the information needed to process them and decide what to do next.
    • Hypermedia as the Engine of State (HATEOAS): Responses contain links that let the client move through the application. The goal is for RESTful consumers to browse the web programmatically, without human intervention.
  • Code on demand: An optional constraint that allows clients to download code.

What?!? No, really, what are the REST design principles?

Well those listed above are the design principles but trying to make sense of that list is not pain free. First, REST means communication happens over HTTP which is the protocol used on the web. Your devices know how to communicate using HTTP. Networks and those who manage the network know HTTP very well. In fact IT operations already have security measures in place to accommodate HTTP communications which the REST model takes advantage of. Like most internal combustion engines know how to run on fuels derived from oil anything connected to the network knows how to use HTTP.

Client – Server means that your device and my service are very independent. My service does not care what programming language your app is written in. My service does not care if you are using your laptop, smartphone, or television game console. My service does not even care if you talk to it once and disappear forever or your device just won't be quiet. My service cares that you communicate using HTTP.

Likewise your device does not give a hoot about my service other than to use it. I'm just another stop on the information superhighway while you and your device are out on a joy ride. My service better be there and ready when you show up chattering away via HTTP.

You are the client; I'm the service. Let's just keep it that way. No need to get all involved and stuff.

Your devices knows that this URL (also known as a URI) – http://some-place-on-the-net – means a place to go and that this URL http://some-place-on-the-net/mylocation-weather is a specific location (it may also be referred to as a resource endpoint). In the human world you have a place - Carnation Farmer’s Market and a specific location - booth 32, vegetable bin labelled “eggplant”.

When your device goes to mylocation-weather endpoint the content will be in an understandable format. HTML, the formatting standard for web pages might be used to contain your weather information. The data could also be contained in other formats such as XML (HTML is a form of XML) or in JSON. HTML looks like this:

<!DOCTYPE html>
<html>
    <head>
        <meta content="text/html; charset=windows-1252" http-equiv="content-type">
        <title>My Weather Information</title>
        <meta content="The Weather Person" name="author">
    </head>
    <body>
        <p>Location= <span style="font-style: italic;">37.791035,-122.394768</span></p>
        <p>85F with sunny skies</p>
    </body>
</html>

We all should be glad that our devices understand this stuff.

In the weather example REST means your device will provide its present location to a service endpoint and that service endpoint in turn will provide the device with a weather forecast for the general location your device provided.

There are also defined verbs or actions that can take place between endpoints – your device and the weather service. The verb set is designed to be small and stateless. The verbs include GET, PUT, POST, DELETE, and a few others. The verb GET is probably what our device will use to GET the weather. We might see the device use PUT if you want to add a favorites to your list of weather forecasts. The PUT may simply be the GPS/map coordinates for the PUT to your favorites list. It may also be the verb behind the SUBMIT button used above.

But you, as the device owner, are oblivious to all this back and forth verb usage with bits of data traveling between the device and all the services it has a relationship with. Quite the social butterfly that device of yours.

And these relationships are stateless. Communications between the device and the endpoints cannot assume a history of past interactions is maintained even if that interaction happened seconds ago. As a rule maintaining state consumes computer resources like server memory and/or storage. Plus a service may actually be delivered by multiple computers. Your device may communicate with Server-A for one transaction and Server-Z for the next. In a landscape where the news of the world is delivered in sound bites so has communication been mimicked in technology. Your social butterfly device is more a flirt than a story teller. Speed dating in the computer scene you might say.

In a REST design style the client side (your device, your browser) also caches content. The weather does seem to change often at times but your weather app does not need to constantly request updates from the weather service. Periodic updates work fine, say hourly. Of course if a tornado warning is raised for your area then the app may elect to ask for updates from the service much more frequently as well as directions to the nearest storm shelter. At least we hope so!

What's it like being a service in this relationship?

Very nice you should ask. Not bad really. Sure there are millions of potential users all wanting content right this second but that's it. The client provides the context of their request and the service provides the response. The service does not care about what programming or scripting language the client is using. The service already knows communication will happen over HTTP. And once the service fulfills the client's request the service just moves on. Farewell. See ya later. Don't let the door hit you in your HTTP before you close the connection.

How secure is REST?

A REST-based implementation like HTTP can be secure. HTTP’s secure cousin HTTPS provides a way to transfer data between your device and the end service securely. HTTPS provides a way to encrypt data in transit. HTTPS has been used for years. In fact if you have done any type of online financial transaction (shopping, banking, stock trading, etc), or logged in, or viewed personal information, or… then you have used HTTPS.

A REST-based implementation can utilize existing HTTPS for secure communications. But security at the end points (your device, my service) is the responsibility of those managing those endpoints. You control who uses your devices (or at least you should). The service provider should control who can do what within their service. 

With anything technology-related there can be levels of complexity in implementing and managing it. Historically we have seen high-levels of apprehension when personal computers made their appearance in the workplace. Same was true of exposing corporate email. There were times when the only people I could email were others who worked for the same company.

The process of organizations becoming more “connected” was always a matter of implementing different technologies in different ways. There is always a learning curve and those whose raise concerns - both legitimate and some which are not. 

One thing for sure - for technology to be secure it must be implemented properly. ForgeRock does provide consultation in how best to secure a REST architecture based on an organization’s requirements

Am I hearing that REST is changing the way security is enforced?

The truly wonderful thing about REST is that Developers, Business Managers, Solution Providers, etc are fully vested in REST because of the design style. They understand it and have been leveraging it (via the web and HTTP) for years. One of the reasons REST design principles are adopted is because of the lack of constraints - which is fine until we move into production. 

Now security is required beyond just the communications channel. It needs to be a different security model than the old days, a model that works well with REST; a security model based on the identity of the user, the device, and the context of usage.

In the past, security was controlled at the firewall, at the perimeter of an organization's various network layers. Perimeters no longer exist (or have had so many holes knocked through them that they have lost their value). Now that control surface is at the identity. The control surface, the security of a REST-based design style, is all about you in context such as:

  • Information about you
  • What groups or communities are you a member of (or not a member of)
  • What are your roles (parent, manager, bill payer, etc)
  • Where do you fit within an organization
  • Who do you report to
  • What entitlements do you have (or not have)
  • What resources are you attempting to access
  • What time of day are you trying to access those resources
  • What type of device is being used (is it registered and are you the registered owner)
  • What part of the earth are you presently on (and were you there five minutes ago)
  • How did you actually log in
  • Have you done this before
  • Is what you are about to do risky – get the weather versus withdraw from a checking account

The REST design style, and the people that work with it, don't really want to be weighed down with all the identity and security stuff. At least not initially...

Which works very well for ForgeRock.

You don't say! How does the ForgeRock's solution add security to REST?

ForgeRock’s goal is to help enable an organization to establish and maintain secure, trusted relationships with identities both inside an organization as well as identities outside an organization all while utilizing a REST-based model. Our solution fully understands the REST model and can deliver much needed controls to services and their interfaces (APIs). Without changing the existing service ForgeRock can intercept HTTP traffic and mandate that the user authenticate. ForgeRock can then control access to the service based on policies. 

As the graphic below attempts to show that without some form of identity management and access control the services can only deliver generic content:

Unfortunately without a scalable identity and access management solution added to the above architecture each service is left to its own to put something in place. This can equate to a poor user experience, added costs to delivering a service, and the loss of valuable insight on how users are utilizing the service. For that personal touch the service needs to know who you are:

With ForgeRock in the picture there is now a common way for you to identify yourself (authentication) and to help the services understand what you can access based on your context (authorization). While the REST design style still maintains independence between the client (you) and the services, ForgeRock's solution adds a much needed layer of security to the endpoints. An organization can place ForgeRock's solution in the HTTP communications flow between the client (you, your device, your app, your browser) and the target service thereby enabling identity-based security without disabling the good things of REST.

The ForgeRock solution can control access to service endpoints such as http://weatherworld/at-myhouse. When a user attempts to access http://weatherworld/at-myhouse ForgeRock can require that the user authenticate and then, based on policies, either permit or deny the user access. Without changes to the client or the service ForgeRock enables great security at the service endpoint. Better security based on your identity can lead to a better relationship between you and your service providers.

ForgeRock's solution has been protecting HTTP-based endpoints for years. We have managed identities and the aspects of these identities at massive scale for years. With ForgeRock you can have your REST and security too.

See Also

NSA Guidelines for Implementation of REST


Known Issues


400 response when adding or updating resources via REST or Amster when the resource name contains forward slashes in AM/OpenAM (All versions)

The purpose of this article is to provide assistance if you receive a 400 Bad Request response when adding or updating resources via REST or Amster when the resource name contains URL encoded forward slashes. This issue only occurs if AM/OpenAM is deployed in the Apache Tomcat™ web application container and affects resources such as SAML2 entities, policy names and application names.

Symptoms

You see a 400 Bad Request response when you make a PUT call (REST) or a create call (Amster) with a resource name that contains URL encoded forward slashes:

{"code":400,"reason":"Bad Request"}

For example: 

  • REST - you will see this response when adding a SAML2 entity via REST:
    $ curl -X PUT -H "iPlanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" -H "Content-Type: application/json" -d '{
         "metadata": "<?xml ...",
         "entityConfig": "<?xml ...",
    }' 'http://host1.example.com:8080/openam/json/realms/root/realm-config/federation/entityproviders/saml2/http%3A%2F%2Fidp.acme.com%3A8080%2Fopenam' 
    
    
    < HTTP/1.1 400 Bad Request
    < Server: Apache-Coyote/1.1
    < Content-Length: 0
    < Connection: close
  • Amster - you will see this response when adding a SAML2 entity via Amster:
    $ create Saml2Entity --realm / --id http%3A%2F%2Fidp.acme.com%3A8080%2Fopenam --body '{"metadata": "<?xml ...","entityConfig": "<?xml ..."}'
    
    [main] ERROR org.forgerock.amster.org.forgerock.openam.sdk.http.DefaultErrorHandler - Unhandled client error: [Status: 400 Bad Request]
    Failed to execute the 'create' command. 400 Bad Request
    

Recent Changes

N/A

Causes

Tomcat only accepts path delimiters (/ and \) if they are URL encoded and the org.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH property is set to true. This property is set to false by default, which means these path delimiters are not permitted.

See Installation Guide › Preparing Apache Tomcat and Tomcat Documentation for further information.

Solution

This issue can be resolved by setting the property using the CATALINA_OPTS variable either in Tomcat's startup scripts (for example, setenv.sh or catalina.properties) or as system parameter.

Caution

It is strongly recommended that you do not set this option when running AM/OpenAM in production as it introduces a security risk. When Tomcat is deployed behind a reverse proxy, this setting can expose you to a directory traversal security vulnerability (CVE-2007-0450); see Apache Tomcat 6.x Vulnerabilities for further information. Therefore, it is preferable to avoid resource names that contain slashes. If this is not possible, see How do I safely enable the org.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH setting in AM/OpenAM (All versions)? for further information.

Startup scripts

  1. Add the following line to the startup script, for example the setenv.sh file:
    export CATALINA_OPTS="‑Dorg.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH=true"
  2. Restart the web container.

System parameter

  • On Linux® and Unix® systems:
    $ export CATALINA_OPTS= \ "-Dorg.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH=true"
    $ startup.sh
  • On Microsoft® Windows® systems:
    C:\> set CATALINA_OPTS= ^ "-Dorg.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH=true"
    C:\> startup.bat
    

You will now be able to add resources via REST or Amster providing you URL encode (%2F) any forward slashes in the resource name, for example:

$ curl -X PUT -H "iPlanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" -H "Content-Type: application/json" -v -d '{
     "metadata": "<?xml ...",
     "entityConfig": "<?xml ...",
}' 'http://host1.example.com:8080/openam/json/realms/root/realm-config/federation/entityproviders/saml2/http%3A%2F%2Fidp.acme.com%3A8080%2Fopenam'

*   Trying 127.0.0.1...
* Connected to host1.example.com (127.0.0.1) port 8080 (#0)
> PUT /openam/json/realms/root/realm-config/federation/entityproviders/saml2/http%3A%2F%2Fidp.acme.com%3A8080%2Fopenam HTTP/1.1
...
< HTTP/1.1 200 OK
...
<
{"_id":"http://idp.acme.com:8080/openam","_rev":"1553138821","metadata":"<?xml version=….”,”entityConfig":"<?xml version=“…,
”* Connection #0 to host host1.example.com left intact
_type":{"_id":"saml2","name":"Entity Descriptor ","collection":true}}

See Also

400 response with json/users endpoint in AM/OpenAM (All versions) if username contains forward slash

FAQ: REST API in AM/OpenAM

Using the REST API in AM/OpenAM

Using Amster in AM

Related Training

N/A

Related Issue Tracker IDs

OPENAM-11798 (REST interface for SAML2 config does not accept entity IDs that are URLs)


400 response with json/users endpoint in AM/OpenAM (All versions) if username contains forward slash

The purpose of this article is to provide assistance if you receive a 400 Bad Request response when the username contains a URL encoded forward slash (%2F) and you make a REST call to the json/users endpoint. You will see a 404 Not Found response instead if the forward slash is not encoded. This issue only occurs if AM/OpenAM is deployed in the Apache Tomcat™ web application container.

Symptoms

URL Encoded forward slash

You see a 400 Bad Request message when you make a call to the json/users endpoint if the username contains a URL encoded forward slash (%2F). The exact message will vary depending on what you are trying to do, but typically you will see:

{"code" : 400,"reason" : "Bad Request","message" : "Resource name '/users/user/1' contains empty path elements"}

If you are trying to change the user's password, for example using a URL such as: http://host1.example.com:8080/openam/json/users/user%2F1?_action=changePassword, you will see the following message instead:

{"code":400,"reason":"Bad Request","message":"Invalid Password"}

Non-encoded forward slash

If you attempt to make a call to the json/users endpoint with a username that contains a forward slash (not encoded), you will see the following response:

{"code":404,"reason":"Not Found"}

Recent Changes

N/A

Causes

Tomcat only accepts path delimiters (/ and \) if they are URL encoded and the org.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH property is set to true. This property is set to false by default, which means these path delimiters are not permitted.

Solution

This issue can be resolved as follows:

  1. Add the following line to the setenv.sh file:
    export CATALINA_OPTS="‑Dorg.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH=true"
  2. Restart the web container.

You will now be able to make calls to the json/users endpoint with a username that contains a forward slash providing it is URL encoded (%2F).

Caution

It is strongly recommended that you do not set this option when running AM/OpenAM in production as it introduces a security risk. When Tomcat is deployed behind a reverse proxy, this setting can expose you to a directory traversal security vulnerability (CVE-2007-0450); see Apache Tomcat 6.x Vulnerabilities for further information. Therefore, it is preferable to avoid usernames that contain slashes. If this is not possible, see How do I safely enable the org.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH setting in AM/OpenAM (All versions)? for further information.

See Also

400 response when adding or updating resources via REST or Amster when the resource name contains forward slashes in AM/OpenAM (All versions)

How do I change what characters are permitted in user names in AM/OpenAM (All versions) for authentication purposes?

FAQ: REST API in AM/OpenAM

Using the REST API in AM/OpenAM

Related Training

N/A

Related Issue Tracker IDs

N/A


Minimum password length is 8 error in AM (All versions) when updating identities using the REST API

The purpose of this article is to provide assistance if you encounter a "Minimum password length is 8" error when updating identities using the REST API in AM, even though the user's password meets this requirement. This issue also occurs when unlocking a user's account.

Symptoms

The following error is shown when updating identities using the REST API even though the user's password is at least 8 characters:

{"code":404,"reason":"Not Found","message":"Minimum password length is 8."}

For example, if you use a REST call such as:

  • To unlock a user's account:
    $ curl -X PUT -H "iPlanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" -H "Content-type: application/json" -H "Accept-API-Version: resource=3.0, protocol=1.0" -d'{
        "inetUserStatus": "Active"
    }' http://host1.example.com:8080/openam/json/realms/root/users/demo
  • To update a user's email address:
    $ curl -X PUT -H "iPlanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" -H "Content-type: application/json" -H "Accept-API-Version: resource=3.0, protocol=1.0" -d'{
        "mail": "demo@example.com" 
    }' http://host1.example.com:8080/openam/json/realms/root/realms/employees/users/demo

Recent Changes

Installed, or upgraded to AM 5 or later.

Causes

The Default Protocol Version setting for a new install defaults to LATEST, but this setting does not work as expected per known issue: OPENAM-11052 (Minimum password length is 8 error in AM 5.0 when updating identities using the REST API).

See Development Guide › REST API Versioning for further information on REST versioning.   

Solution

The following are suggested workarounds to resolve this issue; either include the Accept-API-Version header in your REST call or set the Default Protocol Version to Oldest.

Include Accept-API-Version header

You can include the Accept-API-Version header in your REST call, for example:

$ curl -X PUT -H "iPlanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" -H "Content-type: application/json" -H "Accept-API-Version: resource=3.0, protocol=1.0" -d'{
    "inetUserStatus": "Active"
}' http://host1.example.com:8080/openam/json/realms/root/users/demo

Set Default Protocol Version

You can set the Default Protocol Version using either the console or ssoadm:

  • Console: navigate to: Configure > Global Services > REST APIs > Default Protocol Version and select OLDEST. 
  • ssoadm: enter the following command:
    $ ./ssoadm set-attr-defs -s RestApisService -t Global -u [adminID] -f [passwordfile] -a openam-rest-apis-default-protocol=Oldest
    replacing [adminID] and [passwordfile] with appropriate values.

See Also

FAQ: REST API in AM/OpenAM

Using the REST API in AM/OpenAM

Related Training

N/A

Related Issue Tracker IDs

OPENAM-11052 (Minimum password length is 8 error in AM 5.0 when updating identities using the REST API)


REST API calls fail after upgrading to OpenAM 12.x or 13.x

The purpose of this article is to provide assistance if your REST API calls (that worked previously) fail after upgrading to OpenAM 12.x or 13.x. This includes requests made indirectly; for example, when you create a REST STS instance in the OpenAM console.

Symptoms

The REST call, or OpenAM functionality that has an underlying REST request, fails after upgrading to OpenAM 12.x or 13.x. The same behavior worked in a previous release.

Example failed request 

The following example shows a REST call and the possible failed responses:

$ curl --request POST --header "iPlanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" --header "Content-Type: application/json" --data '{"currentpassword":"changeit","userpassword":"newpassword"}' http://openam.example.com:8080/openam/json/users/user.0?_action=changePassword

Which can result in:

{"code":501,"reason":"Not Implemented","message":"Actions are not supported for resource instances"}

Or:

{"code":404,"reason":"Not Found","message":"User not found"}

Example failed functionality with underlying REST request

When adding a REST STS instance in the OpenAM console, you may receive the following error:

HTTP Status 500 - AMSetupFilter.doFilter

Recent Changes

Upgraded to OpenAM 12.x or 13.x.

Causes

The resource version associated with the REST request is incompatible with the endpoint being called and OpenAM release combination.  

Since OpenAM 12.0.0, REST API features have been assigned version numbers to allow for compatibility between OpenAM releases. The version number of a feature increases when OpenAM introduces a non-backwards-compatible change that affects clients making use of the feature. Versioning is provided for the resource and protocol elements. See OpenAM Developer's Guide › Developing Client Applications › REST API Versioning for further information on versioning.

Both OpenAM 12.x and 13.x support protocol version 1.0; supported resource versions vary according to the endpoint and the release you are using. You should check the Supported resource Versions table for the relevant release of OpenAM:

Solution

This issue can be resolved by ensuring you use a resource version that is appropriate to the endpoint and OpenAM release you are using.

You can configure a global setting to determine version compatibility and/or specify the versions in your REST request.

Global setting

You can configure the global setting using either the OpenAM console or ssoadm:

  • OpenAM 13.5 console: navigate to: Configure > Global Services > REST APIs > Default Version and select the appropriate option. 
  • Pre-OpenAM 13.5 console: navigate to: Configuration > Global > REST APIs > Default Version and select the appropriate option. 
  • ssoadm: enter the following command:
    $ ./ssoadm set-attr-defs -s RestApisService -t Global -u [adminID] -f [passwordfile] -a openam-rest-apis-default-version=[version]
    replacing [adminID], [passwordfile] and [version] with appropriate values, where [version] is LATEST, OLDEST or NONE.

The options available are:

  • LATEST: The latest available supported version of the API is used. This is the preset default for new installations of OpenAM.
  • OLDEST: The oldest available supported version of the API is used. This is the preset default for upgraded OpenAM instances.
  • NONE: If a version is not specified in the request, it will not be defaulted. 
Caution

If you select NONE for the global setting, you must always specify the version in the REST request. If the version is not specified the request will not be handled and will results with a 400 Bad Request error.

You can include the Accept-API-Version header in your REST call to specify the versions. For example, to include resource version 2.0 and protocol version 1.0 you would include the following header:

"Accept-API-Version: resource=2.0, protocol=1.0"

For example:

$ curl --request POST --header "iPlanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" --header "Accept-API-Version: resource=2.0, protocol=1.0" --header "Content-Type: application/json" --data '{"currentpassword":"changeit", "userpassword":"newpassword"}' http://openam.example.com:8080/openam/json/users/user.0?_action=changePassword

 See OpenAM Developer's Guide › Developing Client Applications › Specifying an Explicit REST API Version for further information.

See Also

FAQ: REST API in AM/OpenAM

OpenAM Developer's Guide › Developing Client Applications › REST API Versioning

OpenAM Administration Guide › Configuring REST APIs

Related Training

N/A

Related Issue Tracker IDs

OPENAM-8380 (REST API Versioning, How to upgrade Rest API version if one upgrade from OpenAM 11x to 12x)


Unable to login to OpenAM console 12.x and 13.x or access REST API after changing the Federation Signing Key

The purpose of this article is to provide assistance if you cannot log into the OpenAM console 12.x and 13.x (XUI) or access the REST API after changing the Signing Key or certificate alias for SAML2 or OAuth, and you receive a code 500 "Internal Server Error" "The server encountered an unexpected condition which prevented it from fulfilling the request".

Symptoms

When attempting to access the OpenAM console or the REST API, the following error is seen:

code: 500 
reason: "Internal Server Error" 
message: "The server encountered an unexpected condition which prevented it from fulfilling the request" 

If you are attempting to log into the OpenAM console, you will see the following message after the Internal Server Error has flashed up:

Unable to login to OpenAM

This issue can also be seen in the HTTP container logs. For example, an error similar to the following is shown in the catalina.out log if you are using Apache Tomcat™:

WARNING: Exception or error caught in server resource 
Internal Server Error (500) - The server encountered an unexpected condition which prevented it from fulfilling the request 
at org.restlet.resource.ServerResource.doHandle(ServerResource.java:517) 
at org.restlet.resource.ServerResource.post(ServerResource.java:1216) 
at org.restlet.resource.ServerResource.doHandle(ServerResource.java:592) 
at org.restlet.resource.ServerResource.doNegotiatedHandle(ServerResource.java:649) 
at org.restlet.resource.ServerResource.doConditionalHandle(ServerResource.java:348) 
at org.restlet.resource.ServerResource.handle(ServerResource.java:952) 
at org.restlet.resource.Finder.handle(Finder.java:246) 
at org.forgerock.openam.rest.service.VersionRouter.handle(VersionRouter.java:139) 
at org.forgerock.openam.rest.service.ServiceRouter$RestletWrapper.handle(ServiceRouter.java:162) 
...
Caused by: java.lang.NullPointerException
	at org.forgerock.openam.forgerockrest.authn.AuthIdHelper.generateAuthId(AuthIdHelper.java:174)
	at org.forgerock.openam.forgerockrest.authn.AuthIdHelper.createAuthId(AuthIdHelper.java:103)
	at org.forgerock.openam.forgerockrest.authn.RestAuthenticationHandler.createJsonCallbackResponse(RestAuthenticationHandler.java:320)
	at org.forgerock.openam.forgerockrest.authn.RestAuthenticationHandler.processAuthentication(RestAuthenticationHandler.java:246)
	at org.forgerock.openam.forgerockrest.authn.RestAuthenticationHandler.authenticate(RestAuthenticationHandler.java:160)
	at org.forgerock.openam.forgerockrest.authn.RestAuthenticationHandler.initiateAuthentication(RestAuthenticationHandler.java:93)
	at org.forgerock.openam.forgerockrest.authn.restlet.AuthenticationServiceV1.authenticate(AuthenticationServiceV1.java:133)
	at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
	at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39)
	at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25)
	at java.lang.reflect.Method.invoke(Method.java:597)
	at org.restlet.resource.ServerResource.doHandle(ServerResource.java:503)
	... 70 more

If you are attempting to access the REST API, you will also see the following error in the restAuthenticationFilter log file:

restAuthenticationFilter:09/10/2015 04:27:19:029 PM CEST: Thread[http-bio-8080-exec-30,5,main] 
Access Denied 
org.forgerock.jaspi.exceptions.JaspiAuthException: Access Denied 
at org.forgerock.jaspi.runtime.context.ContextHandler.handleCompletion(ContextHandler.java:131) 
at org.forgerock.jaspi.runtime.context.JaspiServerAuthContext.validateRequest(JaspiServerAuthContext.java:244) 
at org.forgerock.jaspi.runtime.JaspiRuntime.processMessage(JaspiRuntime.java:160) 
at org.forgerock.jaspi.JaspiRuntimeFilter.doFilter(JaspiRuntimeFilter.java:131) 
at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:243)
at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:210) 
at org.forgerock.openam.validation.ResponseValidationFilter.doFilter(ResponseValidationFilter.java:44) 
...
Caused by: org.forgerock.json.resource.PermanentException: Access Denied
        at org.forgerock.json.resource.ResourceException.getException(ResourceException.java:251)
        at org.forgerock.json.resource.ResourceException.getException(ResourceException.java:181)
        at org.forgerock.jaspi.runtime.context.ContextHandler.handleCompletion(ContextHandler.java:129)
        ... 25 more

Recent Changes

Imported a new signing key into the keystore and changed the certificate alias for SAML2 or OAuth.

Causes

The default 'test' certificate alias used for SAML2 and OAuth signing keys is also used by the XUI and for REST authentication as of OpenAM 12.x. 

The procedure in the OpenAM 12 Admin Guide: To Change the Signing Key for Federation describes creating a new keystore.jks and replacing the default keystore.jks with the newly created one. This process removes the default 'test' alias and replaces it with a newly created alias. If you follow this procedure but do not change the certificate alias used for authentication, you will not be able to log into the OpenAM console with XUI enabled or make REST calls.

Solution

This issue can be resolved by updating the certificate alias to match the alias of the new signing key using either the OpenAM console or ssoadm. You can either do this globally or per realm:

Globally:

  • OpenAM 13.5 console: navigate to: Configure > Authentication > Core Attributes > Security > Persistent Cookie Encryption Certificate Alias and enter the alias of the new signing key.
  • OpenAM 13 console: navigate to: Configuration > Authentication > Core > Security > Persistent Cookie Encryption Certificate Alias and enter the alias of the new signing key.
  • Pre-OpenAM 13 console: navigate to: Configuration > Authentication > Core > Security > Organization Authentication Certificate Alias and enter the alias of the new signing key.
  • ssoadm: enter the following command:
    $ ./ssoadm set-attr-defs -s iPlanetAMAuthService -t organization -u [adminID] -f [passwordfile] -a iplanet-am-auth-key-alias=[signingkeyalias]
    replacing [adminID], [passwordfile] and [signingkeyalias] with appropriate values.

Realm:  

  • OpenAM 13 and later console: navigate to: Realms > [Realm Name] > Authentication > Settings > Security > Persistent Cookie Encryption Certificate Alias and enter the alias of the new signing key.
  • Pre-OpenAM 13 console: navigate to: Access Control > [Realm Name] > Authentication > All Core Settings > Security > Organization Authentication Certificate Alias and enter the alias of the new signing key.
  • ssoadm: enter the following command:
    $ ./ssoadm set-realm-svc-attrs -s iPlanetAMAuthService -e [realmname] -u [adminID] -f [passwordfile] -a iplanet-am-auth-key-alias=[signingkeyalias]
    replacing [realmname], [adminID], [passwordfile] and [signingkeyalias] with appropriate values.
Note

You must restart the web application container in which OpenAM runs to apply these configuration changes.

See Also

How do I change the Signing Key for Federation in OpenAM 12.x and 13.x?

Login to AM/OpenAM console (All versions) fails for amadmin user

FAQ: SAML certificate management in AM/OpenAM

Related Training

N/A

Related Issue Tracker IDs

OPENAM-6003 (value for 'iplanet-am-auth-key-alias' should be checked when saving)

OPENAM-6824 (Procedure To Change the Signing Key for Federation results in being locked out of XUI)


Authentication fails in OpenAM 12.0.0, 12.0.1, 12.0.2, 12.0.3 and 13.0 if username or password has non-English characters in a REST call

The purpose of this article is to provide assistance if you receive a 401 Unauthorized response when trying to authenticate to OpenAM using the /json/authenticate REST endpoint, and have non-English or UTF-8 characters in your username or password.

Symptoms

Authenticating to OpenAM using the /json/authenticate REST endpoint fails if you have non-English or UTF-8 characters in your username or password. For example:

$ curl -X POST -H "X-OpenAM-Username: ɗëɱø" -H "X-OpenAM-Password: changeitÖ" -H "Content-Type: application/json" http://host1.example.com:8080/openam/json/authenticate

Example responses:

{"code":401,"reason":"Unauthorized","message":"Authentication Failed!!"}

{"code":401,"reason":"Unauthorized","message":"Access Denied"} 

The same user can authenticate to OpenAM in a browser, which proves their credentials are correct.

Recent Changes

N/A

Causes

The HTTP headers used to submit usernames and passwords in a REST call do not support any encoding, which prevents the use of non-English characters. Therefore, when non-English characters are used, the authentication call fails.

Solution

This issue can be resolved by upgrading to OpenAM 12.0.4, or OpenAM 13.5 and later; you can download this version from BackStage.

You can then include UTF-8 usernames or passwords in your REST calls as base-64 encoded values as described in Authentication and Single Sign-On Guide › Authentication and Logout.

Workaround

You can authenticate using callbacks in your REST call, which are passed in the POST body rather than using headers to authenticate. This method is the same as the one used when logging in via the XUI in a browser. For example, you could use a REST call such as:

$ curl -X POST -H "Content-Type: application/json" -d '{"callbacks":[{"type":"NameCallback","input":[{"name":"IDToken1","value":"ɗëɱø"}]},{"type":"PasswordCallback","input":[{"name":"IDToken2","value":"changeitÖ"}]}]}' http://host1.example.com:8080/openam/json/authenticate
Note

This workaround is only supported for a single stage authentication process as explained in OPENAM-3335 (REST authentication inconsistency with ZPL). For example, if you have a chain where the Persistent Cookie module is SUFFICIENT followed by the DataStore module set to REQUIRED, this method will not work as the authentication process will not know which module the username and password applies to. 

See Also

FAQ: REST API in AM/OpenAM

Using the REST API in AM/OpenAM

How do I change what characters are permitted in user names in AM/OpenAM (All versions) for authentication purposes?

Authentication and Single Sign-On Guide › About the REST API › Authentication and Logout

Related Training

N/A

Related Issue Tracker IDs

OPENAM-3750 (REST authentication failed if unicode/utf8 login/password)


Policy import fails in OpenAM 13.0 with Invalid resource type null message

The purpose of this article is to provide assistance if you receive an "Invalid resource type null, must be one from the set defined against the containing application" message when trying to import a policy in OpenAM 13.0 via REST or ssoadm. The policy import fails in the OpenAM console without a message.

Symptoms

The following error is shown when attempting to import a policy in XACML format using ssoadm:

com.sun.identity.entitlement.EntitlementException: Invalid resource type null, must be one from the set defined against the containing application.

The following response is received when attempting to import a policy in XACML format using the REST API:

{"code":400,"reason":"Bad Request","message":"Invalid resource type null, must be one from the set defined against the containing application."}

If you try to import a policy via the OpenAM console, the policy is not imported but you do not get a message saying it failed. 

Recent Changes

Installed, or upgraded to OpenAM 13.0.

Causes

OpenAM 13 introduced a new concept - Resource Types which form part of describing policies in OpenAM 13. The resource types are missing from the xml file for the exported policy. The existing resource type is not associated with the imported policy and as such the policy fails validation

Solution

This issue can be resolved by upgrading to OpenAM 13.5 or later; you can download this version from BackStage.

Workaround

Alternatively, this issue can be resolved by manually re-creating the policy using either the OpenAM console or the REST API.

If you want to use the REST API, see How do I create a policy in AM/OpenAM (All versions) using the REST API? for details on successfully creating a policy, including retrieving the missing resource types. This article also provides a Postman collection  to make it easier to create policies.

See Also

How do I export and import policies in AM/OpenAM (All versions)?

Related Training

N/A

Related Issue Tracker IDs

OPENAM-6013 (Resource types are missing in XACML exported policy and it is not possible to import it)

OPENAM-8495 (XACML Import - Existing resource type not being associated with the imported policy)


400 response using REST API to update a user's password in OpenAM 11.0.0, 11.0.1, 11.0.2 and 12.0.0

The purpose of this article is to provide assistance if you encounter a 400 Bad Request: Invalid Password response when using the REST API to update a user's password in OpenAM 11.0.0, 11.0.1, 11.0.2 and 12.0.0, even though the old user password submitted is valid. This issue occurs when you have an authentication chain that requires more than a username and password to authenticate and uses a module such as the Adaptive Risk module.

Symptoms

The following response is received when updating a user's password using the REST API, even though the old user password submitted is valid:

{"code":400,"reason":"Bad Request","message":"Invalid Password"}

Recent Changes

Upgraded to OpenAM 11.0.0, 11.0.1, 11.0.2 or 12.0.0.

Implemented an authentication chain that requires more than a username and password to authenticate, for example, requires a historical IP address for the Adaptive Risk module.

Causes

The password validation mechanism (using the IdentityResource#checkValidPassword method) tries to authenticate the user in the realm using the default chain for the realm; this fails when the REST call is made if authentication requires anything more than the username and password (olduserpassword) because the REST interface does not have access to the authentication context. Therefore, this error is received regardless of whether the olduserpassword is correct or not.

Solution

This issue can be resolved by upgrading to OpenAM 11.0.3, or OpenAM 12.0.1 or later; you can download this from BackStage.

Alternatively, you could remove the additional authentication steps from the authentication chain, for example, remove the Adaptive Risk module. However this approach is not recommended as you will lose the functionality associated with the additional authentication steps.

See Also

OpenAM Developer's Guide › RESTful Identity and Realm Management Services › Updating Identities

Related Training

N/A

Related Issue Tracker IDs

OPENAM-3877 (Changing password through new REST endpoint fails if default AuthN chain needs more than just the password to authenticate)


Copyright and TrademarksCopyright © 2018 ForgeRock, all rights reserved.

This content has been optimized for printing.

Loading...