From Communication-mashups
HYBRID COMMUNICATIONS - AUTHORIZATIONS MANAGEMENT
Contents |
Overview
Hybrid Communication API is using the OAUTH standard to manage users authorizations.
For more information about OAUTH protocol and associated terminology, please refer to http://oauth.net . OAUTH specification is available at http://oauth.net/core/1.0/ .
The present documentation provides indications for the devlopment of a mashup application (a "Consumer" application in OAUTH terminology) that will use the services provided by Hybrid Communications services (the "Service Provider" in OAUTH terminology). Through OAUTH protocol, a user of Hybrid Communications (user of www.dundal.com site) will be able to give authorization to the mashup application allowing thus this application to access to the user's private resources: here his communication hyperlinks (or "dundals").
Hybrid Communications and OAUTH
Hybrid Communication API is currently compliant with release 1.0 of OAUTH (see specification).
Nevertheless, following points need to be noticed:
- In the current implementation, and unlike mentioned in the specification, the two arguments oauth_token (corresponding to a request token) and oauth_callback (pointing to a valid URL given by the consumer application) are mandatory for the call to the User Authorization URL.
- Only the "HMAC-SHA1" and "RSA-SHA1" signature methods are currently supported (the usage of "PLAINTEXT" signature method will be possible once https will be supported for Hybrid Communications access).
- In the current implementation, a unique level of authorization is asked to the user (no possibility for him to give access in read only mode for instance). Thus, it is the responsability of the consumer application to clearly indicate to the users, the consequences of the actions performed on his resources.
Following chapters provide, for Hybrid Communication Services, necessary information for registration of consumers and for OAUTH authentication transactions.
Consumer Registration
To register a new consumer application to Hybrid Communications, following information are required:
- Email address where the "Consumer Key" and "Consumer Secret" will be returned (see OAUTH specification),
- Name of the mashup application,
- URL where the application will be (or is) accessible,
- Description of the application.
These three last information will be presented to the users when they will be asked to allow or refuse access to their resources.
The form to register an Hybrid Communication consumer is available here: Special:OAuthConsumerMgt.
It is the responsability of the Consumer to store its Consumer Key and Consumer Secret data. These two elements will have to be used by the consumer as specified by OAUTH standard.
User Authorization
To be able to access to the communication hyperlinks of a user, a consumer will have to follow the three authentication steps defined by OAUTH.
The following URLs need to be used for these three steps:
- For the consumer to obtain a request token:
- http://www.dundal.com/HybridComServer/request_token
- For the consumer to ask for a user authorization
- http://www.dundal.com/HybridComServer/authorize
- For the consumer to exchange a request token by an access token
- http://www.dundal.com/HybridComServer/access_token
The arguments to be provided for these requests are the ones specified in OAUTH specification. No additional argument is required by Hybrid Communication Services.
Warnings:
- As indicated in section "Hybrid Communications and OAUTH", PLAINTEXT signature method is currently not supported, and the arguments oauth_token and oauth_callback are mandatory in request http://www.dundal.com/HybridComServer/authorize.
- When a user will have granted an authorization for the consumer, he will be redirected to the URL indicated in oauth_callback (with the authorized requestToken specified as oauth_token argument). But if the user refuses the authorization, no redirection will be done. The consumer has to handle this possible case in its implementation.
- It is the responsability of the consumer to store and manage the associations between the users and the tokens returned by Hybrid Communication Services.
- A user will have the possibility to revoke an authorization already granted when he desires. In such a case, all new requests coming from the consumer to access to this user's resources will be rejected (the access token is no more valid).
- In case where an access token is invalid, a consumer will have to following again the three steps of OAUTH authentication if it is needed to access again to the user's resources.
Access to user resources
Once an access token has been got, a consumer has the possibility to access to the resources of the concerned user. To access to these resources, the consumer will have to follow the specifications of the Hybrid Communication Services API documented here: Special:APIDocumentation.
It is naturally necessary to add, to the arguments of the methods described in this API, the OAUTH arguments as mentioned in the OAUTH specification. (Reminder: the signature has to be built from the URL and arguments mentionned in the API and also from the arguments required by OAUTH protocol).
Miscellaneous
To ease the development of Hybrid Communications consumers, some libraries (for different languages) and examples will be provided as a complement to this documentation soon ...
