| TOC |
|
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.
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 |
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 |
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 |
- 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.
| TOC |
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 |
- 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 |
The Service Provider will supply URLs for the Consumers to use for both normal OAuth implementations and "Trusted" instances.
| TOC |
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 |
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 |
| TOC |
- 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
- 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
- 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
- Header:
- The Consumer Application will also get a URI to the User resource via Content-Location header:
- The Consumer Application will access the User's data using the Access Token and Token Secret
| TOC |
- 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:
- 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
- The Consumer Application may pass a callback url via url as an OPTIONAL parameter
- User URL:
- 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
- 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,” .)
- 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:
- Header:
- The Consumer Application will also get a URI to the User resource via Content-Location header:
- The Consumer Application will access the User's data using the Access Token and Token Secret
| TOC |
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
| TOC |
| [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 |
| Fellowship One API Group | |
| Email: | api@fellowshipone.com |