Deprecated REST APIs

This appendix provides information about REST APIs deprecated in OpenAM 13.5.2-15.

Deprecated Session Information APIs

Interface Stability: Deprecated

To check the maximum remaining time (in seconds) of a session, perform an HTTP POST to the resource URL, /json/sessions/, using the getMaxTime action as shown in the following example:

$ curl \
 --request POST \
 --header "Content-Type: application/json" \
 --header "iplanetDirectoryPro: AQIC5w...NTcy*" \
 http://openam.example.com:8080/openam/json/sessions/?_action=getMaxTime&tokenId=BXCCq...NX*1*

{"maxtime":7022}

The getMaxTime action has been deprecated in favor of getTimeLeft. For more information, see "Obtaining Information About Sessions".

Deprecated Self-Service APIs

Interface Stability: Deprecated

For information about the new self-service APIs, see "RESTful User Self-Service".

Legacy User Self-Registration

The OpenAM REST API for users provides an action for self-registration. The feature works by sending an email to the user in response to RESTful HTTP POST requesting registration with an email address. When the user clicks the link received by mail, an application intercepts the HTTP GET, transforms the query string values into an HTTP POST to confirm the operation. OpenAM responds to the application with a JSON object that the application can further use to request creation of the user account to complete the transaction.

To Set Up Legacy User Self-Registration

  1. Configure the Email Service.

    You must configure the Email Service to send mail notifications to users who self-register. To configure these globally in OpenAM console, navigate to Configure > Global Services, and then click Email Service.

    Alternatively, you can configure them for an individual realm under Realms > Realm Name > Services.

  2. Configure Legacy User Self Service.

    You must enable self-registration in the User Self Service service. To configure these globally, in OpenAM console navigate to Configure > Global Services, and then click Legacy User Self Service. On the Legacy User Self Service page, click the Enabled checkbox next to Legacy Self-Service REST Endpoint, and Self-Registration for Users, and then click Save.

    At this point users can self-register. The starting screen for self-registration is at /XUI/#register/ under the base URL where OpenAM is installed. The default confirmation URI is /XUI/confirm.html.

  3. Perform an HTTP POST on /json/users?_action=register with the new user’s mail.

    In OpenAM 13, the /users endpoint was updated to version 3.0. Request API resource version 2.0 in the REST API calls to get the behavior provided in previous versions of OpenAM.

    To use a subject and message other than those configured in the Email Service, you can optionally set the mail subject and message content by including "subject" and "message" strings in the JSON data. For example, the following POST results in a mail with subject Confirm registration with OpenAM and content Follow this link to confirm your registration in addition to the confirmation link.

    Notice that authentication is not required.

    $ curl \
--request POST \
--header "Content-Type: application/json" \
--header "Accept-API-Version: protocol=1.0,resource=2.0" \
--data \
'{
    "email": "newuser@example.com",
    "subject": "Confirm registration with OpenAM",
    "message": "Follow this link to confirm your registration"
}' \
https://openam.example.com:8443/openam/json/users?_action=register
{}

    On success, the response is an empty JSON object {} as shown in the example.

  4. The user receives an email message that includes a URL similar to the following example, but all on one line. The user has self-registered in the root realm:

    https://openam.example.com:8443/openam/XUI/confirm.html?
      confirmationId=f4x0Dh6iZCXtX8nhiSb3xahNxrg%3D
      &email=newuser%40example.com
      &tokenId=yA26LZ6SxFEgNuF86%2FSIXfimGlg%3D
      &realm=/

  5. Intercept the HTTP GET request to this URL when the user clicks the link.

    Your application must use the confirmation link to construct an HTTP POST to /json/users?_action=confirm from the query string parameters as shown in the following example:

    $ curl \
--request POST \
--header "Content-Type: application/json" \
--header "Accept-API-Version: protocol=1.0,resource=2.0" \
--data \
'{
    "email": "newuser@example.com",
    "tokenId": "yA26LZ6SxFEgNuF86/SIXfimGlg=",
    "confirmationId": "f4x0Dh6iZCXtX8nhiSb3xahNxrg="
}' \
https://openam.example.com:8443/openam/json/users?_action=confirm
{
    "email": "newuser@example.com",
    "tokenId": "yA26LZ6SxFEgNuF86/SIXfimGlg=",
    "confirmationId": "f4x0Dh6iZCXtX8nhiSb3xahNxrg="
}

    The response is a further confirmation that the account can be created.

  6. Using the confirmation, your application must make an authenticated HTTP POST to /json/users?_action=anonymousCreate to create the user as shown in the following example:

    $ curl \
--request POST \
--header "Content-Type: application/json" \
--header "Accept-API-Version: protocol=1.0,resource=2.0" \
--data \
'{
    "email": "newuser@example.com",
    "tokenId": "yA26LZ6SxFEgNuF86/SIXfimGlg=",
    "confirmationId": "f4x0Dh6iZCXtX8nhiSb3xahNxrg=",
    "username": "newuser",
    "userpassword": "password"
}' \
https://openam.example.com:8443/openam/json/users?_action=anonymousCreate
{
    "username": "newuser",
    "realm": "/",
    "uid": [
        "newuser"
    ],
    "mail": [
        "newuser@example.com"
    ],
    "sn": [
        "newuser"
    ],
    "cn": [
        "newuser"
    ],
    "inetUserStatus": [
        "Active"
    ],
    "dn": [
        "uid=newuser,ou=people,dc=openam,dc=forgerock,dc=org"
    ],
    "objectClass": [
        "devicePrintProfilesContainer",
        "person",
        "sunIdentityServerLibertyPPService",
        "inetorgperson",
        "sunFederationManagerDataStore",
        "iPlanetPreferences",
        "iplanet-am-auth-configuration-service",
        "organizationalperson",
        "sunFMSAML2NameIdentifier",
        "inetuser",
        "forgerock-am-dashboard-service",
        "iplanet-am-managed-person",
        "iplanet-am-user-service",
        "sunAMAuthAccountLockout",
        "top"
    ],
    "universalid": [
        "id=newuser,ou=user,dc=openam,dc=forgerock,dc=org"
    ]
}

    At this point, the user is registered, active, and can authenticate with OpenAM.

