Introduction
OAuth is an open protocol to allow secure API authorization in a simple and standardized way from desktop and web applications. Acxiom implements the OAuth 2.0 Authorization Framework.
The purpose of this section is to provide developer’s detailed instructions for implementing the OAuth and OpenID functionality built into Acxiom's Identity Association Service. All of the Acxiom APIs Acxiom publishes require OAuth 2.0 authentication.
We have included References on OAuth 2.0 for those who wish to delve deeply into the subject.
Which Grant Type Should I Use?
We strongly suggest you use the client credentials grant type unless you have a compelling reason not to. Please note that if you choose the password grant type you will be required to log onto the system and change your password every 45 days.
Client Credential Grant Type
The Client Credentials grant type lets the caller obtain an access token by just passing in the client id and client secret values. There is no user/resource owner being authenticated in this token. Client credential authorization is for situations where the client application needs to access resources or call functions in the resource server which are not related to a specific resource owner (e.g. user). For instance, obtaining a list of venues from Foursquare does not necessarily have anything to do with a specific Foursquare user.
The caller invokes the token endpoint and the access token is returned.
Figure 1
Flows in Client Credential Grant Type
Because of the nature of the validation to get a token from this grant type, tighter controls are in place for its use. There are additional manual configuration steps needed before a user can use this particular grant type. See the Notes section at the end for more information on that. Also, see the code samples for this grant type to gain further understanding
Step 1: The Partner Application Makes a Token Request to Acxiom
United States (US) or European Union (EU) Access
When a partner application wants access to an Acxiom protected resource, it makes a call to the Acxiom authorization endpoint at https://login.acxiom.com to obtain an OAuth token via client credential grant.
Shown below is an example of the request:
POST /oauth2/default/v1/token HTTP/1.1
Host: https://login.acxiom.com
Content-Type: application/x-www-form-urlencoded
client_id=$CLIENT_ID&client_secret=$CLIENT_SECRET&grant_type=client_credentials
For this request specify the following parameters:
| Parameter | Required | Description |
| client_id | Yes | Obtained at the time of partner application registration. |
| client_secret | Yes | Obtained at the time of partner application registration. |
| grant_type | Yes | Must be “client_credentials” |
Step 2: Acxiom Returns Access Token to Partner Application
If the access token request is valid and authorized, the token server issues the access token. Per the OAuth 2.0 specification, a refresh token is not allowed for the client credentials grant type.
{ "access_token":"$ACCESS_TOKEN","token_type":"Bearer","expires_in":3600 }
The parameters in the response include:
| Parameter | Required | Description |
| access_token | Yes | This is the access token that can be used for subsequent Acxiom service endpoint calls. |
| token_type | Yes | Access token type given. Should always return “Bearer” token types. |
| expires_in | Yes | Expiration time of the access token in seconds. |
| scope* | No | Unused, always returns "empty_default". *Only returned in EU token requests. |
If the token request is invalid or unauthorized, the token error response is returned as an application/json in the entity body of the HTTP response. HTTP response code 400 is returned. The token error response specification is here.
Example:
HTTP/1.1 400 Bad Request
Content-Type: application/json
{ "error":"invalid_request","error_description":"Missing grant_type" }
| Parameter | Required | Description | Parameter Values |
|---|
| error | Yes | | invalid_request |
| invalid_client |
| invalid_grant |
| unauthorized_client |
| invalid_scope |
Step 3: Application Requests Access to Protected Resource
Once the application has the OAuth2 access token, it calls the appropriate API endpoint for the service it desires, passing the access token in the authorization header. Below is an example of how the token is used to call a protected resource. This needs to be done in TLS (i.e., https).
GET /v1/people/er/jsmith1test@acxiom.com
HTTP/1.1
Host:api.acxiom.com
Authorization:Bearer $ACCESS_TOKEN
Accept:application/json
| Parameter | Required | Description |
|---|
| authorization header | Yes | This is “Bearer”, space, “access token value” (from the response of the token endpoint) |
Notes
- The API Explorer drop down for this grant type is "Client Credentials.”
- For the Data Services APIs, before tokens generated from this grant type can be used, the client id (also referred to as api key), along with the tenant id, and role, has to be registered with the Data Services product team. To begin this registration, email DSAPI_Team@acxiom.com.
- The registration of a client id in the demo/sandbox environment is separate from the registration of that same client id in the production environment. In order to acquire access for the demo/sandbox, please self-register on the portal.
OAuth Code Examples
The purpose of this section is to provide developers code samples, along with instructions for implementing those code samples. All of the APIs that Acxiom publishes require OAuth 2.0 authentication. These code samples will let you test your connection and make sure you're set up properly before customizing them to meet your needs. We have samples of code available for Java, C# and Python programming languages for the OAuth 2.0 client credential and password grant types. Click the links below to download the samples.
• Java Code Samples• C# Code Samples• Python Code SamplesError Code References
Gateway error codes are prefaced with '000-'.
Error Code
${gatewayErrorCode} | Message
${gatewayResponseMessage} | | 000-1000 | Bad Request |
| 000-1001 | Invalid Host |
| 000-1002 | Invalid Target |
| 000-1003 | Invalid Gateway |
| 000-1010 | Invalid URI |
| 000-1020 | Invalid/missing version |
| 000-1xxx | |
| 000-1004 | Invalid Gateway Error |
| 000-1005 | Invalid Content-type |
| 000-1100 | Forbidden |
| 000-1101 | Forbidden |
| 000-2000 | Rate Limit Exceeded |
| 000-2001 | Rate Limit Exceeded |
| 000-20xx | |
| 000-2100 | Malformed request syntax |
| 000-2101 | Malformed request syntax |
| 000-2102 | Malformed request syntax |
| 000-2110 | Malformed request syntax |
| 000-2111 | Malformed request syntax |
| 000-2112 | Malformed request syntax |
| 000-2120 | Malformed request syntax |
| 000-2121 | Malformed request syntax |
| 000-2122 | Malformed request syntax |
| 000-21xx | |
| 000-3000 | Route failure |
| 000-3010 | Multi-route failure |
| 000-4000 | Forbidden: Invalid path |
| 000-1200 | |
| 000-1201 | Unauthorized |
| 000-1202 | Unauthorized |
| 000-1205 | token parse error |
| 000-1208 | Invalid Gateway Error |
| 000-5000 | Service Unavailable |
| 000-5001 | Bad Request |
| 000-5002 | Unauthorized |
| 000-5003 | Not Found |
| 000-5004 | Not Found |
References
The official OAuth site can be found at http://www.oauth.net. It contains good history about the standard, but is somewhat out of date.
Google. "Using OAuth 2.0 for Login" (Mountain View, CA)
https://developers.google.com/accounts/docs/OAuth2Login
Internet Engineering Task Force. "The OAuth 2.0 Authorization Framework (RFC 6749)" (Fremont, CA: October 2012)
http://tools.ietf.org/html/rfc6749
OAuth.net. OAuth 2.0 Code libraries and code samples.
http://oauth.net/code/
Open ID Foundation. "OpenID Connect Basic Client Profile 1.0" (San Ramon, CA)
http://openid.net/specs/openid-connect-basic-1_0.html
Open ID Foundation. "OpenID Connect 1.0 Specification" (San Ramon, CA: February 26, 2014)
http://openid.net/connect/
Parecki, Aaron. "OAuth 2 Simplified." (Portland, OR: Aaron Perecki, 2014).
http://aaronparecki.com/articles/2012/07/29/1/oauth2-simplified
