OpenTox API 1.2 A&A

From ToxBank API Wiki
Jump to: navigation, search

Listed below are relevant REST operations. Please see the  documentation for more information.

Contents

A REST operations

(a)

Desired action

URL

Parameters

Return values (conditions)

Authentication

POST on /auth/authenticate

username1
password1
uri1

200 + token (Valid)
401 (Invalid)

Token validation

POST on /auth/isTokenValid

tokenid1

200 + Boolean

Logout

POST on /auth/logout

subjectid1

200 + void

1 URI-encoded: YES
Note: all parameters are form parameters.

(b1)

Desired action

URL

Parameters

Return values (conditions)

All

All

as before +
subjectid1

as before + 401

1 URI-encoded: YES
Note: all parameters are form parameters.

(b2)

Desired action

URL

Parameters

Return values (conditions)

Authorization

POST on /auth/authorize

uri1
action1
subjectid1

200 + Boolean (Grant)
401 + Boolean (Deny)

 

1 URI-encoded: YES
Note: all parameters are form parameters.

Background

Authentication: client authenticates against OpenSSO and obtains a token. The user data is drawn from the LDAP backend that also the Plone website uses.

Authorisation: Token is used to permit or deny a client a specific action. The token encodes conjunction of user and point of time and has a certain lifetime. If token is authorized for the action according to current server policy, the webservice performs the action.

To access a restricted/protected service, only tokens NOT credentials should be passed to the respective service (e.g. descriptor calculation)

 

The OpenTox API needs modification in some places and the introduction of some new components. We have two cases:

(a) Authentication against OpenSSO: should be done by the client application
(b) Authorisation against OpenSSO for resource and action combinations

For (1), we need to transmit user credentials and obtain a token, while part (b) can be decomposed into:

(b1) Client authorisation request to the webservice: should be done by the client application
(b2) Authorisation request confirmation from webservice to OpenSSO: should be done by the webservice.

 See  documentation


Policy REST operations

Desired action

URL

Parameters

Return values (conditions)

Create a policy

POST XML file to /pol/

subjectid3

200 (OK)
400 (XML contains errors)
500 (Other Errors)

List my policies

GET on /pol

subjectid3

200 (OK)
500 (Other Errors)

List my policy id

GET on /pol

subjectid3
id

200 (OK)
401 (Unauthorized)
500 (Other Errors)

GET owner of URI uri
GET on /pol subjectid3
uri
200 (OK)
401 (Unauthorized)
500 (Other

Errors)

GET owner of URI uri
and all affected policy
names
GET on /pol
subjectid3
uripolnames2
200 (OK)
401 (Unauthorized)
500 (Other

Errors)

Delete policy id

DELETE on /pol

subjectid3
id

200 (OK)
400 (Policy non-existent)
401 (Unauthorized)
500 (General Error)

2 may be set to any value, e.g. 'true', return value is owner (first row), policy names (consecutive rows),
3 URI-encoded: NO
Note: all parameters are header parameters.

Background

To create a policy, issue a POST to http://<pol-server>/Pol/opensso-pol with the XML file to transfer and header entry "Content-Type: application/xml". The XML file should match the following schema:

<!DOCTYPE Policies PUBLIC "-//Sun Java System Access Manager7.1 2006Q3
   Admin CLI DTD//EN" "jar://com/sun/identity/policy/policyAdmin.dtd">
<Policies>
<Policy name="POLICY_NAME" referralPolicy="false" active="true">
   <strong><Rule name="RULE_NAME"></strong>
      <ServiceName name="iPlanetAMWebAgentService" />
      <ResourceName name="TARGET_URI"/>
      <strong><AttributeValuePair></strong>
         <Attribute name="ACTION_NAME" />
         <Value>ACTION_VAL</Value>
      <strong></AttributeValuePair></strong>
   <strong></Rule></strong>
   <Subjects name="SUBJECT_GROUP" description="">
        <strong><Subject name="SUBJECT_ID" type="LDAP_TYPE" includeType="inclusive"></strong>
            <AttributeValuePair>
                <Attribute name="Values"/>
                <Value>LDAP_DN</Value>
            </AttributeValuePair>
        <strong></Subject></strong>
   </Subjects>
