How To
ForgeRock Identity Platform
Does not apply to Identity Cloud

How does a user change their own password in IDM (All versions) using the REST API?

Last updated Apr 8, 2021

The purpose of this article is to provide information on how a user can change their own password in IDM using the REST API. The method differs if IDM is protected by AM depending on which authentication method is used.


Overview

A user can change their own password as described in this article. The method used depends on whether IDM is protected by AM, and if so which authentication module is used.

Note

Please observe the following when constructing REST calls for AM:

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

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

Changing own password (non-integrated setup)

When IDM is standalone, a user can change their own password as follows using either a POST or PATCH request:

  1. Authenticate using the login endpoint to return your user id. For example:
    • IDM 7 and later: $ curl -X GET -H "X-OpenIDM-Username: jdoe" -H "X-OpenIDM-Password: password" -H "Accept-API-Version: resource=1.0" http://localhost:8080/openidm/info/login
    • Pre-IDM 7: $ curl -X GET -H "X-OpenIDM-Username: jdoe" -H "X-OpenIDM-Password: password" http://localhost:8080/openidm/info/login

Example response (where user id = 505d8485-e11b-4384-8309-2e9b157a78d9): {"_id":"login","authenticationId":"jdoe","authorization":{"userRolesProperty":"authzRoles","component":"managed/user","authLogin":false,"authenticationIdProperty":"username","roles":["internal/role/openidm-authorized"],"ipAddress":"0:0:0:0:0:0:0:1","authenticationId":"jdoe","protectedAttributeList":["password"],"id":"505d8485-e11b-4384-8309-2e9b157a78d9","moduleId":"MANAGED_USER","queryId":"credential-query"}}

  1. Update your password using either a POST or PATCH request, ensuring you pass your user id in the URL. For example:
    • POST:
      • IDM 7 and later: $ curl -X POST -H "Content-Type: application/json" -H "X-OpenIDM-Username: jdoe" -H "X-OpenIDM-Password: oldPassword" -H "Accept-API-Version: resource=1.0" -H "X-OpenIDM-Reauth-Password:oldPassword" -H "X-HTTP-Method-Override: PATCH" -d '[{"operation":"replace","field":"password","value":"newPassw0rd"}]' http://localhost:8080/openidm/managed/user/505d8485-e11b-4384-8309-2e9b157a78d9 Pre-IDM 7: $ curl -X POST -H "Content-Type: application/json" -H "X-OpenIDM-Username: jdoe" -H "X-OpenIDM-Password: oldPassword" -H "X-OpenIDM-Reauth-Password:oldPassword" -H "X-HTTP-Method-Override: PATCH" -d '[{"operation":"replace","field":"password","value":"newPassw0rd"}]' http://localhost:8080/openidm/managed/user/505d8485-e11b-4384-8309-2e9b157a78d9
    • PATCH:
      • IDM 7 and later: $ curl -X PATCH-H "Content-Type: application/json" -H "X-OpenIDM-Username: jdoe" -H "X-OpenIDM-Password: oldPassword" -H "Accept-API-Version: resource=1.0" -H "X-OpenIDM-Reauth-Password:oldPassword" -d '[{"operation":"replace","field":"password","value":"newPassw0rd"}]' http://localhost:8080/openidm/managed/user/505d8485-e11b-4384-8309-2e9b157a78d9 Pre-IDM 7: $ curl -X PATCH-H "Content-Type: application/json" -H "X-OpenIDM-Username: jdoe" -H "X-OpenIDM-Password: oldPassword" -H "X-OpenIDM-Reauth-Password:oldPassword" -d '[{"operation":"replace","field":"password","value":"newPassw0rd"}]' http://localhost:8080/openidm/managed/user/505d8485-e11b-4384-8309-2e9b157a78d9

Changing own password (integration using OAUTH_CLIENT or OPENID_CONNECT module)

