Authentication using OAuth 2.0 - Server and Client Flows

[webservices]

This information is for our older v1 API and is not current.

If you are using our v2 or v3 APIs, please see the following links instead:

v2: http://developer.constantcontact.com/docs/authentication/authentication.html
v3: https://v3.developer.constantcontact.com/api_guide/auth_overview.html

---

Constant Contact supports using the both the OAuth 2.0 server flow and client flow for authentication. These are much simpler flows than the equivalents from OAuth 1.0a. The server flow is best when your application is using the Constant Contact API from within your webserver code (for example, from within PHP or Java running on the server.) The client flow makes it simple to obtain an access token when calling the Constant Contact APIs from client langauges such as javascript.

The specification of OAuth 2.0 can be found at

http://tools.ietf.org/html/draft-ietf-oauth-v2-15#section-3

Server Flow

Constant Contact supports the Authorization Code/Web Server flow specified by the OAuth 2.0 protocol. The steps in the flow are illustrated in the diagram below, which is reproduced from the above URL:

The Authorization Server role has been implemented by Constant Contact so that client applications can enable their users to authenticate using the OAuth 2.0 Web Server flow. There are 2 steps required in order to obtain an access token, as described below.

I. Authorization request

This step consists of accessing the authorization endpoint in the authorization server to do two things:

1. Authenticate the resource owner.
2. Get an authorization grant from resource owner for the client application to access his resource in CTCT.

The URL is of the form:

https://oauth2.constantcontact.com/oauth2/oauth/siteowner/authorize

An example of how to call this URL is shown below:

https://oauth2.constantcontact.com/oauth2/oauth/siteowner/authorize?

response_type=code&

client_id=API_KEY&

redirect_uri=https://somedomain

The parameters for this call are described in the following table:

Parameter	Description
response_type	This parameter MUST always be set to the string ‘code’.
client_id	This parameter MUST always be set to the value of the API key that identified the client application. See http://community.constantcontact.com/t5/Documentation/API-Keys/ba-p/25015 for information on how to generate an API key.
redirect_uri	An HTTPS URI that the authorization server will redirect to after the initial authorization request is processed.

Upon successful authorization, the redirect_uri will be called with two parameters appended to it:

‘code’  - the unique code generated for this request - to be used in the token call later in the flow.

'username'  - the name of the Constant Contact user that is authenticating.  For example,

https://somedomain?code=dkdd93ldd0ldf03ds0d&username=joesflowers

The server code for handling the redirect should extract and save the ‘code’ parameter value, as it is required as part of the next step in the flow. The 'username' value should also be saved so that URLs to the user's data can be constructed.

If the call to the authorization server is malformed, or if the user denies access, the response will be of the form:

https://somedomain?error=(predefined values)

where the pre-defined error codes can be found here.

NOTE: We do not currently support scope for our clients, so the ‘scope’ parameter mentioned in the OAuth 2.0 specification is not required.

II. Access token request

To authenticate the client and exchange the code for an access token, the client application needs to do a POST to our token URL. In this step, authorization server will:

1. Check that the authorization code was issued to the same client that is making the token request.
2. Authenticate the client.

The URL is of the form:

https://oauth2.constantcontact.com/oauth2/oauth/token

The client application must include the redirect_uri, client_id, client_secret, grant_type and code parameters in this call. An example of how to call the request token endpoint is shown below:

https://oauth2.constantcontact.com/oauth2/oauth/token?

grant_type=authorization_code&

client_id=rapportive&

client_secret=somesecret&

code=dkdd93ldd0ldf03ds0d&

redirect_uri=https://somedomain

The parameters for this call are described in the table below:

Parameter	Description
grant_type	This parameter MUST always be set to the string ‘authorization_code’
client_id	This parameter MUST always be set to the value of the API key that identifies the client application. See http://community.constantcontact.com/t5/Documentation/API-Keys/ba-p/25015 for information on how to generate an API key.
client_secret	This parameter MUST always be set to the value of the API secret associated with the API key. Anyone requesting an API key will also be assigned an API secret; see the link above for details on how to request a key and secret.
code	The value of the ‘code’ parameter that was passed into the redirect_uri as part of the original authorization request (section I above).
redirect_uri	An HTTPS URI that token request endpoint will redirect to after the token request is processed.

