Database

Copula provides a schema file for persistent storage of access tokens. Storing tokens in the database is optional but recommended, and is assumed to be the default method.

Additionally, each OAuth API is split into two datasources, both of which must be configured in your app’s Config/database.php file.

An example is given below:

<?php
	class DATABASE_CONFIG {
	var $cloudprint = array(
		'datasource' => 'Cloudprint.CloudprintSource',
		'login' => 'username',
		'password' => 'secretPassword',
		'authMethod' => 'OAuthV2',
		'access_token' => '',
		'refresh_token' => ''
	);

	var $cloudprintToken = array(
		'datasource' => 'Copula.RemoteTokenSource',
		'login' => 'username',
		'password' => 'secretPassword',
		'authMethod' => 'OAuthV2',
		'scheme' => 'https',
		'authorize' => 'o/oauth2/auth',
		'access' => 'o/oauth2/token',
		'host' => 'accounts.google.com',
		'scope' => 'https://www.googleapis.com/auth/cloudprint',
		'callback' => 'https://mysite.com/oauth2callback'
	);
	}

The second configuration block is used to retrieve access and request tokens from the OAuth provider, and the first one is used for the actual API operations. Keys common to both blocks are:

login

This must equal the consumer_key (OAuth) or client_id (OAuth 2.0)

password

This must equal the consumer_secret (OAuth) or client_secret (OAuth 2.0)

authMethod

This must equal either 'OAuth' or 'OAuthV2'. Those are the only allowed values.

scheme

Valid values: 'http' or 'https'. Many, if not most, APIs prefer you to use HTTPS.

Also common to both configurations is the 'datasource' key, which is required by CakePHP. By default the API datasource should be set to 'Copula.ApisSource' and the Token datasource should be set to 'Copula.RemoteTokenSource'. You may use any value for this key provided that the referenced class extends the default one.

API Datasource

No additional configuration beyond the above is required, but if your app will only ever use one set of credentials, you may manually set them in the API Datasource config using the following keys:

access_token

This must equal to the access token given to you by the OAuth provider for both OAuth and OAuth 2.0 datasources.

token_secret

(optional) If using OAuth, this must be equal to the access token secret given by your OAuth provider. If using OAuth 2.0, omit this field.

refresh_token

(optional) If using OAuth 2.0, this field must be equal to the refresh token given by your OAuth provider. If not using OAuth 2.0, omit this field.

At the time of this writing, actually using static OAuth 2.0 credentials is probably a bad idea. Not only that, but supporting that use case is not high on the feature list. For a more thorough discussion, consult Extending the datasource.

Token Datasource

In addition to the aforementioned keys belonging to both configs, the following keys are used in the Token datasource config. Note: there is a naming convention here: the name of the Token database config needs to be the same as the matching API config plus the string 'Token'. Future versions may combine the two configs and dynamically generate the proper info. If you're reading this, that hasn't happened.

host

This must be equal to the hostname of the OAuth provider's credential server. This may or may not differ from the host used to provide the actual API services.

authorize

This contains the relative path for the authorization endpoint of the OAuth provider's credential server, without a prefixed slash.

access

This contains the relative path for the access token endpoint of the OAuth provider's credential server, without a prefixed slash.

request

(optional) This contains the relative path for the request endpoint of the OAuth provider's credential server, without a prefixed slash. Not used in OAuth 2.0

scope

(optional) Some API providers require this field; consult your API documentation for more details.

callback

This must contain the address on your server to which the user will be redirected after authorization.

For more Detail on the OAuth authorization process, consult the following links:

• OAuth v1 information
• OAuth v2 information

For the details on how these methods have been implemented, see Component Functions.