FOAFRealm/SOA/Introduction

From Corrib Clan Wiki

Contents 1 FOAFRealm SOA short introduction 1.1 Main concepts 1.2 Avaliable methods 1.3 Available data (URIs) 1.4 Requests statuses. 1.5 Authorisation. 1.6 Access control 1.7 How to implement Authorisation in a SOA client 1.8 Authorization process example.

FOAFRealm SOA short introduction

Main concepts

FOAFRealm SOA is build using REST Web Services approach. In summary, RESTful Web Services are resource based and uses HTTP protocol to access, change, remove or add resources in the server. Resources are identified with unique URI. FOAFRealm SOA uses RDF to exchange the data between client and server.

More information could be find in thesis: Service Oriented Architecture for Distributed Identity Management System. REST detailed information - Section 2.6, FOAFRealm SOA details - Chapters 4, 5, 6.

Avaliable methods

In REST there are only four methods available. These methods could operate on infinitive amount of data identified by URI. REST uses 4 HTTP methods:

• GET - to get the data. You should send the GET request to some specific URI to receive the resource pointed with this URI.
• POST - to change the data. New data should be send to some specific URI pointing the resource that should be changed.
• PUT - to add new data. Data should be send to some specific uRI (which describes the resource that will be created). In FOAFRealm SOA mainly used for new profile creation.
• DELETE - to remove the data. This request should be send to the URI which points to the resource that should be removed.

Available data (URIs)

In the following description foafrealm.org/soa/ is a example base service URI.

• http://[foafrealm.org/soa/][mbox]. Use to get, set, update or remove users profile. User is identified with mbox or mboxsha1_sum
• http://[foafrealm.org/soa/][mbox_sha1_sum]. Use to get, set, update or remove users profile. User is identified with mbox or mboxsha1_sum.
• http://[foafrealm.org/soa/][mbox]/[profile_part] where profile_part is one of title, name, surname, nickname, homepage, phoneNumber, workHomepage, schoolHomepage, etc. This URI should generally return one (or sometimes more than one, i.e. user could have many nick names) RDF triple (with GET method). Could be also used to change, add or remove this information (with rest of HTTP methods).
• http://[foafrealm.org/soa/][mbox]/friends will give access to the list of the friends, optionally with friendship level information (only owner could access friendship level information).
• http://[foafrealm.org/soa/][mbox]/friends/[mbox or mbox_sha1sum] will give access to the information about one particular friend.
• http://[foafrealm.org/soa/][mbox]/friends/[mbox or mbox_sha1sum]/[friend_part] will give access to the partial information about a friend.
• http://[foafrealm.org/soa/][mbox]/inrole/[FOAFRealm role] Only GET method available. Should be used to check if user is in given role (has suitable access rights)

Requests statuses.

All the previously mentioned requests could return a common set of HTTP stutuses.

• 200 - Success, the content of the response contains RDF data (in GET - requested data, POST or PUT - changed/added data)
• 400 - Wrong URI. Specified URI is not supported by FOAFRealm SOA.
• 401 - Unauthorized. User sends the request that needs authorization. (POST, PUT, DELETE methods)
• 403 - Forbidden. User tries to change the that data that he do not have access. (POST, PUT, DELETE methods)
• 406 - Unacceptable. POST method - user tries to change not existing data.

Authorisation.

In FOAFRealm SOA there is HTTP Basic authorisation method implemented. HTTP Basic is supported by majority internet browsers. To use the HTTP Basic outside the browser, there should be specific information send in request header. To be authorised, there should be following header field sent:

Authorization: Basic Base64_encoded(login':'password)

If the authorization information is not send (and is required) then the SOA will respond with 401 Unathorized HTTP status and the Realm name will be send with

WWW-Authenticate: Basic realm="FOAFRealm SOA realm.

Access control

Generally, GET method is available without authorisation. However to access some specific information about user (like friendship level) user needs to be authorised. Other methods (POST, PUT, DELETE) requires user authorisation, and only the owner of the FOAFRealm profile could send such request. For example, only test@test.com, could send the POST request to the http://soa.address/test@test.com/phone.

How to implement Authorisation in a SOA client

SOA does not have specific method to log the user in, furthermore the HTTP Basic is stateless. To authorise user in the client there test should be done to check if user is the one that he/she claims to be. To do that one should send request that needs authorisation. If the SOA answers with 401 Unathorized, it means that user should not be logged in, if the answer status is 200, it means that the user should be logged in.

To ease the process the special URI was prepared. The http://soa.address/[mbox]/auth should be send with empty content by POST method. It will return either 401 or 200 with user's profile in the content (equivalent to GET 'http://soa.address/[mbox]). After successful authorisation information about user should be kept on client side (to be attached in the next request).

Authorization process example.

• User pass the following data:
  • login: test@test.com
  • password: abcd

• Client constructs the HTTP Header
  • encode the test@test.com:abcd to base64String
  • construct the header: Authorization: Basic base64String

• Client send the POST to the
  • http://soa.address/test@test.com/auth with empty content.

• Client receives the answer status
  • 401 or other greater than 400 - the information sent by the user is wrong.
  • 200 - the user and password match the original one.

• The "[...]/auth" method is also special for one more reason - it returns the user's profile. Generally POST method should be used only to change information and it might return information that have been changed. In case of "[...]/auth" a
  • GET http://soa.address/test@test.com

is invoked just after successful authorisation and it's results is put in the response content.