Authorization

For an app to access financial data by calling the Customer Account Data API, it must be authorized to make the call. The IPP Java Customer Account Data SDK uses OAuth for authorization. When your app makes a call to Customer Account Data service API, the SDK obtains OAuth information from Intuit, builds an instance of Context object and uses the Context object as an authorization parameter in all calls to Customer Account Data services.

Prerequisites:

Create an Customer Account Data Integration

Integrate your app with the Customer Account Data API by creating an Customer Account Data integration at the Intuit Developer site.

Build the Context Object

The following steps describe how the SDK builds the Context object.

Step 1: Create the OAuthAuthorizer Object

A valid OAuthAuthorizer object ensures that an end-user is authorized to access financial data using your app.  When your app uses the DevKit to invoke an Customer Account Data API, the SDK does the following to build an OAuthAuthorizer object:

  1. Obtains the OAuth Access Token and OAuth Access Token Secret for a specified OAuth Consumer Key, OAuth Consumer Secret and SAML Identity Provider ID by using following flow:
    1. Creates a SAML assertion with the specified SAML Identity Provider ID (and the Batch Authentication ID if using batch API call).
    2. Signs the SAML assertion with your X.509 private key certificate.
    3. Applies Base64 URL encoding to the signed SAML assertion.
    4. Passes the Base64 URL encoded SAML assertion to Intuit OAuth Server:
  • With your OAuth Consumer Key in the header
  • In an unencrypted message
  • Via SSL
  1. Parses the response from the Intuit OAuth Server and extracts the OAuth Access Token and OAuth Access Token Secret.
  2. Returns OAuth tokens (optional, See Constructor 2).

Note:

  • The OAuth access token has a validity of one hour.
  • For development, use the Consumer Key, Consumer Secret and SAML Identity Provider ID values from the Development tab of IPP developer site.  For Production, use values available in the Production tab.
  • For more information about OAuth, see OAuth for Customer Account Data.
  1. Proceeds to build the OAuthAuthorizer object using either of the two constructors discussed in the following sections.

Constructor 1

The DevKit sends a SAML assertion to the Intuit OAuth server, obtains the OAuth Access Tokens in the background and proceeds to build the OAuthAuthorizer object.  To re-use the OAuth Access Tokens you may cache the OAuthAuthorizer object and use it until the tokens expires or until the session expires, whichever comes first.

The following code snippet shows how to create an OAuthAuthorizer object with the following parameters:

  • OAuth Consumer Key:  Assigned to your app by Intuit and displayed in the IPP developer site.
  • OAuth Consumer Secret:  Assigned to your app by Intuit and displayed in the IPP developer site.
  • SAML Identity Provider ID:  Also assigned to your app by Intuit and displayed in the IPP developer site.
  • Subject: A User ID or a Batch Authentication ID, depending on the API you are calling:
    • User ID:  A unique ID assigned to an end-user by your app.  It is used while calling non-batch APIs.
    • Batch Authentication ID:  A unique ID assigned to your app by Intuit, if you have requested batch data access when you created the Customer Account Data API integration.  It is assigned when your app is approved for production and displayed in the Production tab of the IPP developer site.  The ID is used while calling batch APIs.
String consumerKey = ... String consumerSecret = ... String samlProviderId = ... String subject = ... OAuthAuthorizer oauth = new OAuthAuthorizer(consumerKey, consumerSecret,                                             samlProviderId, subject);

Constructor 2

The DevKit uses the OAuthUtil class to obtain OAuth Credentials and then retrieves the OAuth Access Tokens by using the getOAuthTokens().  You can then pass the OAuthCredentials object as a parameter to build the OAuthAuthorizer object.  To re-use the OAuth Access Tokens, you may cache the OAuthCredentials object or the OAuthAuthorizer object and use it until the tokens expire or until the session expires, whichever comes first.

The following steps show how to obtain OAuth Access Tokens and build the OAuthAuthorizer object:

  1. Build the OAuthUtil object by passing the following parameters:
  • OAuth Consumer Key: Assigned to your app by Intuit and displayed in the IPP developer site.
  • SAML Identity Provider ID: Assigned to your app by Intuit and displayed in the IPP developer site.
  • Subject: A User ID or a Batch Authentication ID, depending on the API you are calling:
    • User ID: A unique ID assigned to an end-user by your app. It is used while calling non-batch APIs.
    • Batch Authentication ID: A unique ID assigned to your app by Intuit, if you have requested batch data access when you created the Customer Account Data API integration. It is assigned when your app is approved for production and displayed in the Production tab of IPP developer site. The ID is used while calling batch APIs.
String consumerKey = ... String samlProviderId = ... String subject = ... OAuthUtil oauthUtil = new OAuthUtil(consumerKey,samlProviderId, subject);
  1. Use the reference to the OAuthUtil object created in step 'a' to retrieve OAuth Access Tokens and create the OAuthCredentials object.
OAuthCredentials oauthCredentials = oauthUtil.getOAuthTokens();

Notes:

  • You may fetch the OAuth Access Tokens from the OAuthCredentials object and cache the access tokens.  Following is a sample code:
oauthCredentials.getAccessToken(); oauthCredentials.getAccessTokenSecret();
  • If you have obtained the OAuth Access Token and the OAuth Access Token Secret by implementing routines outside of the DevKit, ignore step 'a' and use the following constructor to build the OAuthCredentials object by passing the Access Tokens:
OAuthCredentials oauthCredentials = new OAuthCredentials(); oauthCredentials.setAccessToken("accessToken"); oauthCredentials.setAccessTokenSecret("accessTokenSecret");
  1. Create the OAuthAuthorizer Object.
    The following code snippet shows how to create an OAuthAuthorizer object with the following parameters:
  • OAuth Consumer Key:  Assigned to your app by Intuit and displayed in the IPP developer site.
  • OAuth Consumer Secret: Assigned to your app by Intuit and displayed in the IPP developer site.
  • oauthCredentials: Acquired by your app during the Step 'b' above.
String consumerKey = ... String consumerSecret = ... OAuthAuthorizer oauth = new OAuthAuthorizer(consumerKey, consumerSecret, oauthCredentials);

Step 2: Create an Instance of the Context Class

The following code snippet shows how to create an instance of the Context class using the reference to the OAuthAuthorizer object:

Context context = new Context(oauth)