</Policy>
</Policies>

 

All parts are mandatory. Bold parts (e.g. <Rule>s and <Subject>s) may occur more than one time, allowing for compound objects such as complex datasets, which may consist of compounds and features stored on different servers, under different URIs. It allows also for multiple actions and subjects. The following table explains the fields that must be set:

POLICY_NAME   Arbitrary string, e.g. "my_policy". Must not contain spaces!

RULE_NAME     Arbitrary string, e.g. "my rule" TARGET_URI    URI to protect, e.g. "<a href="http://opentox.mybox.org/res">http://opentox.mybox.org/res</a>" ACTION_NAME   One of "GET", "PUT", "POST", "DELETE" ACTION_VAL    One of "allow", "deny" SUBJECT_GROUP Arbitrary string, e.g. "my people" SUBJECT_ID    Arbitrary string, e.g. "John Doe" LDAP_TYPE     One of "LDAPUsers", "LDAPGroups"

LDAP_DN       Distinguished name, e.g. "uid=jdoe, ou=people, dc=opentox,dc=org"
Note for LDAP_DN:

Individuals always use:  uid=<uid>, ou=people, dc=opentox, dc=org
Groups always use      :  cn=<gid>, ou=groups, dc=opentox, dc=org

        Note: <uid>/<gid> should be replaced with OpenTox's Plone user/group IDs, respectively.

Note: Disabled wildcards completely for URIs (June 11, 2010).

See  documentation.

 


Extended use cases


General Authentication

 

  1. The client establishes encrypted SSL/TLS connection to the OpenSSO server.
  2. The client sends username and password through the encrypted channel to the OpenSSO server.
  3. The OpenSSO server verifies the presented user credentials against opentox.org’s user database.
  4. Depending on the result of this verification:
    1. On success, the OpenSSO server returns a cryptographic token to the client.
    2. On failure, the OpenSSO server returns appropriate error message.

 

Uploading dataset

 

  1. The client establishes encrypted SSL/TLS connection to the dataset service.
  2. The client fetches the user and group lists from the OpenSSO server.
  3. The client presents the user with an interface to select the required permissions for the dataset to be uploaded: different users and/or groups could be selected and for each one any of the four HTTP methods GET, POST, PUT and DELETE could be either allowed or disallowed.
  4. The client POSTs the dataset to the dataset service, providing along also:
    1. The token acquired from the authentication phase: Following the guidelines of RFC 2616 (section 14.8), the authentication information of the user agent for the realm of the resource being requested is provided in the Header field 'Authorization'. Note also that the provided token should be URL encoded (in UTF-8). See http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.8 for further details.
    2. The policies to be created based on the user preferences from step 3.
  5. The dataset service sends the provided token for validation to the OpenSSO server.
  6. If the token is not valid, the dataset service returns an appropriate error message. Otherwise, it checks with the OpenSSO server whether the user is allowed to create new data.
  7. If the user is allowed to create new data, the dataset service registers the uploaded dataset, but does not publish it yet.
  8. The dataset service requests the OpenSSO policy service to create the requested policy by the user in step 3 for the resources registered in the previous step.
  9. If the creation of access control policy fails, the dataset service returns an appropriate error message to the client. Otherwise, if the policy is successfully created, the dataset is published.
  10. The dataset service returns the newly created dataset ID to the client.

 

 


General

Relevant readings:

FOAF+SSL: RESTful Authentication for the Social Web

OpenID

OAuth

HTTP Authentication: Token Access Authentication

http://wiki.oauth.net/OAuth-WRAP

James Hollenbach, Joe Presbrey, and Tim Berners-Lee, Using RDF Metadata To Enable Access Control on the Social Semantic Web, 2009

Basic Access Control ontology

WebAccessControl is a decentralized system for allowing different users and groups various forms of access to resources where users and groups are identified by HTTP URIs.

Personal tools