Skip to end of metadata
Go to start of metadata

Today REST is a trend and almost every platform has a mobile app and provides REST API.

OpenIAM in its 3.x version supports the RESTful interface in addition to SOAP Services. The RESTful API can be used for the majority of possible use cases in our application. The developers can use its CRUD, Search, Validation, Success and Error responses to write their own code. Potentially, this will allow to create a mobile version of the Self-Service application or a HTML5 mobile page.

While we don't usually want to expose the ESB to the outside, there are ways to protect it using the interceptors.

OpenIAM RESTful API

OpenIAM RESTful API is a separate web-application.

REST means exchange of JSON objects. So, this documentation describes what objects to be sent and what objects come in response. The interfaces of interaction with our REST controllers are described. This is necessary to know if you want to use our RESTful API.

The programming language for REST is JavaScript with the help of Ajax.

 

You can use the REST methods for the following purposes:

  • Authorization
  • User management
  • User provisioning
  • User and Role searching

Methods

You can use the following methods:

MethodDescription
login
Error rendering macro 'excerpt-include' : No link could be created for 'RESTful Authentication API - login Skip to end of metadata'.
renewTokenThe RenewToken API allows to renew access tokens before they expire.
saveUserThe saveUser method creates new or updates the existing user. It refers to the provisioning service.
deleteUserThe deleteUser method deletes the user by userId. It refers to the provisioning service.

removeUser

The removeUser method removes the user by userId. It refers to the provisioning service.
enableUserThe enableUser method enables the user by userId. It refers to the provisioning service.
disableUserThe disableUser method disables the user by userId. It refers to the provisioning service.
activateUserThe activateUser method activates the user by userId. It refers to the Provisioning service.
resetPasswordThe resetPassword method resets password for the user. It refers to the provisioning service.
attributesThe userAttributes method returns user attributes by userId.
search 
searchRoles 

They are all basically simple and self-explanatory but saveUser and resetPassword need complex objects as parameters: ResetPasswordBean and EditUserModel.

All actions that exist in REST-controllers are currently used in the User Interface scripts. For example, user.edit.js has a usage example of the activeUser method.

Responses

BasicAjaxResponse is a common response. It is a Java class BasicAjaxResponse.java with the following properties:

private int status;
private List<ErrorToken> errorList;
private String redirectURL;
private SuccessToken successToken;
private String successMessage;
private Map<String, Object> contextValues;

Status values:

  • 200 means success;
  • 500 is an error.

If there is no any errors, then we can read successToken or successMessage returned.

If there is an error, then errorList is not empty and contains error messages.

Having the JSON response, the customer must decide how to process this object and display the result. For example, in case of success to show the success message in the popup.


Debugging and Testing

The following page can be used to debug requests and responses:

/webconsole-am/authenticationDebug.html
You can use the Firefox browser's Firebug plugin to track Ajax requests and responses sent and received from the working Webconsole UI. Call the plugin, log in to OpenIAM, fulfill operations using the user interface and see details of what is happening "behind the scenes" at the plugin panel. You can use the obtained information to create your own cURL requests.

The following screen-shot shows how the Firebug plugin can be used to get the URL and all necessary JSON data sent to OpenIAM.

You have several options for sending requests through an OpenIAM API:

  • Developers and testers may prefer to use cURL, the command-line tool from http://curl.haxx.se/. With cURL, you can send HTTP requests and get responses from the command line.
  • If you like to use a more graphical interface, you can use the Chrome or Firefox/Firebug plugin to get the URL and all necessary JSON data sent to OpenIAM. For example, the REST client for Firefox works well for testing and trying out commands, read more about it in https://addons.mozilla.org/en-US/firefox/addon/restclient/.
  • You can also download and install rest-client, a Java application to test ReSTful web services, from http://code.google.com/p/rest-client/.

Real Life Example

