TOC 
Implementer Draftnaf. Fellowship One OAuth
 Extension
 June 2009


Fellowship One REST API Auth Core v1.0 (Draft)

Abstract

This Authentication protocol is an extension of the OAuth 1.0 protocol which enables websites or applications (Consumers) to access Protected Resources from a web service (Service Provider) via an API, without requiring Users to disclose their Service Provider credentials to the Consumers. More generally, OAuth creates a freely-implementable and generic methodology for API authentication.

This extension’s intent is to provide a pattern that will support the usage concepts of Trusted Consumer applications, Multi-Tenant / multi-Users with multi-personas. As well as provide a token based trust for consumer applications that have a preexisting trust established (i.e. the consumer is a tenant of the service provider and the consumer’s users have established a trust with the service provide via the consumer).

This enables the usage of many security measures from the OAuth Protocol while allowing the applications written by those parties accept credentials directly. Since the user already "trusts" the Consumer / Organization who wrote the application encoding and accepting credentials directly ensures seemless integration.



Table of Contents

1.  Authors
2.  Notation and Conventions
3.  Definitions
4.  Multi-Tenant Configuration
    4.1.  Steps
    4.2.  URLs
5.  Authentication Workflow
    5.1.  Trusted credential based authentication (2nd Party)
    5.2.  OAuth based authentication (3rd Party)
6.  *HTTP Response Codes
7.  References
§  Author's Address




 TOC 

1.  Authors

Jas Singh (jsingh@fellowshiptech.com)

Kingsley Allen (kallen@fellowshiptech.com)

Matt Vasquez (mvasquez@fellowshiptech.com)

Nick Floyd (nfloyd@fellowshiptech.com), Editor

Tim Hardy (thardy@fellowshiptech.com)



 TOC 

2.  Notation and Conventions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119] (Bradner, B., “Key words for use in RFCs to Indicate Requirement Levels,” .). Domain name examples use [RFC2606] (Eastlake, D. and A. Panitz, “Reserved Top Level DNS Names,” .).

OAuth Core 1.0 references and definitions can be viewed : http://oauth.net/core/1.0/



 TOC 

3.  Definitions

1st Party Consumer Applications:
Applications written and made public by the Service Provider (Fellowship Technologies) – They will be marked as Public and as Trusted by the Service Provider.
2nd Party User Trusted Consumer Applications:
applications written and made private by the Consumer and used by the Consumer’s(or Tenant’s) Users – They will be marked as Private by the Service Provider.
3rd Party Consumer Applications:
Defined as applications written and made public for consumption across Tenants – They will be marked as Public by the Service Provider.
*Service Provider:
A web application that allows access via OAuth.
Tenant:
An entity / organization that encapsulates a group of Users with in the context of the Service Provider.
User:
A persona of the User for the given Consumer Application implementation - An individual who has an account with the Service Provider.
User Type:
A persona of the User for the given Consumer Application implementation - Based on personas established by the Service Provider.
Consumer:
3rd party / Tenant - A website or application that uses OAuth to access the Service Provider on behalf of the User.
Trusted Consumer:
A Consumer where the User has implicit trust because the Consumer is both a Tenant / User of the Service Provider and the User's organization.
*Protected Resource(s):
Data controlled by the Service Provider, which the Consumer can access through authentication.
*Consumer Developer:
An individual or organization that implements a Consumer.
*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.

* from [OAuth] (Atwood, M., Conlan, R., Cook, B., Culver, L., McCrea, K., Halff, L., Hammer, E., Laurie, B., Messina, C., Panzer, J., Quigley, S., Recordon, D., Sandler, E., Sergent, J., Sieling, T., Slesinsky, B., and A. Smith, “OAuth,” .) Core 1.0 Spec



 TOC 

4.  Multi-Tenant Configuration

Tenants of the Service Provider must establish the trust through a series of configurations so that the Consumer / Tenant and its Users will be able to use this authentication extension.



 TOC 

4.1.  Steps

Step 1:
Before any Consumer applications can access any Tenant data the Tenant must first enable access to thier data via Service Providers interface.
Step 2:
The Tenant must establish a relationship with and 1st, 2nd, or 3rd party applications via Service Providers interface that they want thier Users to be able to use.
Step 3:
Users of the Tenant can create / view / delete relationships (Access Tokens) with all Consumer Applications that the Tenant has established a relationship with.



 TOC 

4.2.  URLs

The Service Provider will supply URLs for the Consumers to use for both normal OAuth implementations and "Trusted" instances.



 TOC 

4.2.1.  OAuth URLs

Request Token:

[GET] https://tenant.sp.com/v1/Tokens/RequestToken
[POST] https://tenant.sp.com/v1/Tokens/RequestToken
Required header - Content-Length: 0

