Archive 1.x:Auth Registrar: Access/1.1

From OSF Wiki
Jump to: navigation, search
Auth Registrar: Access endpoint version:
1.1
2
3


The Auth Registrar: Access Web service is used to register (create, update and delete) an access for a given IP address, to a specific dataset and all the registered Web services endpoints registered to the WSF (Web Services Framework) with given CRUD (Create, Read, Update and Delete) permissions in the WSF.

Developers communicate with the Auth Registrar: Access Web service using the HTTP POST method. You may request any content type (*/*).

No content is returned by the Web service endpoint if the endpoint successfully executed the query. Only a "200 OK" message will be returned in the header.


Version

This documentation page is used for the version 1.1 of this endpoint. Check at the top of this page to see the documentation pages for the other versions of this endpoint.

Usage

This Web service is intended to be used by content management systems, developers or administrators to manage access to WSF (Web Service Framework) resources (users, datasets, Web services endpoints).

This web service endpoint is used to create what we refer to as an access permissions record. This record describe the CRUD permissions, for a certain IP address, to use a set of web service endpoints, to query a target dataset.

If the IP address that is registered is "0.0.0.0", it refers to the public access of this dataset. This means that if we define an access permission record for the IP address 0.0.0.0, to the CRUD permissions "Create: False; Read: True; Update: False; Delete: False", on the dataset URI http://mydomain.com/wsf/datasets/mydataset/ for all web service endpoints, this mean that anybody that send a query, to any web service endpoint, for that dataset, will be granted Read permissions. This means that this dataset becomes World Readable.

Web Service Endpoint Information

This section describes all you permissions you need in the WSF (Web Service Framework) to send a query to this Web service endpoint, and it describes how to access it.

To access this Web service endpoint you need the proper CRUD (Create, Read, Update and Delete) permissions on a specific graph (dataset) of the WSF. Without the proper permissions on this graph you won't be able to send any queries to the endpoint.

Needed registered CRUD permission:
  • Create: True
  • Read: True
  • Update: False
  • Delete: False

As shown on the graph URI:

  • http://[...]/wsf/

Here is the information needed to communicate with this Web service's endpoint. Descriptions of the parameters are included below.

Note: if a parameter has a default value, the requester can omit it and the default value will be used. Also, some baseline Web services may not offer other values than the default.

HTTP Method:
  • POST

Possible "Accept:" HTTP header field value:

  • */*

URI:

  • http://[...]/ws/auth/registrar/access/ ?crud=param1&ws_uris=param2&dataset=param3&action=param4& target_access_uri=param5&registered_ip=param6

URI dynamic parameters description:

Note: All parameters have to be URL-encoded

  • param1. A quadruple with a value "True" or "False" defined as <Create;Read;Update;Delete>. Each value is separated by the ";" character. an example of such a quadruple is: "crud=True;True;False;False", meaning: Create = True, Read = True, Update = False and Delete = False. This defines the permissions granted for the target IP, target Dataset and target Web Service Endpoints of this access permission record.
  • param2. A list of ";" separated Web services URI accessible by this access permissions record
  • param3. URI of the target dataset of this access permissions record
  • param4. One of:
    • "create (default)": Create a new access permissions record
    • "delete_target": Delete a target access permissions record for a specific IP address and a specific dataset
    • "delete_all": Delete all access permissions records for a target dataset
    • "update": Update an existing access permissions record
  • param5. Target URI of the access resource to update. Only used when param4 = update
  • param6. Target IP address to registered in the WSF. Any IP address can be used to create the access permissions record. The special IP address "0.0.0.0" is used for public access; read the usage section above for more information.
Query Answer from the Endpoint

If the query is successfully performed by the endpoint (i.e., the access resource has been properly created, updated or deleted), the endpoint will return the HTTP status message "200 OK" with an empty body. If an error occured, one of the HTTP status messages with the description of the error message in the body of the HTTP query will be returned.

HTTP Status Codes

Here are the possible HTTP status (error) codes returned by this Web service endpoint.

On error code and the specific error, a different message description can be issued (meaning a different error has been returned).

  • Code: 200
    • Message: OK
  • Code: 400
    • Message: Bad Request
    • Message description: Answer from the endpoint
    • Message description: Action type undefined
    • Message description: No IP to register
    • Message description: No crud access defined
    • Message description: No web service URI(s) defined
    • Message description: No dataset defined
    • Message description: No target Access URI defined for update
    • Message description: No requester IP available
    • Message description: No target dataset
    • Message description: No Web service URI available
    • Message description: Target Web service XYZ not registered to this Web Services Framework
    • Message description: No access defined for this requester IP XYZ, dataset (XYZ) and Web service (XYZ)
    • Message description: The target Web service (XYZ) needs create access and the requested user (XYZ) doesn't have this access for that dataset (XYZ)
    • Message description: The target Web service (XYZ) needs read access and the requested user (XYZ) doesn't have this access for that dataset (XYZ)
    • Message description: The target Web service (XYZ) needs update access and the requested user (XYZ) doesn't have this access for that dataset (XYZ)
    • Message description: The target Web service (XYZ) needs delete access and the requested user (XYZ) doesn't have this access for that dataset (XYZ)
  • Code: 406
    • Message: Not Acceptable
    • Message description: Unacceptable mime type requested
  • Code: 500
    • Message: Internal Error