The information in this article is the intellectual property of xMatters and is intended only for use with xMatters products by xMatters customers and their employees. Further, this intellectual property is proprietary and must not be reused or resold.

We've made some exciting new enhancements to the Integration Builder that will improve integration security, and give you finer control over how to authenticate and track interactions between your applications and xMatters.

These changes also mean that you can no longer create "unauthenticated" inbound integrations and any older inbound integrations that don't have authentication will need to be updated to use the new options.

Don't worry! Your integrations will continue to work as implemented, but at some point soon you will want to take advantage of the increased security and additional options that the new functions provide.

Note: If you make any changes to an existing inbound integration, you will be prompted to select one of the new authentication methods before you can access the transformation scripts.

• Overview
• Inbound integration authentication
• Accessing the new feature
• Outbound integration authentication
• The xMatters endpoint
• Best practices
• Other helpful tips

Overview

We've been implementing these changes in stages over the past few releases, with the latest features added during the Asteroids release. Here's what's changed:

• You can now set authentication for inbound integrations separately for each integration, and there are four different authentication options to choose from:
  • Basic authentication requires a user's user name and password to authenticate requests.
  • URL and API Key authentication require you to select an authenticating user to trigger the integration.
  • OAuth authentication requires the OAuth credentials of an xMatters user to trigger the integration.
• All outbound integration script requests are now authorized using the account and permissions of the user who initiated the integration.

Inbound integration authentication

Previously, you could enable or disable authentication for all of the inbound integrations within a communication plan on the Integration Builder tab. Enabling the option would generate a randomized user name and password (essentially an API key and secret) that you could submit as credentials for any request, using basic HTTP authentication.

You must now choose from one of the following authentication options when configuring each inbound integration:

• URL Authentication: When you select this method, xMatters generates an API key unique to an authenticating user (defaults to the logged-in user), and appends it to the integration URL. Any requests submitted via this URL will have the same permissions as the authenticating user in xMatters (though the URL does NOT grant permission to log into the web user interface).
• Basic Authentication: This requires the calling system to store the credentials of an xMatters user. Any user who has permission to access this integration can authenticate the request using HTTP Basic Authentication and their username and password. If the user updates their password in xMatters, you must also update the credentials in the calling system. These credentials can also be used to log in to the xMatters user interface (if the user has permission to access it, of course), and will be subject to password expiry if enabled for your organization.
• API Key: This method works similar to the previous inbound integration authentication option in that it generates a unique API key and randomized secret password, but the API key and secret are now specific to this inbound integration and a selected authenticating user. The API key and secret cannot be used to log in to the xMatters web user interface, and cannot be used to trigger any other inbound integration, even those on the same plan.
• OAuth: This method uses xMatters access tokens and client IDs based on the xMatters OAuth authentication feature to authorize incoming requests. For more information about using OAuth with xMatters, see OAuth authentication.

For more information, and instructions on how to configure each of these options, refer to the xMatters On-Demand online help.

Accessing the new feature

As of the 5.5.217 release of xMatters On-Demand, if you go into the Integration Builder and expand the list of inbound integrations, you will notice a new warning message beside your inbound integrations:

If you then open the inbound integration to edit it, you'll see the new authentication options:

You will need to select a new method, and then update the endpoints in your calling system and scripts to make sure they are targeting the correct integration and using the right credentials. (Note: If you do not edit the integration, it will continue to function; however, you must select one of the new authentication methods if you want to modify the scripts or update any other settings.)

Once you select a new method and save your integration, the previously unauthenticated version of the integration will expire after 72 hours. During this period, the Integration Builder will accept both authenticated and unauthenticated requests from this integration.

The expiration for each of your previously unauthenticated integrations is also displayed in the list of integrations. Once you've updated your calling system scripts you can ignore the these warnings - they'll disappear once the 72 hour period has passed.

Updating your inbound integrations

Let's say you've gone into your Integration Builder and noticed the orange warning messages. So now what?

Well, you will first need to decide which authentication method works best for you and your integrations. You may decide to use different methods for different applications or different communication plans, or even for different inbound integrations within the same plan.

For this exercise, however, we're going to recommend that you use the API Key authentication for several reasons:

• URL Authentication should really only be used if your calling system does not have the ability to include authentication headers in the request.
• You've been following our integration guides when implementing your integrations, of course, and have a separate integration user (with the REST Web Service User role) assigned to the xMatters endpoint.
• You don't want to store the xMatters credentials for your integration user in a third-party system.

So here's how to update your system and your inbound integrations to use the API Key authentication method.

To maintain availability of your systems while transitioning your integration to use authentication, the Integration Builder will accept both unauthenticated and authenticated requests for a 72 hour period, starting from when save your integration with a new authentication method.

Step One: Confirm access permissions

First, make sure your communication plans and forms are set up to allow your integration user to initiate integrations properly.

1. Navigate to the Developer tab, and find the communication plan for your integration. Click Edit > Access Permissions.

2. In the Communication Plan Access Permissions dialog box, do one of the following:
   • Select the Accessible by All check box.
   • Type "REST" into the search field and then select the REST Web Service User role when it appears in the drop-down list.
   • Start typing the name of your integration user into the search field. When the user appears in the drop-down list, select their name.
