OpenTox API 1.2 A&A
Mrautenberg (Talk | contribs) |
Mrautenberg (Talk | contribs) |
||
Line 1: | Line 1: | ||
<p>Listed below are relevant REST operations. Please see the [http://www.opentox.org/data/documents/development/opentoxreports/opentoxreportd33 documentation] for more information.</p><h2>A REST operations</h2><p><strong>(a)</strong></p> | <p>Listed below are relevant REST operations. Please see the [http://www.opentox.org/data/documents/development/opentoxreports/opentoxreportd33 documentation] for more information.</p><h2>A REST operations</h2><p><strong>(a)</strong></p> | ||
− | {| | + | {| class="wikitable" |
| <p class="TableContents"><strong>Desired action</strong></p> | | <p class="TableContents"><strong>Desired action</strong></p> | ||
| <p class="TableContents"><strong>URL</strong></p> | | <p class="TableContents"><strong>URL</strong></p> | ||
Line 19: | Line 19: | ||
| <p class="TableContents">POST on /auth/logout</p> | | <p class="TableContents">POST on /auth/logout</p> | ||
| <p class="TableContents">subjectid<sup>1</sup></p> | | <p class="TableContents">subjectid<sup>1</sup></p> | ||
− | | <p class="TableContents">200 + void</p | + | | <p class="TableContents">200 + void</p> |
|}<p><sup>1</sup> URI-encoded: <strong>YES</strong><br> Note: all parameters are <strong>form</strong> parameters.</p><p><strong>(b1)</strong></p> | |}<p><sup>1</sup> URI-encoded: <strong>YES</strong><br> Note: all parameters are <strong>form</strong> parameters.</p><p><strong>(b1)</strong></p> | ||
− | {| | + | {| class="wikitable" |
| <p class="TableContents">Desired action</p> | | <p class="TableContents">Desired action</p> | ||
| <p class="TableContents">URL</p> | | <p class="TableContents">URL</p> | ||
Line 30: | Line 30: | ||
| <p class="TableContents">All</p> | | <p class="TableContents">All</p> | ||
| <p class="TableContents">as before + <br>subjectid<sup>1</sup></p> | | <p class="TableContents">as before + <br>subjectid<sup>1</sup></p> | ||
− | | <p class="TableContents">as before + 401</p | + | | <p class="TableContents">as before + 401</p> |
|}<p><sup>1</sup> URI-encoded: <strong>YES</strong><br>Note: all parameters are <strong>form</strong> parameters.</p><p><strong>(b2)</strong></p> | |}<p><sup>1</sup> URI-encoded: <strong>YES</strong><br>Note: all parameters are <strong>form</strong> parameters.</p><p><strong>(b2)</strong></p> | ||
− | {| | + | {| class="wikitable" |
| <p class="TableContents">Desired action</p> | | <p class="TableContents">Desired action</p> | ||
| <p class="TableContents">URL</p> | | <p class="TableContents">URL</p> | ||
Line 41: | Line 41: | ||
| <p class="TableContents">POST on /auth/authorize</p> | | <p class="TableContents">POST on /auth/authorize</p> | ||
| <p class="TableContents">uri<sup>1</sup><br>action<sup>1</sup><br>subjectid<sup>1</sup></p> | | <p class="TableContents">uri<sup>1</sup><br>action<sup>1</sup><br>subjectid<sup>1</sup></p> | ||
− | | <p class="TableContents">200 + Boolean (Grant)<br>401 + Boolean (Deny)</p><p class="TableContents"> </p | + | | <p class="TableContents">200 + Boolean (Grant)<br>401 + Boolean (Deny)</p><p class="TableContents"> </p> |
|}<p><sup>1</sup> URI-encoded: <strong>YES</strong><br>Note: all parameters are <strong>form</strong> parameters.<br><sup></sup></p><h3>Background</h3><p>Authentication: client authenticates against OpenSSO and obtains a token. The user data is drawn from the LDAP backend that also the Plone website uses.</p><p>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.</p><p>To access a restricted/protected service, only tokens NOT credentials should be passed to the respective service (e.g. descriptor calculation)</p><p> </p><p>The OpenTox API needs modification in some places and the introduction of some new components. We have two cases:</p><blockquote dir="ltr"><p>(a) Authentication against OpenSSO: should be done by the client application<br>(b) Authorisation against OpenSSO for resource and action combinations</p></blockquote><p>For (1), we need to transmit user credentials and obtain a token, while part (b) can be decomposed into:</p><blockquote dir="ltr"><p>(b1) Client authorisation request to the webservice: should be done by the client application <br>(b2) Authorisation request confirmation from webservice to OpenSSO: should be done by the webservice.</p></blockquote><p> See [http://www.opentox.org/data/documents/development/opentoxreports/opentoxreportd33 documentation]</p><hr><h2>Policy REST operations</h2> | |}<p><sup>1</sup> URI-encoded: <strong>YES</strong><br>Note: all parameters are <strong>form</strong> parameters.<br><sup></sup></p><h3>Background</h3><p>Authentication: client authenticates against OpenSSO and obtains a token. The user data is drawn from the LDAP backend that also the Plone website uses.</p><p>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.</p><p>To access a restricted/protected service, only tokens NOT credentials should be passed to the respective service (e.g. descriptor calculation)</p><p> </p><p>The OpenTox API needs modification in some places and the introduction of some new components. We have two cases:</p><blockquote dir="ltr"><p>(a) Authentication against OpenSSO: should be done by the client application<br>(b) Authorisation against OpenSSO for resource and action combinations</p></blockquote><p>For (1), we need to transmit user credentials and obtain a token, while part (b) can be decomposed into:</p><blockquote dir="ltr"><p>(b1) Client authorisation request to the webservice: should be done by the client application <br>(b2) Authorisation request confirmation from webservice to OpenSSO: should be done by the webservice.</p></blockquote><p> See [http://www.opentox.org/data/documents/development/opentoxreports/opentoxreportd33 documentation]</p><hr><h2>Policy REST operations</h2> | ||
− | {| | + | {| class="wikitable" |
| <p class="TabellenInhalt">Desired action</p> | | <p class="TabellenInhalt">Desired action</p> | ||
| <p class="TabellenInhalt">URL</p> | | <p class="TabellenInhalt">URL</p> | ||
Line 80: | Line 80: | ||
| <p>DELETE on /pol</p> | | <p>DELETE on /pol</p> | ||
| <p class="TabellenInhalt">subjectid<sup>3</sup><br>id<sup></sup></p> | | <p class="TabellenInhalt">subjectid<sup>3</sup><br>id<sup></sup></p> | ||
− | | <p class="TabellenInhalt">200 (OK)<br>400 (Policy non-existent)<br>401 (Unauthorized)<br>500 (General Error)</p | + | | <p class="TabellenInhalt">200 (OK)<br>400 (Policy non-existent)<br>401 (Unauthorized)<br>500 (General Error)</p> |
|}<p><sup>2</sup> may be set to any value, e.g. 'true', return value is owner (first row), policy names (consecutive rows), <br><sup>3</sup> URI-encoded: <strong>NO</strong><br>Note: all parameters are <strong>header</strong> parameters.</p><h3>Background</h3><p>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:</p><pre><!DOCTYPE Policies PUBLIC "-//Sun Java System Access Manager7.1 2006Q3 | |}<p><sup>2</sup> may be set to any value, e.g. 'true', return value is owner (first row), policy names (consecutive rows), <br><sup>3</sup> URI-encoded: <strong>NO</strong><br>Note: all parameters are <strong>header</strong> parameters.</p><h3>Background</h3><p>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:</p><pre><!DOCTYPE Policies PUBLIC "-//Sun Java System Access Manager7.1 2006Q3 | ||
Admin CLI DTD//EN" "jar://com/sun/identity/policy/policyAdmin.dtd"> | Admin CLI DTD//EN" "jar://com/sun/identity/policy/policyAdmin.dtd"> |
Revision as of 10:04, 9 December 2011
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 |
200 + token (Valid) |
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 + |
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 |
200 + Boolean (Grant)
|
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) |
List my policies |
GET on /pol |
subjectid3 |
200 (OK) |
List my policy id |
GET on /pol |
subjectid3 |
200 (OK) |
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 |
200 (OK) |
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"
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
- The client establishes encrypted SSL/TLS connection to the OpenSSO server.
- The client sends username and password through the encrypted channel to the OpenSSO server.
- The OpenSSO server verifies the presented user credentials against opentox.org’s user database.
- Depending on the result of this verification:
- On success, the OpenSSO server returns a cryptographic token to the client.
- On failure, the OpenSSO server returns appropriate error message.
Uploading dataset
- The client establishes encrypted SSL/TLS connection to the dataset service.
- The client fetches the user and group lists from the OpenSSO server.
- 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.
- The client POSTs the dataset to the dataset service, providing along also:
- 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.
- The policies to be created based on the user preferences from step 3.
- The dataset service sends the provided token for validation to the OpenSSO server.
- 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.
- If the user is allowed to create new data, the dataset service registers the uploaded dataset, but does not publish it yet.
- 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.
- 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.
- The dataset service returns the newly created dataset ID to the client.
General
Relevant readings:
FOAF+SSL: RESTful Authentication for the Social Web
HTTP Authentication: Token Access Authentication
http://wiki.oauth.net/OAuth-WRAP
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.