Legacy Forgotten Password Reset

The OpenAM REST API provides an action for handling forgotten passwords as long as the user has a valid email address in their profile. This is an alternative to the password reset capability described in "Configuring User Self-Service Features" in the Administration Guide.

If the current password is known, use the "Changing Passwords" feature to change a password.

An example follows, showing the steps in more detail.

To Set Up Legacy Forgotten Password Reset

  1. Configure Legacy User Self Service.

    You must enable Forgotten Password Reset in the Legacy User Self Service service. To configure this globally in the OpenAM console, navigate to Configure > Global Services, and then click Legacy User Self Service. On the Legacy User Self Service page, click the Enabled checkbox next to Legacy Self-Service REST Endpoint, and Forgot Password for Users, and then click Save.

  2. Configure the Email Service.

    In particular, you must configure the Email Service to send mail allowing the user to reset the forgotten password.

    To configure the service globally in the OpenAM Console, navigate to Configure > Global Services, and then click Email Service.

    Alternatively, you can configure it for an individual realm under Realms > Realm Name > Services.

    At this point users with mail addresses can reset their forgotten passwords. The starting screen for forgotten password reset is at /XUI/#forgotPassword/ under the base URL where OpenAM is installed. The default confirmation URI is /XUI/confirm.html.

    The steps that follow show how to use the REST API directly.

  3. Perform an HTTP POST on /json/users?_action=forgotPassword with the user’s ID.

    In OpenAM 13, the /users endpoint was updated to version 3.0. Request API resource version 2.0 in the REST API calls to get the behavior provided in previous versions of OpenAM.

    To use a subject and message other than those configured in the Email Service, you can optionally set the mail subject and message content by including "subject" and "message" strings in the JSON data. For example, the following POST results in a mail with subject Reset your forgotten password with OpenAM and content Follow this link to reset your password in addition to the confirmation link.

    Notice that authentication is not required.

    $ curl \
--request POST \
--header "Content-Type: application/json" \
--header "Accept-API-Version: protocol=1.0,resource=2.0" \
--data '{
    "username": "demo",
    "subject": "Reset your forgotten password with OpenAM",
    "message": "Follow this link to reset your password"
}' \
https://openam.example.com:8443/openam/json/users/?_action=forgotPassword
{}

    Note that you can also use the email attribute to locate the user. If both username and mail attributes are used, then a request error is issued. If more than one account has been registered with the same email address, the password reset process does not start.

    $ curl \
--request POST \
--header "Content-Type: application/json" \
--header "Accept-API-Version: protocol=1.0,resource=2.0" \
--data '{
    "email": "demo@example.com",
    "subject": "Reset your forgotten password with OpenAM",
    "message": "Follow this link to reset your password"
}' \
https://openam.example.com:8443/openam/json/users/?_action=forgotPassword
{}

    On success, the response is an empty JSON object {} as shown in the example.

    OpenAM looks up the email address in the user profile, and sends an email message that includes a URL as in the following example, but all on one line.

    https://openam.example.com:8443/openam/json/XUI/confirm.html
      ?confirmationId=sdfsfeM+URcWVQ7vvCDnx4N5Vut7SBIY=
      &tokenId=vkm+5v58cTs1yQcQl5HCQGOsuQk=
      &username=demo&realm=/

  4. Intercept the HTTP GET request to this URL when the user clicks the link.

    Your application must use the confirmation link to construct an HTTP POST to /json/users?_action=confirm from the query string parameters as shown in the following example:

    $ curl \
--request POST \
--header "Content-Type: application/json" \
--header "Accept-API-Version: protocol=1.0,resource=2.0" \
--data \
'{
    "username":"demo",
    "tokenId":"vkm+5v58cTs1yQcQl5HCQGOsuQk=",
    "confirmationId":"sdfsfeM+URcWVQ7vvCDnx4N5Vut7SBIY="
}' \
https://openam.example.com:8443/openam/json/users?_action=confirm
{
    "username": "demo",
    "tokenId": "vkm+5v58cTs1yQcQl5HCQGOsuQk=",
    "confirmationId": "sdfsfeM+URcWVQ7vvCDnx4N5Vut7SBIY="
}

    The response is a further confirmation that the request is valid, has not expired, and the password can be reset.

  5. Using the confirmation, your application must construct an HTTP POST to /json/users?_action=forgotPasswordReset to reset the password as shown in the following example.

    Your POST includes the new password as the value of the "userpassword" field in the JSON payload. You can also use the email attribute instead of username.

    $ curl \
--request POST \
--header "Content-Type: application/json" \
--header "Accept-API-Version: protocol=1.0,resource=2.0" \
--data '{
    "username":"demo",
    "userpassword":"password",
    "tokenId":"vkm+5v58cTs1yQcQl5HCQGOsuQk=",
    "confirmationId":"sdfsfeM+URcWVQ7vvCDnx4N5Vut7SBIY="
}' \
https://openam.example.com:8443/openam/json/users?_action=forgotPasswordReset
{}

    On success or failure, the REST call returns an empty message, so that information is not leaked.

    At this point the user can authenticate with the new password.