JDBC Driver for Bullhorn CRM

Build 20.0.7654

Custom Credentials

When to Use a Custom OAuth App

You must create a custom OAuth app to connect to the Bullhorn CRM.

Desktop Authentication with a Custom OAuth App

Follow the steps below to authenticate with the credentials for a custom OAuth app. See Creating a Custom OAuth App.

Scenario 1: Authenticate with a Verifier Code

Making any changes to your OAuth app (such as the CallbackURL) requires reaching out to Bullhorn CRM directly, which can be a time-consuming process.

As such, it's highly recommended that you instead use an OAuthVerifier to connect. To obtain a verifier, you will need an OAuth Authorization URL.

Retrieving an OAuth Verifier Code

Construct your authorization URL as follows:
https://<authurl for your data center>/oauth/authorize?client_id=<your OAuth client id>&response_type=code

For example, if you had data center "CLS5", the authentication URL would be "https://auth.bullhornstaffing.com/oauth/authorize?client_id=your_client_id&response_type=code".

Please refer to the list here to determine the authentication URL for your data center.

Next, retrieve the OAuth verifier code as follows:

  1. Open your authorization URL in a browser. Log in and grant permissions to the driver. You are then redirected to the callback URL, which contains the verifier code.
  2. Save the value of the verifier code.

Get and Refresh the OAuth Access Token

After setting the following, you are ready to connect:

  • OAuthVerifier: Set this to the OAuth Verifier code obtained previously.
  • DataCenterCode: Set this to the respective data center your account is connected with. Find the list of the data centers here. For example, CLS33.
  • OAuthClientId: Set this to the client Id assigned when you registered your app.
  • OAuthClientSecret: Set this to the client secret assigned when you registered your app.
  • InitiateOAuth: Set this to GETANDREFRESH. You can use InitiateOAuth to avoid repeating the OAuth exchange and manually setting the OAuthAccessToken.
The driver then completes the OAuth process:
  1. The process finalizes with the access token returned from the Bullhorn CRM API.
  2. Refreshes the access token when it expires.
  3. Saves OAuth values in OAuthSettingsLocation to be persisted across connections.

Scenario 2: Authenticate with a Custom CallbackURL

You also have the option of requesting a custom callback URL (for example, http://localhost:33333) from Bullhorn CRM. If you have been provided with a custom CallbackURL, you can set the following to connect to data:

  • CallbackURL: Set this to the custom callback URL provided by Bullhorn CRM.
  • DataCenterCode: Set this to the respective data center your account is connected with. Find the list of the data centers here. For example, CLS33.
  • OAuthClientId: Set this to the client Id assigned when you registered your app.
  • OAuthClientSecret: Set this to the client secret assigned when you registered your app.
  • InitiateOAuth: Set this to GETANDREFRESH. You can use InitiateOAuth to avoid repeating the OAuth exchange and manually setting the OAuthAccessToken.
The driver then completes the OAuth process:
  1. The process finalizes with the access token returned from the Bullhorn CRM API.
  2. Refreshes the access token when it expires.
  3. Saves OAuth values in OAuthSettingsLocation to be persisted across connections.

Web Authentication with a Custom OAuth App

When connecting via a Web application, you need to register a custom OAuth app with Bullhorn CRM. See Creating a Custom OAuth App. You can then use the driver to get and manage the OAuth token values.

Get an OAuth Access Token

Set the following connection properties to obtain the OAuthAccessToken:

  • OAuthClientId: Set this to the Client Id provided by Bullhorn.
  • OAuthClientSecret: Set this to the Client Secret provided by Bullhorn.

You can then call stored procedures to complete the OAuth exchange:

  1. Call the GetOAuthAuthorizationURL stored procedure. Set the AuthMode input to WEB and set the CallbackURL input to the Redirect URI.

    The stored procedure returns the URL to the OAuth endpoint.

  2. Open the URL, log in, and authorize the application. You are redirected back to the callback URL.
  3. Call the GetOAuthAccessToken stored procedure. Set the AuthMode input to WEB. Set the Verifier input to the "code" parameter in the query string of the callback URL.

Refresh the OAuth Access Token

You can set InitiateOAuth to REFRESH to automatically refresh the OAuth access token when it expires, or you can call the RefreshOAuthAccessToken stored procedure to refresh the token manually.

Automatic Refresh

To refresh the token with InitiateOAuth, set the following on the first data connection:

  • OAuthAccessToken: Set this to the access token returned by GetOAuthAccessToken.
  • InitiateOAuth: Set this to REFRESH. You can use InitiateOAuth to avoid repeating the OAuth exchange and manually setting the OAuthAccessToken.
  • OAuthSettingsLocation: Set this to the path where the driver will save the OAuth values, to be persisted across connections.
  • OAuthClientId: Set this to the Client Id provided by Bullhorn.
  • OAuthClientSecret: Set this to the Client Secret provided by Bullhorn.
  • OAuthRefreshToken: Set this to the refresh token returned by GetOAuthAccessToken.

On subsequent data connections, set the following:

  • InitiateOAuth
  • OAuthSettingsLocation

Manual Refresh

You can use the RefreshOAuthAccessToken stored procedure to manually refresh the OAuthAccessToken. Call the stored procedure after the ExpiresIn parameter value returned by GetOAuthAccessToken has elapsed. You need the following connection properties to be set:

  • OAuthClientId: Set this to the Client Id provided by Bullhorn.
  • OAuthClientSecret: Set this to the Client Secret provided by Bullhorn.

You can then call RefreshOAuthAccessToken with the following parameter set:

Copyright (c) 2020 CData Software, Inc. - All rights reserved.
Build 20.0.7654