Fellowship One REST API

API Index | Authentication | HTTP Status Codes | HTTP Headers | Single Sign On Client Implementation | Single Sign On Host Implementation

Authentication

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 applications without web based end points.

OAuth Core 1.0 references and definitions can be viewed : http://oauth.net/core/1.0/
Fellowship One OAuth Extension document can be viewed here
Fellowship One OAuth Extension repository can be accessed here

Multi-Tenant Configuration

• Step 1 - Establish global access via Service Provider
• Step 2 - Manage relationships between the Consumer applications and the Tenant
• Step 3 - Manage relationships between the Consumer applications and the User

Authentication Protocols

• Fellowship One Basic OAuth
• 1st Party Trusted Consumer: Credentials based | Token based | OAuth
• 2nd Party Trusted Consumer: Credentials based | Token based | OAuth
• 3rd Party Consumer: OAuth

Appendix and Definitions

Multi-Tenant Configuration

Step 1 Before any Consumer applications can access any Tenant data the Tenant must first enable access to thier data via Fellowship One Portal

Step 2 Next the Tenant must establish a relationship with and 1st, 2nd, or 3rd party applications via Fellowship One Portal that they want thier Users to be able to use

Step 3 Finally, Users of the Tenant can create / view / delete relationships (Access Tokens) with all Consumer Applications that the Tenant has established a relationship with

Authentication Protocols

OAuth URIs

Request Token:

• [GET] https://demo.staging.fellowshiponeapi.com/v1/Tokens/RequestToken
• [POST] https://demo.staging.fellowshiponeapi.com/v1/Tokens/RequestToken
  • Required header - Content-Length: 0

User Authorization

• Redirect: Portal User: https://demo.staging.fellowshiponeapi.com/v1/PortalUser/Login
• Redirect: Weblink User: https://demo.staging.fellowshiponeapi.com/v1/WeblinkUser/Login

Access Token:

• [GET] https://demo.staging.fellowshiponeapi.com/v1/Tokens/AccessToken
• [POST] https://demo.staging.fellowshiponeapi.com/v1/Tokens/AccessToken
  • Required header - Content-Length: 0

Trusted URIs (requires credentials as specified for 1st and 2nd Party authentication):

Access Token

• Portal User: [GET] https://demo.staging.fellowshiponeapi.com/v1/PortalUser/AccessToken
• Portal User: [POST] https://demo.staging.fellowshiponeapi.com/v1/PortalUser/AccessToken
  • Required header - Content-Length: 0
• Weblink User: [GET] https://demo.staging.fellowshiponeapi.com/v1/WeblinkUser/AccessToken
• Weblink User: [POST] https://demo.staging.fellowshiponeapi.com/v1/WeblinkUser/AccessToken
  • Required header - Content-Length: 0

2nd Party credentials based authentication basic workflow

1. Consumer Application collects the User's credentials directly
2. Consumer Application concatenates the user name and password with a space and base64 encodes the credentials
3. 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
4. Consumer Application posts them to the following URI depending on what user type your using:
   • This request is signed using OAuth signing requests
   • Portal User: [POST] https://demo.staging.fellowshiponeapi.com/v1/PortalUser/AccessToken
   • Weblink User: [POST] https://demo.staging.fellowshiponeapi.com/v1/WeblinkUser/AccessToken
5. 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
6. The Consumer Application will also get a link to the person via Content-Location header:
   • Ex. Content-Location=https://demo.staging.fellowshiponeapi.com/v1/People/123
7. The Consumer Application will access the User's data using the Access Token and Token Secret

3rd Party OAuth based authentication basic workflow

1. Consumer Application requests an unauthenticated Request Token
   • This request is signed using OAuth signing requests
   • [GET] https://demo.staging.fellowshiponeapi.com/v1/Tokens/RequestToken
   • [POST] https://demo.staging.fellowshiponeapi.com/v1/Tokens/RequestToken
     • Required header when using the [POST] verb - Content-Length: 0
2. 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
3. Consumer Application requests user authorization via redirect
   • This request is signed using OAuth signing requests
     • The Consumer Application will sign the request using the Request Token and Token Secret
     • The Consumer Application will pass the Request Token via url
       • ex. https://demo.staging.fellowshiponeapi.com/v1/PortalUser/Login?oauth_token=afd011d3-fbd3-4c69-8326-a24fad8d0c34
     • The Consumer Application may pass a callback url via url (optional)
       • ex. https://demo.staging.fellowshiponeapi.com/v1/PortalUser/Login?oauth_token=afd011d3-fbd3-4c69-8326-a24fad8d0c34&oauth_callback=http://www.myconsumerapp.com/home
   • Portal User: https://demo.staging.fellowshiponeapi.com/v1/PortalUser/Login
     • User logging in must be linked to a person in the Fellowship One Portal application
   • Weblink User: https://demo.staging.fellowshiponeapi.com/v1/WeblinkUser/Login
4. The User enters thier credentials in using the Service Provider's interface
5. 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 written 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
       • ex. Redirect http://www.myconsumerapp.com/home?permissiondenied=The+user+has+denied+access+to+all+protected+resources. (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
6. 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 signing requests
     • 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://demo.staging.fellowshiponeapi.com/v1/Tokens/AccessToken
   • [POST] https://demo.staging.fellowshiponeapi.com/v1/Tokens/AccessToken
     • Required header when using the [POST] verb - Content-Length: 0
7. 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
8. The Consumer Application will also get a link to the person via Content-Location header:
   • Ex. Content-Location=https://demo.staging.fellowshiponeapi.com/v1/People/123
9. The Consumer Application will access the User's data using the Access Token and Token Secret

Debugging (Available in test evironments ONLY)

The following headers will be retuned only if an OAuth signing error occurs:

• oauthsignaturebase_debug <- this value represents the base signature that the API created to check against the one the consumer sent over
• oauthsignaturedebug <- this value represents the signature that the API created from the base signature. Used to check against the signature that the consumer sent over

Fellowship One Basic OAuth

1st Party credentials based authentication

1st Party token based authentication

2nd Party credentials based authentication

2nd Party token based authentication

3rd Party OAuth

Appendix and Definitions

• 1st Party Consumer Applications: Defined as applications written and made public by the Service Provider (Fellowship Technologies). They will be marked as Public and as Trusted.

• 2nd Party User Trusted Consumer Applications: Defined as applications written and made private by the Consumer and used by the Consumer's(or Tenant's) Users. They will be marked as Private.

• 3rd Party Consumer Applications: Defined as applications written and made public for consumption across Tenants. They will be marked as Public.

• Service Provider: Fellowship Technologies allows access to resources via OAuth.

• Consumer: 3rd party / Tenant - 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.

• 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.