Brightbox API OAuth improvements

The Brightbox API for Cloud Resources is authenticated using OAuth 2.0.

The OAuth 2.0 spec was still a draft when we first implemented it and has changed quite a bit since then. We’ve recently made some improvements to bring our token endpoint into line with the final spec which makes it easier to use with standard OAuth2 libraries (without affecting backwards compatibility of course!)

OAuth 2.0 Grant types

We currently allow accessing the API using client credentials (using API clients) or using a user’s own login credentials (using OAuth applications).

Client Credentials using API clients

This is the simple Client Credentials (client_credentials) grant type. API clients can only access the account that they belong to.

API client credentials are an identifier and secret issued to a single account to access the API, commonly used for authenticating automated systems.

Resource Owner Password Credentials using OAuth applications

This is OAuth 2’s Resource Owner Password Credentials (password) grant type. It is a bit harder to work with since it involves credentials for the client and also for the user.

We currently check that the client’s secret is correct which is optional in the OAuth 2.0 spec but all access rights comes from the user’s details.

Since a user can access several accounts, an additional account_id parameter is required for most API calls to specify which is being used.

Plus, all API activity is associated with the user and shows up in the activity event stream in Brightbox Manager which is ideal when collaborating on an account in teams.

An example in Ruby

The oauth2 gem is a nice little wrapper around Faraday that adds support for standard OAuth2.

Client Credentials

Using an API client to access an account is simpler since it only requires one set of credentials, the API client’s.

require "oauth2"

url = "https://api.gb1.brightbox.com"
client_id = "cli-abcde"
client_secret = "secret"

client = OAuth2::Client.new(client_id, client_secret, site: url)
token = client.client_credentials.get_token

response = token.get("/1.0/servers")
puts response.body

The response.body will be the JSON response, suitable for parsing.

Login Credentials

Since you may be able to access multiple accounts you have set up or are collaborating on, you must specify account_id as a parameters to API calls.

require "oauth2"

url = "https://api.gb1.brightbox.com"
client_id = "app-12345"
client_secret = "secret"

client = OAuth2::Client.new(client_id, client_secret, site: url)
token = client.password.get_token("email@example.com", "pa$$w0rd")

response = token.get("/1.0/servers", params: { account_id: "acc-12345" })
puts response.body

The response.body will be the JSON response, suitable for parsing.

An example in Go

Go has it’s own OAuth 2 package that supports both types of grant types.

Here’s a quick example to get a list of servers in JSON using an API client.

package main

import (
	"fmt"
	"golang.org/x/oauth2"
	"golang.org/x/oauth2/clientcredentials"
	"io/ioutil"
)

func main() {
	oauthConfig := clientcredentials.Config{
		ClientID:     "cli-abcde",
		ClientSecret: "secret",
		TokenURL:     "https://api.gb1.brightbox.com/token",
		Scopes:       []string{},
	}
	oauthClient := oauthConfig.Client(oauth2.NoContext)
	resp, err := oauthClient.Get("https://api.gb1.brightbox.com/1.0/servers")

	if err != nil {
		fmt.Println(err)
		return
	}

	defer resp.Body.Close()

	body, err := ioutil.ReadAll(resp.Body)

	if err != nil {
		fmt.Println(err)
	}

	fmt.Println(string(body))
}

Future Plans

There’s still a couple of OAuth related features we’re working on.

We already support a number of OAuth scopes to limit what your clients and tokens can do and have been using them internally for a while. We’re just working on the GUI and documentation to support them.

We’re also looking at supporting public OAuth applications which no longer need their own credentials. This will superficially allow authentication using username and password but will still perform the OAuth exchange for a token. That should make setting up the Brightbox CLI a whole lot easier.