Lets try to create a User using cURL and the OpenIAM installation at localhost:8585/webconsole under Windows 7.

  1. Here is the first step to get the authentication token. Use the login method:

    curl -k http://localhost:8585/idp/login.html -d"login=my.login&password=secret"

    which returns authToken among other data:

    {"status":200,"errorList":null,"redirectURL":"/selfservice","successToken":null,"successMessage":nul
    l,"contextValues":null,"possibleErrors":null,"passwordExpired":false,"userId":"297e9f344ca3f6f3014ca
    46e5a110063","unlockURL":null,"tokenInfo":{"authToken":"cT7FTfxDPE037tqUF8jN1UmXyQy5kOODDvl1Rk1A8qVK
    d4aEvYCumcKupH++jRVBalzATYyEbxoZB+tS8h7YbAbyPMiTEs+thCno3TnUNyh/qoLRrY393wwKyYaXz5ZV7e2boicUTyAiJ8jT
    xh9TOxL+3tOEr9GG/ETQEO0QS6k2LS7dc1etqfltH1qTJvBwU83W87vLGSsr/3bndCrmUKOYtVhKPXqom8U8I0wvBDkiwItXyvSA
    ENJvIhIiS4wX","timeToLiveSeconds":-1},"error":false}
  2. Then you can add a new User using the saveUser method. Use the authentication token received in the first step to stay logged in.

    curl http://localhost:8585/webconsole/rest/api/prov/saveUser -v
    --cookie "OPENIAM_AUTH_TOKEN=cT7FTfxDPE037tqUF8jN1UmXyQy5kOODDvl1Rk1A8qVK
    d4aEvYCumcKupH++jRVBalzATYyEbxoZB+tS8h7YbAbyPMiTEs+thCno3TnUNyh/qoLRrY393wwKyYaXz5ZV7e2boicUTyAiJ8jT
    xh9TOxL+3tOEr9GG/ETQEO0QS6k2LS7dc1etqfltH1qTJvBwU83W87vLGSsr/3bndCrmUKOYtVhKPXqom8U8I0wvBDkiwItXyvSA
    ENJvIhIiS4wX" -H "Content-Type: application/json; charset=UTF-8" -X
    POST
     -d 
    "{\"id\":null,\"firstName\":\"Xxx\",\"lastName\":\"Zzz\",\"metadataTypeId\":\"DEFAULT_USER\",\"notifyUserViaEmail\":false,\"notifySupervisorViaEmail\":false}"

    Response:

    Response
    * Adding handle: conn: 0x1d95a90
    * Adding handle: send: 0
    * Adding handle: recv: 0
    * Curl_addHandleToPipeline: length: 1
    * - Conn 0 (0x1d95a90) send_pipe: 1, recv_pipe: 0
    * About to connect() to lnx1.openiamdemo.com port 80 (#0)
    *   Trying 198.154.117.130...
    * Connected to lnx1.openiamdemo.com (198.154.117.130) port 80 (#0)
    > POST /webconsole/rest/api/prov/saveUser HTTP/1.1
    > User-Agent: curl/7.33.0
    > Host: lnx1.openiamdemo.com
    > Accept: */*
    > Cookie: OPENIAM_AUTH_TOKEN=omElHjtEkNPCVvmxdLO/HUA2iimcMt/mF/rOh64AoDFA7Cmwh1SnOpReUI9czS3nXt+WQ4A
    vsyFtVcXZZD83HmAfWehGCRfEfFgu+G48bAkgYMDNJ91zmKL5bEQcOfXwwxx1gaTcEgo4o+4xa/uBQw==
    > Content-Type: application/json; charset=UTF-8
    > Content-Length: 138
    >
    * upload completely sent off: 138 out of 138 bytes
    < HTTP/1.1 200 OK
    < Date: Mon, 13 Apr 2015 11:05:21 GMT
    * Server Apache-Coyote/1.1 is not blacklisted
    < Server: Apache-Coyote/1.1
    < X-UA-Compatible: IE=EmulateIE10
    < Cache-Control: no-cache
    < Pragma: no-cache
    < Expires: Wed, 31 Dec 1969 23:59:59 GMT
    < Content-Type: application/json;charset=UTF-8
    < Set-Cookie: OPENIAM_AUTH_TOKEN=ZmtNGM3jsiQsGKGLdUMsXKjRWh3/K00NgG+TrS1eADEyjOIbZ/6MiVkWc0J+0cqYBFc
    Ly441ReQ6Y1D67aWXYeA/ydO+te0UwwCFZZ2/0ECN++NT3HYPjrPUsDc4pVLMHAK8EVKZ1juYeRLs6aHdZw==; Path=/; HttpO
    nly; Domain=.openiamdemo.com
    < Set-Cookie: JSESSIONID=5A287C8B8133DCF3C17B0D26EC826523; Path=/webconsole/; HttpOnly
    < Connection: close
    < Transfer-Encoding: chunked
    <
    {"status":200,"errorList":null,"redirectURL":"editUser.html?id=000000004ca96864014cb2747ea30054","su
    ccessToken":{"message":"USER_INFO_SAVED"},"successMessage":"User Information Saved Successfully<br/>
    Provisioning:<br/>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;OPENIAM: CREATED","contextValues":{"userId":"0000000
    04ca96864014cb2747ea30054","checkStatusInProgress":true},"possibleErrors":null,"error":false}* Closi
    ng connection 0

    At the end of the response you can see the successMessage: "User Information Saved Successfully.


 


In the Current Section...