User Authorization:

Redirect User: https://tenant.sp.com/v1/[User Type]/Login

Access Token:

[GET] https://tenant.sp.com/v1/Tokens/AccessToken
[POST] https://tenant.sp.com/v1/Tokens/AccessToken
Required header - Content-Length: 0

It is RECOMMENDED that Consumer application use POST when requesting Tokens, however the Service Provider SHOULD support both GET and POST



 TOC 

4.2.2.  Trusted URLs

Access Token:

[GET] https://tenant.sp.com/v1/[User Type]/AccessToken
[POST] https://tenant.sp.com/v1/[User Type]/AccessToken
Required header - Content-Length: 0

It is RECOMMENDED that Consumer application use POST when requesting Tokens, however the Service Provider SHOULD support both GET and POST



 TOC 

5.  Authentication Workflow



 TOC 

5.1.  Trusted credential based authentication (2nd Party)

Consumer Application collects the User's credentials directly
Consumer Application concatenates the user name and password with a space and base64 encodes the credentials
Consumer Application puts the encoded credentials in the body of the request (no parameter assignment, just put the bytes in the request)
If the consumer is using the accept header value: application/x-www-form-urlencoded then the consumer must pass the credentials using the following format
ec=bXZhc3F1ZXogcGEkJHcwcmQ%3d
Credentials must be URL Encoded after they are base64 encoded
Consumer Application posts credentials to the following URI depending on User Type:
This request is signed using [OAuth] (Atwood, M., Conlan, R., Cook, B., Culver, L., McCrea, K., Halff, L., Hammer, E., Laurie, B., Messina, C., Panzer, J., Quigley, S., Recordon, D., Sandler, E., Sergent, J., Sieling, T., Slesinsky, B., and A. Smith, “OAuth,” .) signing
https://tenant.sp.com/v1/[User Type]/AccessToken
The Service Provider will hand the Consumer Application back an Access Token via:
Response body:
This request is signed using [OAuth] (Atwood, M., Conlan, R., Cook, B., Culver, L., McCrea, K., Halff, L., Hammer, E., Laurie, B., Messina, C., Panzer, J., Quigley, S., Recordon, D., Sandler, E., Sergent, J., Sieling, T., Slesinsky, B., and A. Smith, “OAuth,” .) signing
ex. oauth_token=afd011d3-fbd3-4c69-8326-a24fad8d0c34&oauth_token_secret=ab86c226-fc65-4d32-a33c-8b54a753655e
Header:
ex. oauth_token=afd011d3-fbd3-4c69-8326-a24fad8d0c34
oauth_token_secret=ab86c226-fc65-4d32-a33c-8b54a753655e
The Consumer Application will also get a URI to the User resource via Content-Location header:
ex. Content-Location=https://tenant.sp.com/v1/People/123
The Consumer Application will access the User's data using the Access Token and Token Secret



 TOC 

5.2.  OAuth based authentication (3rd Party)

