Using OAuth 2.0 with Dotdigital

Overview

Dotdigital uses OAuth 2.0 to provide authorisation. The OAuth 2.0 authorisation protocol provides the means for an Dotdigital user to log into their account just once, removing the need for them to constantly re-enter their credentials. When they wish to use their Dotdigital account, they just have to click a specially crafted URL.

🚧

Authorisation for API requests

OAuth 2.0 is only used to provide authorisation for user log-ins. Requests made using the Dotdigital API use Basic Auth.

OAuth 2.0 is a relatively simple protocol built on top of HTTP. There are five key stages in using it to provide authorisation for a user’s Dotdigital account:

1. Registering with Dotdigital
Only pre-registered clients may call the Dotdigital OAuth 2.0 API.
2. Obtaining an authorisation code
When you want to be able to provide a user with OAuth 2.0 authorisation, you must first get the user’s authorisation to provide this service. If the user consents, an authorisation code is issued.
3. Exchanging an authorisation code for an access and refresh token
The authorisation code is then exchanged for an access token and refresh token. Access tokens are used to log a user in to Dotdigital, while refresh tokens are used to obtain more access tokens in the future.
4. Using an access token to log a user in
The access token is appended to a URL for a Dotdigital page; “create a new campaign”, “view your campaigns’ reports”, etc. This URL may be embedded in your web application, allowing a user to click the link and log in to their Dotdigital account.
5. Obtaining more access tokens
For security reasons, access tokens have short lives. You can create new access tokens using the refresh token issued in stage 3.

In the following sections, each stage will be examined in detail.

Registering with Dotdigital

To register to use OAuth you will need to be on an Enterprise licence and to contact your account manager. When you register with Dotdigital for use of the OAuth 2.0 service, you must provide a URL that will be used to receive authorisation responses. This is known as the redirect URI. The redirect URI must:

