Previous: Authentication | Up: Introduction | Next: Groups

HTTP Basic Authentication

Background

While most of the API functions employ an internal authentication strategy (the credentials section of the request body), a few require HTTP Basic Authentication instead. This allows configuring preexisting tools, which were not specifically designed to use this API, to use basic services of this API.

For example, the CloudForge Activity Streams data formats and functions are based on the industry standard Activity Streams formats and functions. The standards allow for HTTP Basic Authentication, but not for the proprietary CloudForge credentials.

For the user

CloudForge authentication requires three values:

HTTP Basic Authentication, on the other hand, involves only two values,

For purposes of this API, we bridge this gap by composing the HTTP Basic Authentication userid from the CloudForge domain and login.

Suppose user Joe Jetson works for the Kitty Kind Katfood Company, with

Then to use HTTP Basic Authentication with the CloudForge API, he should provide HTTP Basic Authentication credentials of

For the developer

The details of how to program HTTP Basic Authentication will depend on the chosen programming environment, but they basically fall into two possible techniques.

Within the URL

Nearly any REST client packge will allow you to embed the HTTP Basic Authentication credentials in the URL:

https://kittykind_joe:miaou@app.cloudforge.com/api/1/activity_streams

Since the CloudForge API is accessed using https, which encrypts the URL as well as the message body, the credentials are secure while in transit over the Internet.

In the Authorization header

The HTTP standard also defines an Authorization header, which can be used to carry the HTTP Basic credentials instead of the URL. This provides basically the same security while in transit through the Internet, but may be more convenient for the application's internal displays.

For example, the application may have a dialog where the user can enter credentials for a particular connection:

In such a dialog, the URL is presented in ordinary, readable text, but the password (at the least) is not actually displayed, even when typed; instead, something like a line of dots is displayed. This is much easier to program if the developer can keep these three strings separately, rather than slicing up the URL before displaying.

Examples

Here are examples of each approach using the Ruby RestClient library.

URL

response = RestClient.get "https://kittykind_joe:miaou@app.cloudforge.com/api/1/activity_streams/id-of-an-activity"

Header

restclient = RestClient::Resource.new( "https://app.cloudforge.com", # URL "kittykind_joe", # userid (domain_login) "miaou") # password response = restclient.get "https://app.cloudforge.com/api/1/activity_streams/id-of-an-activity"