When IDM is protected by AM using either the OAUTH_CLIENT or OPENID_CONNECT module, a user must follow these steps to change their password:

  1. Send a request to IDM: $ curl -X POST -H 'Content-Type: application/json' -H 'X-OpenIDM-Username: anonymous' -H 'X-OpenIDM-Password: anonymous' -H 'X-OpenIDM-NoSession: true' -d '{ "provider":"OPENAM", "landingPage":"http://idm.example.net:8081/#login/&oauthReturn=true&provider=OPENAM&gotoURL=%23" }' 'http://idm.example.net:8081/openidm/identityProviders?_action=getAuthRedirect'Example response; this includes a long token value which you should save for step 4: {"redirect":"http://host1.example.com:8080/openam/oauth2/authorize?nonce=74881rqrqjtw4cq7exjhzb9tjeo4vbc&response_type=code&client_id=openidm&redirect_uri=http://idm.example.net:8081/oauthReturn/&scope=openid&state=99iu3pclpz8ub9buogfp4geznl0ax5c","token":"ey...<long token>...cnF0"}
  2. Send the following request to authenticate to AM, note the AM username and password: $ curl -X POST -H "Content-Type: application/json" -H "X-OpenAM-Username: jdoe" -H "X-OpenAM-Password: password" -H "Accept-API-Version: resource=2.1" 'http://host1.example.com:8080/openam/json/realms/root/authenticate'Example response: {"tokenId":"aXuK02gnIwq_2rJacbNqob_QWC8.*AAJTSQACMDEAAlNLABxZeU5DZGhPTm8yVlBBVEx5eW9DZWpIVzh6R0k9AAJTMQAA*","successUrl":"/openam/console","realm":"/"}
  3. Send the following request to AM to obtain an authorization token, ensuring you replace the nonce and state values with the ones returned in step 1: $ curl -v -H 'Cookie: iPlanetDirectoryPro=aXuK02gnIwq_2rJacbNqob...JTMQAA*' 'http://host1.example.com:8080/openam/oauth2/authorize?nonce=74881rqrqjtw4cq7exjhzb9tjeo4vbc&response_type=code&client_id=openidm&redirect_uri=http%3A%2F%2Fidm.example.net%3A8081%2FoauthReturn%2F&scope=openid&state=99iu3pclpz8ub9buogfp4geznl0ax5c'Example response (note the Location header): < HTTP/1.1 302 Found < X-Frame-Options: SAMEORIGIN  < Pragma: no-cache  < Cache-Control: no-store  < Date: Mon, 15 Jan 2018 16:00:25 GMT  < Accept-Ranges: bytes  < Location: http://idm.example.net:8081/oauthReturn/?code=3d69820b-452a-49a9-bf55-22c4c3c588ac&scope=openid&iss=http%3A%2F%2Fhost1.example.com%3A8080%2Fopenam%2Foauth2&state=99iu3pclpz8ub9buogfp4geznl0ax5c&client_id=openidm  < Server: Restlet-Framework/2.3.4  < Vary: Accept-Charset, Accept-Encoding, Accept-Language, Accept  < Content-Length: 0
  4. Send the following request to IDM, ensuring you set the X-OpenIDM-DataStoreToken header to the long token value returned in step 1, replace the code value with the one returned in step 3 and replace the state value with the one returned in step 1: $ curl -X POST -H 'Content-Type: application/json' -H 'X-OpenIDM-Username: anonymous' -H 'X-OpenIDM-Password: anonymous' -H 'X-OpenIDM-NoSession: true' -H 'X-OpenIDM-DataStoreToken: ey...<long token>...cnF0' -d '{"code":["3d69820b-452a-49a9-bf55-22c4c3c588ac"],"scope":["openid"],"iss":["http://host1.example.com:8080/openam/oauth2"],"state":["99iu3pclpz8ub9buogfp4geznl0ax5c"],"client_id":["openidm"]}' 'http://idm.example.net:8081/openidm/identityProviders?_action=handlePostAuth'Example response: {"landingPage":"http://idm.example.net:8081/#login/&oauthReturn=true&provider=OPENAM&gotoURL=%23","data":null,"token":"eyJ...<BIG JWT>...2hk"}
  5. Send the following request to IDM, ensuring you set the X-OpenIDM-DataStoreToken header to the JWT value returned in step 4: $ curl -H "X-OpenIDM-OAuth-Login: true" -H "X-OpenIDM-DataStoreToken: eyJ...<BIG JWT...2hk" -H "Referer: http://openam.example.com:8081/" -H "X-Requested-With: XMLHttpRequest" -H "Content-Type: application/json" -H "X-OpenIDM-Reauth-Password:OldPassword" -X POST -H "X-HTTP-Method-Override: PATCH" -d '[{"operation":"replace","field":"password","value":"NewPassw0rd"}]' http://localhost:8081/openidm/managed/user/b4acc4e1-365d-4684-85e1-09c27e26725bSuccessful response: {"_id":"2b18e91f-9d99-47a2-bbd6-77dadfe995a4","_rev":"2","displayName":"jdoe","givenName":"john","mail":"jdoe@example.com","telephoneNumber":"1234","sn":"doe","userName":"jdoe","kbaInfo":[{"answer":{"$crypto":{"type":"salted-hash","value":{"algorithm":"SHA-256","data":"9NFvqidMytCEgCoF3kpFK4Hk5pdjJcvCgp4oO2nPkWlkgdPKzaM8LA9/65Ef6KuV"}}},"questionId":"1"},{"answer":{"$crypto":{"type":"salted-hash","value":{"algorithm":"SHA-256","data":"HRsHVADg9Rfxv5UQVLkkcxoyZwXRuchO14ZY9vVL0H67PHHCCy7/fZIy2yC+8xnH"}}},"questionId":"2"}],"accountStatus":"active","effectiveRoles":[],"effectiveAssignments":[]}

See Also

How does the OIDC authorization flow work when IDM 5.5.x, 6.x or 7.x is integrated with AM?

Security Guide › Secure Password Changes

Object Modeling Guide › Managed Users

Related Training

N/A

Related Issue Tracker IDs

N/A


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