USING OAUTH

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
OAuth Client Credential Grant Type in the Data Services API Platform

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

When a partner application wants access to an Acxiom protected resource, it makes a call to the Acxiom authorization endpoint at https://login.myacxiom.com in order to obtain an OAuth client credential grant.

Shown below is an example of the request:

POST /api/v1/auth/oauth2/token
HTTP/1.1Host:https://login.myacxiom.com
Content-Type:application/x-www-form-urlencoded

client_id=3d2f9b04-7d98-4959-85a3-a2bffb92f041&client_secret=b6e2807e-62b9-4a63-b831-e0d22dc49f95&grant_type=client_credentials

For this request specify the following parameters:

ParameterRequiredDescriptionParameter Values
client_idYesObtained at the time of partner application registration. 
client_secretYesObtained at the time of partner application registration. 
grant_typeYesMust 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":"920d8f37-5e10-453a-8e87-8e28ae37cc90","token_type":"Bearer","expires_in":3600 } 

 

The parameters in the response include:

ParameterRequiredDescriptionParameter Values
access_tokenYesThis is the access token that can be used for subsequent Acxiom service endpoint calls. 
token_typeYesMust be “Bearer”. 
expires_inYesExpiration time of the access token in seconds. 

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 BadRequestContent-Type:application/json { "error":"invalid_request","error_description":"Missing grant_type" }
ParameterRequiredDescriptionParameter Values
errorYes 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 920d8f37-5e10-453a-8e87-8e28ae37cc90
Accept:application/json
ParameterRequiredDescription
authorization headerYesThis is “Bearer”, space, “access token value” (from the response of the token endpoint)
Notes
  • The API Explorer drop down for this grant type says "Client Credentials.”
  • For the Data Services APIs, before tokens generated from this grant type can be used to call Data Services APIs, 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 apidevsupport@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 register on the portal.

Password Credential Grant Type

The resource owner password credentials grant type lets the caller obtain an access token by passing in the client_id and client_secret values along with a username and password. For instance, a user could type his Acxiom user name and password (credentials) into the partner application. The partner application could then use the user name and password to access specific resources at Acxiom for which the user has authorization.

If you choose this grant type, you will have to log onto the portal every 45 days to change your password.

The following sequence diagram shows the flows in a successful process.

Figure 2
Flows in Resource Owner Password Credential Grant Type
OAuth Password Credential Grant Type in the Data Services API Platform

The caller invokes the token endpoint and the access token is returned.

Step 1: The Partner Application Makes a Token Request to Acxiom

When a partner application wants access to an Acxiom protected resource, it makes a call to the Acxiom authorization endpoint at https://login.myacxiom.com, passing both the username and password, in order to obtain an OAuth client credential grant. It may have acquired the username/password directly from the user via a screen prompt, or may have passed the username/password from another system without any user input.

Shown below is an example of the request:

POST /api/v1/auth/oauth2/token
HTTP/1.1 Host:https://login.myacxiom.com
Content-Type:application/x-www-form-urlencoded

client_id=3d2f9b04-7d98-4959-85a3-a2bffb92f041&client_secret=b6e2807e-62b9-4a63-b831-e0d22dc49f95&grant_type=password&username=acmerockets\jdoe&password=password

For this request specify the following parameters:

ParameterRequiredDescriptionParameter Values
client_idYesObtained at the time of partner application registration. 
client_secretYesObtained at the time of partner application registration. 
grant_typeYesMust be “password” 
user nameYesUsernameThe username parameter should be of the form tenant_system_name\user_name
• The tenant_system_name can be obtained from the Acxiom Account Center where you manage your user and company information. See site help for how to retrieve this identifier.
• The user_name is the Acxiom username for the user.
Example: AcmeCompany\jsmith
passwordYesPassword 

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 and associated refresh token.

{ "access_token":"920d8f37-5e10-453a-8e87-8e28ae37cc90","token_type":"Bearer","scope":"email openid profile company","expires_in":604800,"refresh_token":"bd1d8bef-85d6-4d31-b59a-ea8d54e4c4a6" } 

The parameters in the response include:

ParameterRequiredDescription
access_tokenYesThis is the access token that can be used for subsequent Acxiom service endpoint calls.
token_typeYesMust be “Bearer”.
expires_inYesExpiration time of the access token in seconds.
refresh_tokenYesMay be used to obtain a new token when the access_token is expired.

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 BadRequest Content¬Type:application/json { "error":"invalid_request","error_description":"Missing grant_type" } 
ParameterRequiredDescriptionParameter Values
errorYes 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 920d8f37-5e10-453a-8e87-8e28ae37cc90
Accept:application/json
ParameterRequiredDescription
authorization headerYesThis is “Bearer”, space, “access token value” (from the response of the token endpoint)

Token Expiration

Refreshing the OAuth 2.0 Access Token

When the access token obtained using the password credential grant type has expired, the partner application can call the token endpoint with the refresh token to get a new access token without having to go through the user authorization process again, not having to specify the username and password again. Aside from being able to bypass the user authorization process, it is essentially the same as getting a new access token. Partner applications can choose either to obtain a new access token by utilizing the refresh token or by making a new password credential grant type request. If the partner application is using client credential grant type, there is no refresh token available and a new client credential grant type request must be made to obtain a new access token. TLS (i.e. https) is required.

POST /api/v1/auth/oauth2/token
HTTP/1.1
Host: login.myacxiom.com
client_id=891de212¬d3cb¬4482¬8c70¬76b647d7eb32&client_secret=217dc803¬0fa1¬48b4¬a362¬492f1dea694d&grant_type=refresh_token&refresh_token=cd6c8702¬d651¬4821¬91f1¬cae034670eac

ParameterRequiredDescriptionParameter Values
refresh_tokenYesThis is the refresh_token code returned by Acxiom. 

client_id

YesObtained at the time of partner application registration. 

client_secret

YesObtained at the time of partner application registration. 

grant_type

YesMust be “refresh_token” 
Implementation Notes
  •  The refresh token is normally returned as part of the access token (except when using the client_credentials grant type).
  •  Refresh tokens expire 7 days after the access token.
  •  The refresh token can be used any time before it expires. The long validity period (relative to the access token) allows the refresh token to be used after the access token has expired.
  •  The refresh token is single use only.  Once it's been used, it cannot be used again.

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 Samples

Error Code References

Gateway error codes are prefaced with '000-'.

Error Code
${gatewayErrorCode}
Message
${gatewayResponseMessage}
000-1000Bad Request
000-1001Invalid Host
000-1002Invalid Target
000-1003Invalid Gateway
000-1010Invalid URI
000-1020Invalid/missing version
000-1xxx
000-1004Invalid Gateway Error
000-1005Invalid Content-type
000-1100Forbidden
000-1101Forbidden
000-2000Rate Limit Exceeded
000-2001Rate Limit Exceeded
000-20xx
000-2100Malformed request syntax
000-2101Malformed request syntax
000-2102Malformed request syntax
000-2110Malformed request syntax
000-2111Malformed request syntax
000-2112Malformed request syntax
000-2120Malformed request syntax
000-2121Malformed request syntax
000-2122Malformed request syntax
000-21xx
000-3000Route failure
000-3010Multi-route failure
000-4000Forbidden: Invalid path
000-1200
000-1201Unauthorized
000-1202Unauthorized
000-1205token parse error
000-1208Invalid Gateway Error
000-5000Service Unavailable
000-5001Bad Request
000-5002Unauthorized
000-5003Not Found
000-5004Not 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