3. Click Save Changes, and then click Edit > Forms.
4. For each form in the plan that you want the integration user to be able to initiate, click the status button (which probably says something like "Web Service Only" or "Web UI and Web Service", and select Sender Permissions.

5. In the Form Sender Permissions dialog box, do one of the following:
   • Type "REST" into the search field and then select the REST Web Service User role when it appears in the drop-down list.
   • Start typing the name of your integration user into the search field. When the user appears in the drop-down list, select their name.

Step Two: Generate your API key and secret

As of the Asteroids Quarterly Release, you no longer need to log into xMatters as the integration user to get their API key and secret. You are required to select an authenticating user to trigger the integration on the inbound integration's configuration screen.

NOTE: An authenticating user must be someone that you supervise with a role that contains the "REST Web Service User" function. This function is included in the REST Web Service User role.

1. Navigate to the Developer tab, and into the Integration Builder for your integration's communication plan.
2. Expand the list of inbound integrations, and click the name of the integration service you want to modify.
3. On the inbound integration's details page, scroll down to the Select authentication method section, and select API Key in the drop-down list.
4. Click Save to update your integration.
   • xMatters displays instructions on how to trigger the integration using API key authentication:

5. In the Authenticating User search field, do one of the following:
   
   • Start typing the name of your integration user and select it when it appears (two characters are required).
   • Type two spaces to view a list of all existing options and select your integration user from the list.
6. Next, do one of the following:
   • Copy the API Key and Secret values to a text file for temporary safekeeping.
   • Copy and paste the API Key and Secret values directly into the appropriate fields within your calling system.

Repeat these steps for each inbound integration that you want to configure for your integration user. (You may notice that the API Key is the same for all inbound integrations that you configure for the same integration user - this is because the key is tied to the authenticating user.)

Step Three: Update your integrated systems

You can now update your calling systems (if you haven't already), to use authentication headers within the HTTP request.

Some pointers:

• Use the API key as the username, and the secret as the password.
• If you need to configure your HTTP headers manually, use Base64 encoding for the API key and secret. Check out this article for more information about how to construct these headers.

Outbound integration authentication

Another security enhancement is a change to how "Run a script" outbound integrations authenticate with xMatters:

Events initiated using any method other than an inbound integration will now authenticate outbound integration script requests using the account of the user who initiated the event.

Events initiated via an inbound integration use the same credentials that are used to initiate the integration, as specified by the authentication method configured on the inbound integration.

For example, let's say you inject an event into xMatters via the POST form trigger, and the communication plan you target includes an outbound integration that is configured to initiate a new conference bridge event when a user responds with a specific response choice. When triggered, the outbound integration will attempt to initiate that event using your credentials.

If the event initiator doesn't have the same permission levels as the account you expected to authenticate the requests in your outbound integration scripts, then the request won't be able to execute the required tasks. The script will still run and execute any of the requests for which the initiator DOES have the correct permission levels, but you might encounter an error in your integration's Activity Stream with a statusCode of 403, and a statusMessage of FORBIDDEN. The reason give will be similar to:

UNAUTHORIZED_ACCESS_ERROR: User does not have the permission to access this service/functionality.

Here's what that message looks like in the Activity Stream:

This issue could affect:

• events initiated from within the xMatters mobile app, or by using the web user interface (i.e., the Messaging tab)
• events triggered via the email form initiation feature
• events injected via the REST POST form trigger

Any of these events that target xMatters endpoints within their outbound integration scripts will use the permissions of the initiating user.

As mentioned, events that are initiated using an inbound integration use the credentials specified on the inbound integration, and not the xMatters endpoint as previously configured. Speaking of which...

The xMatters endpoint

The original implementation of the Integration Builder workflow required that you configure an xMatters endpoint that specified a user account to use when the integrations for that form needed to authenticate a request with xMatters. You could then target the xMatters endpoint from your outbound integration scripts with API requests to perform actions in xMatters, such as creating a device, retrieving a list of users, or initiating another event.

The problem with this approach is that it automatically applied the same permissions (and the same initiator ID) to every request made to xMatters from the Integration Builder. The new authentication methods ensure that every request that enters the system has only the permissions assigned to the user making the request. (Once you have configured all of the inbound integrations in your system to use one of the new authentication methods, the "owner" of the xMatters endpoint will no longer have any effect; the setting will be removed in a future release of xMatters.)

Best practices

The best approach is mostly just making sure that you've thought through the implications of your integrations, and considered any potential differences in permission levels.

Here are some specific places you can check to make sure that your integrations won't run into any issues (for more information about how to perform any of these checks, click the link in each step):

1. Review the authentication options detailed in the online help for inbound integrations, and decide which authentication method best suits your requirements.
2. Check the Sender Permissions and Access Permissions you currently have in place on your forms.
   • For inbound integrations, event initiation will fail if the authenticating user does not have both access to the plan AND permission to send messages for a form.
   • You may also need to adjust the sender permissions if you are starting xMatters events using your outbound integrations so that the user who started the original event can initiate the forms referenced in the outbound integrations.
3. Make sure your event initiators have the roles they need to make requests in xMatters. Remember: for a user to make a request via the REST API, they must have the same permissions they would need to perform that action in the web user interface.
4. For any request made by your outbound integration that needs to read or update xMatters data, make sure that your initiators have the correct permissions on other roles that those updates might require. For example, calling the GET people endpoint will require the correct role-on-role permissions for the user who initiated the form to be able to Use or View the relevant users.

Other helpful tips

In general, when building integrations, you should:

• Choose the highest level of authentication for inbound integrations that the calling system supports. Again, URL Authentication is NOT recommended unless the calling system does not have the ability to provide authentication headers in the request.
• Remember that xMatters will treat any script request from the Integration Builder as being made by the same user that initiated the integration, and therefore restricted to that user's permissions.
• Modify your integration scripts to handle the cases where the initiating user might not have the required permissions. This is especially important if, for example, you're retrieving a list of users and the returned results will be different if the initiating user doesn't have permission to view some of the people in your system.

If you do encounter any problems, or for technical assistance with these changes, contact xMatters Support.