API key security provider in Jitterbit App Builder

The API Key security provider allows administrators to secure App Builder REST APIs using an API key code generated by App Builder. The consumer passes the API key to App Builder when making REST API requests. Because each API key is associated with an individual user, this provides both authentication and authorization.

Definition and use cases

App Builder's API keys consist of a 128-bit, cryptographically random number. The keys are base64url encoded. Below is an example of an API key:

DLOo9sPS5slJEMHpXBFt3g

API keys have the following advantages over standard username/password authentication:

• They have greater entropy than username-password combinations.
• They can survive a password reset.
• They can be easily revoked.
• They can be rotated.
• They are faster. Passwords must be hashed, which is deliberately slow.

The disadvantages, or weaknesses, of API keys include managing their distribution and the risk of leaks. Some of the use cases where API keys can be the most adequate authentication method include:

• Service-level accounts
• Application-to-application communication
• Server-to-server communication
• Read-only access
• Non-sensitive information

Add an API key security provider

To add a new API key security provider, follow these steps:

1. Go to IDE > Security Providers. The Security page opens.

2. In the User Authentication table, click + User Authentication. The Provider dialog appears:

   

3. Under the Settings section, fill in these fields:

   1. Name: Enter a name to identify your API key security provider.

   2. Type: In the dropdown menu, select API Key as the type of security provider you're creating. Doing this will alter the rest of the fields that are shown in the dialog.

   3. Priority: Enter a number to set the order in which security providers appear on the login form.

   4. Enabled: Click this checkbox to activate the new security provider.

   5. Identifier: This field is automatically generated by App Builder.

4. Under the Keys section, fill in these fields:

   1. Default Expiry: Enter how many minutes for the default lifetime of new keys. (Altering this field does not affect existing keys.)

   2. Max Expiry: Enter how many minutes for the maximum lifetime of new keys. (Altering this field does not affect existing keys.)

   3. Length: Enter the length (in bytes) of new keys. (Altering this field does not affect existing keys.)

5. Click Save.

After you save a new API key security provider, you will be taken back to the Security page, where the User Authentication table will show the new one you've just created. By clicking the icon at the end of its row, you can continue configuring it.

Configure an API key security provider

To configure your API key security provider, go to IDE > Security Providers. Locate it in the User Authentication table and click the icon at the end of its row. The Provider page will be shown, where you can add additional configurations. The Provider panel on the left shows the same settings and keys that are shown when you created the security provider. The Properties panel on the right allows you to set up some extra parameters, described below.

To add a new property, click the + Property button. This will bring up the Properties dialog, which contains the Parameter and Value fields. The following parameters are available:

• AllowApiKeyInQueryString: Use this parameter to allow the API key to be passed in the query string instead of in the HTTP header (see the Pass an API key section). The default value is False.

• AllowInsecureHttp: Use this parameter to allow the API key to be passed via an insecure HTTP request instead of a secure HTTPS request (see the Pass an API key section). The default value is False.

• HttpHeaderName: Use this parameter to change the name of the HTTP header that will pass the API key from the default X-API-Key.

• QueryStringParameterName: When you have also used the AllowApiKeyInQueryString option to pass the API key via one of the query string parameters, you can use this option to change the parameter's name from the default name apiKey (see the Pass an API key section).

Click Save and close the Properties dialog. The new parameter you've added will be listed in the Properties table.

Generate an API key

When you have a configured API key security provider, you can generate API keys associated with users by following these steps:

1. Go to IDE > Runtime > User Management.

2. The Users panel lists all users. Locate the user you want to generate an API key for and click the icon at the end of its row.

3. In the User dialog, click More > Keys. The Keys dialog opens.

4. Click Create. The Generate Key dialog will open.

5. In the Provider menu, select the API key security provider that you created.

6. (Optional) Provide a Description for this key and enter a customized expiration time in the Expires In field.

7. Click Save. The API key will be created.

Pass an API key

In most scenarios, Jitterbit recommends that the client pass the API key via a custom header in a secure HTTPS connection to limit the risk of exposure. The following example illustrates this:

GET /Vinyl/rest/v1/sales/customers HTTP/1.1
Host: example.com:443
Accept: application/json
X-API-Key: ABCd0eFG1hiJKLMnOPQr2s

This is the default behavior, which App Builder selects automatically. You can also use the HttpHeaderName parameter when configuring your API key to change the name of the HTTP header that will pass the API key from the default X-API-Key.

The following examples are some exceptions to this recommendation:

1. In some scenarios, HTTPS connections may be prematurely terminated. To work around this issue, you can force App Builder to accept API keys sent via HTTP connections by setting the AllowInsecureHttp parameter to True during API key configuration.

2. In cases where you don't have access to the HTTP request headers, it is also possible to send the API key via the query string parameters. To enable this option, set the AllowApiKeyInQueryString to True in the API key configurations. The example below illustrates how the API key is passed in this scenario:

   GET /Vinyl/rest/v1/sales/customers?apiKey=ABCd0eFG1hiJKLMnOPQr2s HTTP/1.1
   HOST: example.com:443
   Accept: application/json
   

   Note

   In the example above the key was sent under the name apiKey. You can change this by going to the API key configuration and adding the QueryStringParameterName parameter to choose a different name.