• Use the HTTPS scheme (http://example.com/callback is not allowed)
• Not contain a fragment (https://example.com/callback#fragment) is not allowed

🚧

The URL (redirect URI) is case sensitive

The URL you provide us with must be the same one you're using once you're set up, including the case being used. If it's not, you'll encounter problems.

When registration is complete you will receive:

1. A client ID - a string that is used to identify you when making authorisation and tokens requests.
2. A client secret - a string that is used to authenticate you when making token requests. This must be kept secret.

📘

Note for any accounts with child accounts

Registering your main Dotdigital account for OAuth access will by default enable all your child accounts for OAuth authentication. Any new accounts just need to complete the initial authorisation phase before obtaining an access and refresh token.

You will need to have an SSL certificate for your application domain. If you do not have one already, please speak to your account manager about buying one.

Obtaining an authorisation code

Authorisation codes are the starting block in providing sign-on authorisation for a user - you send a request to the Dotdigital OAuth 2.0 API indicating that you would like to provide sign-on authorisation for a user. The user is then prompted to log in (signifying their acceptance for your application to provide sign-on authentication) and once their credentials have been validated, an authorisation code is sent to your redirect URI.

This code represents a user’s permission to provide sign-on authorisation for them. It is short-lived (it expires in 10 minutes) so should be exchanged for an access and refresh token as soon as possible.

Sending the authorisation request

Requests for authorisation codes are sent using a HTTP GET request to https://r1-app.dotmailer.com/OAuth2/authorise.aspx (or with the account's appropriate region URL), with the parameters below added as query string parameters. SSL must be used and plain HTTP connections are refused.

Handling the response

If the authorisation request is well formed and successful, the authorisation server will redirect to the redirect URI supplied in the redirect_uri parameter.

Example request and response

The following is an example of an authorisation request for a client with the identifier QVNY867m2DQozogTJfUmqA%3D%3D and the redirect URI https://testhost.com/callback:

https://r1-app.dotmailer.com/OAuth2/authorise.aspx?redirect_uri=https%3A%2F%2Ftesthost.com%2Fcallback&client_id=QVNY867m2DQozogTJfUmqA%3D%3D&scope=Account&state=somevalue&response_type=code

This will result in a HTTP redirect to this URI:

https://testhost.com/callback?code=6U0XQpAgGC4WbWM2c7a5SQ%3D%3D&state=somevalue

The authorisation code (6U0XQpAgGC4WbWM2c7a5SQ%3D%3D) can be found in the code parameter. Note that the state parameter holds the same value as it did in the authorisation request.

Note that the authorisation code ends in ‘%3D%3D’ because it has already been URL encoded.

Exchanging an authorisation code for an access and refresh token

Once you have your authorisation code, you can exchange it for an access and refresh token.

• Access tokens are included in requests for a user’s Dotdigital private resources, signing in the associated user into Dotdigital. They are short lived (the default expiry time is an hour).
• Refresh tokens are used to generate more access tokens. When an access token expires, you may use the refresh token to generate a new access token without having to obtain a new authorisation code (see the Obtaining more access tokens section).

Sending the token request

Token requests are made using a HTTP POST request to https://r1-app.dotmailer.com/OAuth2/Tokens.ashx (or with the account's appropriate region URL), where the body of the request contains the parameters in the 'application/x-www-form-urlencoded' format. SSL must be used and plain HTTP connections are rejected.

Handling the response

The response returned is a JSON-encoded object. On success, the object will contain the following fields:

If an error occurred, the object will contain the following fields:

Example request and response

The following is an example of a token request, using the authorisation code value 5RFR3oRx5yF3I5LIbZ1g7w%3d%3d. Certain HTTP headers have been omitted for brevity:

POST https://r1-app.dotmailer.com/OAuth2/Tokens.ashx HTTP/1.1
Content-Type: application/x-www-form-urlencoded
client_id=QVNY867m2DQozogTJfUmqA%3D%3D&
redirect_uri=https%3a%2f%2flocalhost%3a10999%2fcallback.aspx
&client_secret=SndpTndiSlhRawAAAAAAAA%3D%3D&
&grant_type=authorization_code

This will generate the JSON-encoded response:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{"access_token":"SJDXSNANPMTaUbIKYFHdYQ%3D%3D","token_type":"bearer","expires_in":3600,"refresh_token":"9OjH6t1-ugikUduoNBcr-g%3D%3D"}

Note that the access token ends in ‘%3D%3D’ because it has already been URL encoded.

Using an access token to log a user in

Forming an authorisation sign-on URL

Once you have successfully received an access token, you can use it to log a user in. Access tokens are appended to requests for Dotdigital pages using the oauthtoken query string parameter. Generally, any URL generated by the Dotdigital website can have the oauthtoken query string parameter attached and it will authenticate a user.

To allow a user to view the reporting section of the Dotdigital site which has the URL http://r1-app.dotdigital.com/Reporting/ and given the access token 'testokenval', the resulting URL would look like this:

https://r1-app.dotdigital.com/Reporting/?oauthtoken=testtokenval

If the access token has expired, the user is prompted to log in (as they normally would).

Beware of tokens expiring and slow users!

When generating sign-on authorisation URLs, it is not recommended that you insert them directly into your pages. Tokens may not have expired at page generation time but content caching or 'slow' users may mean the access token expires before the user clicks on the hyperlink.

Instead, it is recommended that sign-on authorisation URLs are created exactly when they are needed - when a user of your application has signified that they wish to log into their Dotdigital account (an HTTP redirect can accomplish this).

Obtaining more access tokens

Access tokens will expire in a short period of time for security reasons. When you wish to acquire a new access token, you can issue a refresh token request.

Sending the refresh token request

Refresh token requests are made in a very similar manner to token requests. The request is made using a HTTP POST request to https://r1-app.dotmailer.com/OAuth2/Tokens.ashx (or with the account's appropriate region URL), over SSL and with the body of the request containing the parameters in the 'application/x-www-form-urlencoded' format.

Handling the response

The response returned is a JSON-encoded object. On success, the object will contain the following fields:

Useful external resources

The following links might be useful in understanding OAuth 2.0 and the Dotdigital implementation.

• IETF OAuth 2.0 draft spec, version 25. The draft specification and version the Dotdigital implementation was based on.
• Google OAuth 2.0 API docs. While not directly related to the Dotdigital implementation, it gives a good overview of the OAuth 2.0 protocol, complete with some lovely diagrams.