Consumer Application requests an unauthenticated Request Token
This request is signed using [OAuth] (Atwood, M., Conlan, R., Cook, B., Culver, L., McCrea, K., Halff, L., Hammer, E., Laurie, B., Messina, C., Panzer, J., Quigley, S., Recordon, D., Sandler, E., Sergent, J., Sieling, T., Slesinsky, B., and A. Smith, “OAuth,” .) signing
[GET] https://tenant.sp.com/v1/[User Type]/AccessToken
[POST] https://tenant.sp.com/v1/[User Type]/AccessToken
Required header - Content-Length: 0
Service Provider passes back an unauthorized Request Token
Response body:
ex. oauth_token=afd011d3-fbd3-4c69-8326-a24fad8d0c34&oauth_token_secret=ab86c226-fc65-4d32-a33c-8b54a753655e
Consumer Application requests user authorization via redirect
This request is signed using [OAuth] (Atwood, M., Conlan, R., Cook, B., Culver, L., McCrea, K., Halff, L., Hammer, E., Laurie, B., Messina, C., Panzer, J., Quigley, S., Recordon, D., Sandler, E., Sergent, J., Sieling, T., Slesinsky, B., and A. Smith, “OAuth,” .) signing
The Consumer Application will pass the Request Token via url
ex. https://tenant.sp.com/v1/Tokens/RequestToken?oauth_token=afd011d3-fbd3-4c69-8326-a24fad8d0c34
The Consumer Application may pass a callback url via url as an OPTIONAL parameter
ex. https:///tenant.sp.com/v1/Tokens/RequestToken?oauth_token=afd011d3-fbd3-4c69-8326-a24fad8d0c34&oauth_callback=http://www.myconsumerapp.com/home
User URL:
ex. https:///tenant.sp.com/v1/[User Type]/Login
The User enters thier credentials in using the Service Provider's interface
The User will either Accept or Deny the request
If the User allows access then the Service Provider authenticates the Request Token
If a oauth_callback parameter was provided the Service Provider sends the User back to the Consumer Application
ex. Redirect http://www.myconsumerapp.com/home?oauthtoken=afd011d3-fbd3-4c69-8326-a24fad8d0c34
If no oauth_callback parameter was provided the Service Provider sends the User to another page with the authorized Request Token witten in the body
If the User denies access then the Service Provider marks the Request Token as revoked
If a oauth_callback parameter was provided the Service Provider sends the User back to the Consumer Application [OAuthProblemReporting] (Kristian, J., “OAuth Problem Reporting Extension,” .)
ex. Redirect http://www.myconsumerapp.com/home?permissiondenied=The+user+has+denied+access+to+all+protected+resources.
If no oauth_callback parameter was provided the Service Provider sends the User to another page stating that Request Token has been revoked
The Consumer Application will take the Authorized Request Token and it's corresponding Token Secret and request an Access Token
This request is signed using [OAuth] (Atwood, M., Conlan, R., Cook, B., Culver, L., McCrea, K., Halff, L., Hammer, E., Laurie, B., Messina, C., Panzer, J., Quigley, S., Recordon, D., Sandler, E., Sergent, J., Sieling, T., Slesinsky, B., and A. Smith, “OAuth,” .) signing
The Consumer Application will sign the request using the Authenticated Request Token and Token Secret
The Consumer Application will pass the Authenticated Request Token via url
[GET] https://tenant.sp.com/v1/Tokens/AccessToken
[POST] https://tenant.sp.com/v1/Tokens/AccessToken
Required header when using the [POST] verb - Content-Length: 0
The Service Provider will hand the Consumer Application back an Access Token via:
Response body:
ex. oauth_token=afd011d3-fbd3-4c69-8326-a24fad8d0c34&oauth_token_secret=ab86c226-fc65-4d32-a33c-8b54a753655e
Header:
oauth_token=afd011d3-fbd3-4c69-8326-a24fad8d0c34
oauth_token_secret=ab86c226-fc65-4d32-a33c-8b54a753655e
The Consumer Application will also get a URI to the User resource via Content-Location header:
ex. Content-Location=https://tenant.sp.com/v1/People/123
The Consumer Application will access the User's data using the Access Token and Token Secret


 TOC 

6.  *HTTP Response Codes

This section applies only to the Request Token and Access Token requests. In general, the Service Provider SHOULD use the response codes defined in [RFC2616] (Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, “Hypertext Transfer Protocol -- HTTP/1.1,” .) Section 10. When the Service Provider rejects a Consumer request, it SHOULD respond with HTTP 400 Bad Request or HTTP 401 Unauthorized.

HTTP 400 Bad Request
Unsupported parameter
Unsupported signature method
Missing required parameter
Duplicated OAuth Protocol Parameter
HTTP 401 Unauthorized
  • Invalid Consumer Key
  • Invalid / expired Token
  • Invalid signature
  • Invalid / used nonce

*from [OAuth] (Atwood, M., Conlan, R., Cook, B., Culver, L., McCrea, K., Halff, L., Hammer, E., Laurie, B., Messina, C., Panzer, J., Quigley, S., Recordon, D., Sandler, E., Sergent, J., Sieling, T., Slesinsky, B., and A. Smith, “OAuth,” .) Core 1.0 Spec



 TOC 

7. References

[FellowshipOneRESTAPI] Floyd, N., “Fellowship One REST API.”
[OAuth] Atwood, M., Conlan, R., Cook, B., Culver, L., McCrea, K., Halff, L., Hammer, E., Laurie, B., Messina, C., Panzer, J., Quigley, S., Recordon, D., Sandler, E., Sergent, J., Sieling, T., Slesinsky, B., and A. Smith, “OAuth.”
[OAuthProblemReporting] Kristian, J., “OAuth Problem Reporting Extension.”
[RFC2119] Bradner, B., “Key words for use in RFCs to Indicate Requirement Levels,” RFC 2119.
[RFC2606] Eastlake, D. and A. Panitz, “Reserved Top Level DNS Names,” RFC 2606.
[RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, “Hypertext Transfer Protocol -- HTTP/1.1,” RFC 2616.
[RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., Leach, P., Luotonen, A., and L. Stewart, “HTTP Authentication: Basic and Digest Access Authentication,” RFC 2617.


 TOC 

Author's Address

  Fellowship One API Group
Email:  api@fellowshipone.com