The information below can also be found in the Documentation section of the Open Flame console. Here we included an example that shows you how to use the given instructions in Rest Client, which is a very handy tool that allows you to perform REST requests, for the non REST specialists out there. We hope that this will make your understanding of how REST works in Open Flame, and how you can use it for your own needs even more accessible.

Open Flame REST Authentication

The basic Open Flame authentication service is simple but powerful. It is based on the provision and usage of authentication tokens dedicated to each user session.

In order to obtain an authentication token, a service client should provide a valid username and password as registered in the Open Flame Directory. Once the client has obtained an authentication token, this token may be used for all requests to Open Flame and Open Flame driven applications and services.

In order to obtain an authentication token from Open Flame the client can submit a standard REST request like the example below.

POST http://{openflame.base.url}/rest/authority/sts/sign-in HTTP/1.1

Accept: application/xml
user-name: {opf-user}
password: {opf-user-password}

In the first line:

POST is the HTTP Method, HTTP/1.1 is the HTTP version used.

The  following three lines are the Headers of the REST request, of which the first part is the actual Header Name, and the second part after the colon, is the value of the Header.

Substitute the bracketed variables in the above example as described below:

• {opf-user} substitute the username of an Open Flame registered user account;
• {opf-user-password} substitute the password of the registered user;
• {openflame.base.url} substitute the base url of the Open Flame system (e.g. http://localhost:8080/openflame).

As an example, let’s assume the following values using localhost as the Open Flame server and the default admin user as the user account:

opf-user=admin
opf-user-password=111111
openflame.base.url=http://localhost:8080/openflame

SAMPLE REQUEST:

POST http://localhost:8080/openflame/rest/authority/sts/sign-in HTTP/1.1
Accept application/xml
user-name admin
password 111111

Provided Open Flame is installed and operating correctly, it should return a result that includes the token.

SAMPLE RESPONSE:

Server: Apache-Coyote/1.1
Set-Cookie: JSESSIONID=E90B48C073C544B539B9AF380A27A01F; Path=/openflame; HttpOnly
Content-Type: application/xml;charset=UTF-8
Content-Length: 454
Date: Tue, 12 Feb 2013 08:59:13 GMT

<?xml version="1.0" encoding="UTF-8"?>
<model>
    <data>
        <authenticationToken>
            <token>c7291f6c-5be0-45bd-b471-4df70ed10fae0962d9493e5eb740e51fa915a3a2def7</token>
            <user>
                <canDelete>true</canDelete>
                <canUpdate>true</canUpdate>
                <id>1</id>
                <guest>false</guest>
                <username>admin</username>
                <password>96e79218965eb72c92a549dd5a330112</password>
            </user>
        </authenticationToken>
    </data>
    <message>Successfully authenticated.</message>
    <success>true</success>
</model>

In the response above, Open Flame returned the following indicators:

<message>Successfully authenticated.</message> and <success>true</success> which tells the client the request succeeded.

It also returned a valid authentication token for the admin user:

<token>c7291f6c-5be0-45bd-b471-4df70ed10fae0962d9493e5eb740e51fa915a3a2def7</token>

This response means that the Open Flame successfully authenticated the user with the username: admin and has now associated the token: c7291f6c-5be0-45bd-b471-4df70ed10fae0962d9493e5eb740e51fa915a3a2def7 with an active user session. This token may be used for all subsequent service calls in the header as long as the session is active.

Although xml format is commonly used, Open Flame also supports requests and responses in the JSON format. In order to receive responses in JSON format the client can simply change the Accept header value from application/xml to application/json.

So, if we would try to change our first request's Accept header from application/xml to application/json.

SAMPLE REQUEST:

POST http://localhost:8080/openflame/rest/authority/sts/sign-in HTTP/1.1
Accept application/json
user-name admin
password 111111

SAMPLE RESPONSE:

Server: Apache-Coyote/1.1
Set-Cookie: JSESSIONID=CE4229C84C2F11A4732FF25700FEA98B; Path=/openflame; HttpOnly
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Date: Tue, 12 Feb 2013 10:05:28 GMT

{
  "message" : "Successfully authenticated.",
  "total" : null,
  "data" : [ {
    "token" : "4754b253-ed7b-4b1d-a864-38ebf38b25a689f180a6071db7d2778c69fa03daf149",
    "user" : {
      "password" : "96e79218965eb72c92a549dd5a330112",
      "firstName" : null,
      "lastName" : null,
      "middleName" : null,
      "distinguishedName" : null,
      "passwordConfirm" : null,
      "facebookId" : null,
      "twitterId" : null,
      "username" : "admin",
      "guest" : false,
      "id" : 1,
      "email" : null,
      "registryNodeId" : null,
      "created" : null,
      "canDelete" : true,
      "canUpdate" : true,
      "rules" : null
    }
  } ],
  "success" : true
}

How to use the authentication token

Once obtained, the Open Flame authentication token is most easily used via an HTTP header value as shown here.

For the purpose of this example, assume the valid authentication token is the one received above:
opf.authentication.token=ff9e7251-1f54-476d-9485-c73eeb7e29e8

In practice we would be using the obtained authentication token in a REST request as shown below:

REQUEST:

GET http://localhost:8080/openflame/rest/registry/root_domain HTTP/1.1
Accept application/json
Cookie opf.authentication.token=c7291f6c-5be0-45bd-b471-4df70ed10fae0962d9493e5eb740e51fa915a3a2def7

Any service secured by Open Flame will obey this cookie header value.

An example of a response to the above request should look like this:

RESPONSE:

Server: Apache-Coyote/1.1
Set-Cookie: JSESSIONID=3B3F4EBE7A0BE2A3656F2122894361A9; Path=/openflame; HttpOnly
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Date: Tue, 12 Feb 2013 09:10:09 GMT

{
  "message" : "List has been found by id.",
  "total" : 3,
  "data" : [ {
    "name" : "firejack.net",
    "parentId" : null,
    "type" : "ROOT_DOMAIN",
    "path" : "",
    "description" : null,
    "lookup" : "net.firejack",
    "parameters" : {
    },
    "childCount" : 4,
    "id" : 1,
    "created" : 1359390158000,
    "canDelete" : true,
    "canUpdate" : true,
    "rules" : null
  }, {
    "name" : "coolmovies.com",
    "parentId" : null,
    "type" : "ROOT_DOMAIN",
    "path" : "",
    "description" : "",
    "lookup" : "com.coolmovies",
    "parameters" : {
    },
    "childCount" : 2,
    "id" : 3216,
    "created" : 1359453900000,
    "canDelete" : true,
    "canUpdate" : true,
    "rules" : null
  }, {
    "name" : "selfref.test",
    "parentId" : null,
    "type" : "ROOT_DOMAIN",
    "path" : "",
    "description" : "",
    "lookup" : "test.selfref",
    "parameters" : {
    },
    "childCount" : 2,
    "id" : 3493,
    "created" : 1359554101000,
    "canDelete" : true,
    "canUpdate" : true,
    "rules" : null
  } ],
  "success" : true
}

Using Rest Client to obtain a REST authentication key

First you should download and install Rest Client. You can find the main page here: http://code.google.com/p/rest-client/

Just download the latest version for your OS and follow the installation instructions.

When Rest Client is installed, start the application.

In the top section you should enter the URL as described the Open Flame REST Authentication section at the beginning of this post.

The next step is to select the right Method, which for our purpose would be POST, as shown in the above screenshot.

Click the Header tab.

In the 'Key' field you enter the header name, and in the value field you enter the value of the header, as shown above.

Once you entered both the Key and Value field data, click the + sign to actually add the header to the header list.

In the end, you should have the following values entered:

Then once all header information is entered, all you have to do is click the double arrow >> button.

In the lower section of the window the results will be displayed and should look similar to this example:

Header:

Body:

If you right-click the yellow marked line and select Ident > Ident XML it will show you the details of the body, like this:

Using the authentication key with Rest Client

Now that we obtained an authentication key, we can use that to perform any future REST requests with.

First we need to replace URL we are using with one that will allow us perform an actual REST request.

Replace the URL we used so far with: http://localhost:8080/openflame/rest/registry/root_domain

Replace 'localhost' with an ip address or domain name if you are not working on a local system.

We also have to change the HTTP method from POST to GET. We can do this on the first tab with the Method information.

Then we need to remove the user-name and password headers in the Header tab, as shown below:

Now we need to add the token where it belongs. For this we will be using the Cookie tab.

In the Key field type: opf.authentication.token, then in the response body, select the value between <token> and </token> and paste it in the Value field.

Go ahead and click the + button to add the Cookie value.

The end result should look like this:

Now we can perform the REST request, using the security password and token that we received in our first request.

With the current parameters a typical response would like like this:

Header:

Body:

Using these instructions, you can use Rest Client to invoke REST requests toward the Open Flame platform.

In the Documentation section you can find more details on the specific actions you want to perform and the URL that you should be using.

-- Edited by marc on Friday 15th of February 2013 03:15:02 PM