RESTful Thoughts - OAUTH implementation for the F1 RESTful API Part 1

We took some time with this implementation and really did some soul searching on Authentication / Authorization mechanisms for the new Fellowship One API. The past few APIs that we've released used credential based authentication ( + signed keys for Payment Gateway) which was appropriate considering the intended usage.

With the RESTful API we know that churches, 3rd parties, vendors, volunteers, and the like will be consuming the API's secure resources - so we chose OAUTH.

The OAUTH features enable all of those consumers to create web sites or applications (consumers) that can access resources available via Fellowship One (Service Provider) securely, and without having to store or gather user credentials.

The benefits of our implementation of OAUTH are:

• Both the church and user will be able to protect / authorize access to their resources
• Resources will only be available to applications that both the church and users of that church has access to (configurable)
• The Consumer will never have access to login information or credentials - so the login is totally owned by the service provider

All requests for resources (excluding tokens and login) must have a Consumer Key, Access Token, and signature.

Roles of our implementation of OAUTH are:

• Service Provider: Fellowship One RESTful API - A web application (API) that allows access via OAuth.
• Consumer: 3rd party / church / Individual - A website or application that uses OAuth to access the Service Provider on behalf of the User.
• User: Portal User, User, Weblink User - An individual who has an account with the Service Provider.

OAUTH Parameter information (from the protocol documents):

• Consumer Key: A value used by the Consumer to identify itself to the Service Provider.
• Consumer Secret: A secret used by the Consumer to establish ownership of the Consumer Key.
• Request Token: A value used by the Consumer to obtain authorization from the User, and exchanged for an Access Token.
• Access Token: A value used by the Consumer to gain access to the Protected Resources on behalf of the User, instead of using the User’s Service Provider credentials.
• Token Secret: A secret used by the Consumer to establish ownership of a given Token.
• OAuth Protocol Parameters: Parameters with names beginning with oauth_.

Brief overview of the F1 OAUTH process (assuming all valid credentials and authority):

• The Consumer application will use a consumer key and secret to sign all URIs so that the F1 API will be able to verify the consumers identity and credentials.
• The Consumer application first requests a "Request Token" to use when the Users access the login pages -> The Service provider grants the request token.
• The Consumer application will direct the User to the Service Provider to obtain User Authorization
• The Service Provider will obtain authorization from the User and direct the User back to the Consumer
• The Consumer application will then request an Access Token -> The Service provider grants the request token and marks the "Content-Location" header with a URI to the User information.
• The Consumer application will use the Access Token to access Protected Resources

The process defined above requires accessing the following URIs:

Request token URI:
http://{churchcode}.{domain}/{version}/Tokens/RequestToken [POST]

Login URIs:
Portal Users http://{churchcode}.{domain}/{version}/PortalUser/Login [GET]
Weblink Users http://{churchcode}.{domain}/{version}/WeblinkUser/Login [GET]
Groups Users http://{churchcode}.{domain}/{version}/User/Login [GET]

Access Token URI:
http://{churchcode}.{domain}/{version}/Tokens/AccessToken [POST]