If successful, the call to the request token endpoint will return a status of 200, and the response body will contain a JSON object of the following form:

{

 "access_token":"the_token",

 "expires_in":315359999,

 "token_type":"Bearer"

}

Here 'the_token' represents the token string returned by the server, typically a hyphen-separated hexadecimal string. 

Client Flow

The Constant Contact API also supports the OAuth 2.0 implicit flow, also known as the client flow. This flow is intended for javascript and other client side languages and makes it easy to obtain an access token for web 'mashups' and similar applications. There is only one step required to obtain a token, which is for the client application to initiate the flow. An example URL to use for initiating the client flow is:

https://oauth2.constantcontact.com/oauth2/oauth/siteowner/authorize?

response_type=token&

client_id=API_KEY&

redirect_uri=https://somedomain

The parameters for this call are described in the following table:

Parameter	Description
response_type	This parameter MUST always be set to the string ‘token’.
client_id	This parameter MUST always be set to the value of the API key that identified the client application. Seehttp://community.constantcontact.com/t5/Documentation/API-Keys/ba-p/25015 for information on how to generate an API key.
redirect_uri	An HTTPS URI that the authorization server will redirect to after the initial authorization request is processed. This must be the same as the redirect URI associated with the API key in 'client_id'.

Once initiated, the flow proceeds as follows (assuming no errors):

1. The user of the application is directed to login.constantcontact.com

2. The user authenticates (either with Constant Contact or accepted 3rd party credentials such as Yahoo).

3. Upon successful authentication, the user is directed to the Grant Access page, and grants access to the application identified by 'client_id'.

4. The user is finally directed back to the original application. An access token is appended to the redirect uri as a hash fragment of the form:

#access_token=the_token&type=Bearer

where 'the_token' represents the actual token string returned by the authorization flow, which as with the server flow is typically a hyphen-separated hexadecimal string.

Once the token has been obtained, programmers need to make one more call to determine the username of the user who authorized the application. To do this, perform a POST to the following URI:

https://oauth2.constantcontact.com/oauth2/tokeninfo.htm

The POST body should contain:

access_token=the_token

 where 'the_token' is the actual value of the access token obtained eariler from the authentication flow. Finally, make sure to set the content type as follows before making the call:

Content-Type: application/x-www-form-urlencoded

 Upon success, this call will return a JSON object similar to the following:

{
 "client_id": "some_api_key",
 "user_name": "user_name_associated_with_token",
 "expires_in": 3600
}

Programmers can then parse this object to retrieve the value of the 'user_name' parameter. Use this parameter along with the access token to formulate calls to the APIs. If an error occurs retrieveing the user_name, an HTTP 400 error will be returned, along with an error object in the response body, similar to the following:

{
 "error": "invalid_token",
 "error_description": "Bad Request"
}

Since the client flow is used primarily by Javascript programmers, here is a simple jQuery Javascript function that can be used to make the call specified above:

function jsgetUserName(token){
	var options = {
		url: 'https://oauth2.constantcontact.com/oauth2/tokeninfo.htm',
		type: "POST",
		contentType: 'application/x-www-form-urlencoded',
		data: encodeURI('access_token=' + token),
		success: function(data, textStatus, jqXHR){
			alert(data);
		}
	};
	jQuery.ajax(options);
}

Note, this simple function displays a message dialog with the JSON returned from the call - it is up to individual programmers to implement the appropriate 'success' function to extract the user_name and store it in a secure fashion along with the access token for each authenticated user.

Using Access Tokens

Once obtained from either the server or client flows, the access token remains valid indefinitely. We do not currently expire access tokens nor provide client applications with a refresh token to re-generate an access token.

The access token should be used as a substitute for Constant Contact user credentials. To make an authenticated call to the Constant Contact API, the application can use one of two approaches:

 - Add a header to the HTTP request:

Authorization:Bearer the_token

OR

- append the token as a parameter to REST URIs, as in:

https://api.constantcontact.com/ws/customers/joesflowers/campaigns?access_token=the_token

This URI would return the XML containing the list of campaigns for user 'joesflowers' and is the simplest way to use the Constant Contact API with an OAuth 2 token.