OAuth Provider Plugin
This plugin implements support for OAuth to provide facilities for FusionForge to act as an OAuth provider.
The oauthprovider plugin allows remote tools to connect to the forge, on behalf of a forge user, (without the user having to divulge his forge credentials to the tool). A detailed explanation about the OAuth protocol can be found here.
This allows remote (Web) applications to invoke FusionForge's APIs (Web services) in authenticated mode, without having to disclose to these applications (whose security may not be assessed) the user's credentials (login+password).
This is unlike what happens with SOAP where some initial login is to be conducted (preferably over HTTPS) to authenticate to FusionForge, during which the a user's (login and) password will have to be submitted by the remote application.
See https://fusionforge.org/tracker/index.php?func=detail&aid=78&group_id=6&atid=114 for status update on this plugin's development.
Note that the plugin is also a dependency for other plugins or features of the forge providing Web services.
See also OAuth consumer Plugin.
The first step to connecting a remote tool to the forge is to register it at the forge. In OAuth terminology, this remote tool is called an OAuth Consumer and the forge is called the OAuth Provider. Only a forge admin has the rights to register/unregister OAuth Consumers. The link to the consumer page will be http://fusionforge/plugins/oauthprovider/consumer.php This is accessible once the forge admin has activated the OAuth Provider plugin through the Account Maintenance page. Registering a consumer generates a consumer key and secret, which are used to identify that consumer in all OAuth transactions.
Access Token Creation
OAuth uses three kinds of credentials: consumer key and secret (explained above), access token and secret (used to authenticate access) and request token and secret (temporary credentials used when creating access tokens). The OAuth Provider (i.e. the forge) is characterised by three end-points. These are needed by an OAuth consumer to create access tokens which it will later use to connect to the provider. For the forge these endpoints are:
- Request Token URL: http://forge/plugins/oauthprovider/request_token.php
- User Authorization URL: http://forge/plugins/oauthprovider/authorize.php
- Access Token URL: http://forge/plugins/oauthprovider/access_token.php
Accessing Protected Resources
An access tokens created on behalf of a user is always linked to one of his roles. This linking is done by the user at the time of creation of the access token. So if a user has a role which just allows read access to a tracker and an access token is linked to this role, all oauth transactions using this access token will have the same permissions as this role (i.e. read access to the tracker) and no more. Once the oauth provider plugin is installed, a page or an action can be oauth-enabled by a call to session_set_for_authplugin('oauthprovider'). All oauth parameters are contained in the HTTP request, either in the Authorisation header or in the query string. The session_set_for_authplugin() function verifies the validity of the oauth parameters and sets up the session with the appropriate permissions (i.e. the role linked to the access token). However, if the file "pre.php" is included, an explicit call to session_set_for_authplugin is not needed, it is called implicitly.
The working of the OAuth plugin is explained below with the help of a use-case.
A user Alice belongs to two projects (A and B) which are both hosted on the same instance of Fusionforge. There are two instances of Jenkins (a continuous integration tool), lets say Jenkins A & Jenkins B, each of which run builds on the different branches of the source-code of the two projects. Alice wants to have automatic bug reports created in the respective tracker of the respective project whenever there is a build failure. This can be done using the protocols OSLC and OAuth.