Configuring API Authentication

A user connecting to the InterAction API must be a valid InterAction user. This is true no matter what type of application (InterAction for Microsoft® Outlook® or custom application) the user is running.

To accomplish this, the REST API authenticates users whenever they attempt to connect. You can configure the REST API to do this authentication in a variety of ways depending on your organization’s environment and security needs.

The overall goal of the authentication settings for the REST API is to ensure that only valid users can access the InterAction data and that those users can only see and change data for which they have InterAction access rights. Furthermore, all communications must be secure, including those between user workstations and the REST API and between servers on your network.

Note that in addition to configuring your options within InterAction Administrator, you may need to also configure Internet Information Services (IIS) with specific settings to work correctly with the REST API. Furthermore, Web applications may require additional settings depending on the options you choose.

• About API Authentication Modes
• InterAction Authentication
• Integrated Windows Authentication
• Using a Hash-based Message Authentication Code for Encryption and Security (HMAC)
• Select the Authentication Mode
• Configure the HMAC Keys
• Review and Update IIS Settings for the REST API Virtual Directory
• Review and Update IIS Settings for Web Applications that Call the API
• Using Both Windows Integrated and InterAction Authentication and Connecting from Untrusted Domains
• Configuring Secure Communications (HTTP/HTTPS)

About API Authentication Modes

The authentication mode determines how the API identifies the user attempting to connect to InterAction. There are two main types of API authentication available:

InterAction Authentication. In this case, the application needs to collect the user’s InterAction account name and password. See InterAction Authentication.

Windows Integrated Authentication. For this type, the API attempts to match the user’s Windows account name to an InterAction account name. This lets the user connect to InterAction without entering an account and password.

See “Integrated Windows Authentication.

You select the authentication mode in the API Configuration Authentication dialog box.

Choosing an Authentication Mode

[A] Selecting the authentication mode.

The mode you select may require specific IIS settings to work correctly. See the topic about the mode for details.

For any authentication mode, you can use either the HTTP or HTTPS protocol for communications. The API uses the settings you define in IIS. See Configuring Secure Communications (HTTP/HTTPS) for more details.

InterAction Authentication

InterAction Authentication is the simplest authentication mode to configure. If you select this option, users must provide their InterAction account names and passwords every time they connect to the REST API.

For example, a custom application that uses the InterAction API would need to collect the user’s InterAction account name and password and pass that information along.

The InterAction Authentication mode secures the user’s InterAction password when sending it to the REST API using the following:

• The password is encrypted using a public/private key pair.
• A Hash-based Message Authentication Code (HMAC) is used to sign the message sent to the REST API to ensure that it is not tampered with during transmission across servers and the network.

Therefore, you must configure two keys when selecting this authentication mode:

• The password encryption public/private key pair
• The HMAC key

For details, see Using a Hash-based Message Authentication Code for Encryption and Security (HMAC) and Configure the HMAC Keys.

InterAction Authentication is the out-of-the-box mode selected when you install the REST API. If requiring users to enter their InterAction account names and passwords is acceptable in your organization, you just need to review the default settings and configure the HMAC keys after installing the REST API.

Integrated Windows Authentication

Integrated Windows Authentication lets your users bypass the login dialog box. In this case, the REST API uses the user’s Windows credentials to authenticate the user. This is often more convenient for most organizations.

To use this method, your users’ Windows account names need to match their InterAction account names. This authentication mode may also require more configuration, depending on your environment.

Web Applications and Windows Authentication

For a Web application, you need some additional configuration when using Windows Authentication:

• Provide a Windows service account to trust. This is the Windows account that the Web application runs as.

  You configure this for the API and also update the IIS settings for the Web application. See Review and Update IIS Settings for Web Applications that call the API for more about settings for Web Applications.

• Configure the Hash-based Message Authentication Code (HMAC) for passing user credentials. This ensures that the information is passed securely and cannot be tampered with during transmission across servers and the network.

  For details, see Using a Hash-based Message Authentication Code for Encryption and Security (HMAC) and Configure the HMAC Keys.

Windows Applications and Windows Authentication

Windows applications that use the API don’t normally need the Windows service account to trust. They also do not need the HMAC settings.

Using a Hash-based Message Authentication Code for Encryption and Security (HMAC)

A Hash-based Message Authentication Code (HMAC) provides a means to ensure both the security and data integrity of a message sent across a network. This method of encrypting a message relies on a secret key that is known both by the sender and receiver of the message.

In the context of InterAction and the REST API, the sender of the message is the application that calls the API, such as another custom application that uses the API. The receiver of the message is the REST API installed on your server.

Using HMAC for authentication ensures the InterAction login information sent across the network remains secure. The sender computes a hash value for the login information and sends both the login information and the HMAC as a single message. The REST API recomputes the hash value on the received message and checks that the computed hash value matches the transmitted hash value. If they do not match, this indicates that something has changed the message during transmission.

In this case, it is actually the .NET API that creates the hash value and sends it to the REST API.

When Do I Need to Configure the HMAC Keys?

You need to configure the HMAC keys in the following scenarios:

• When using InterAction Authentication. This ensures the security of the InterAction account information. The user’s password is always encrypted before being sent to the REST API for authentication.

  See InterAction Authentication for more about this authentication mode.

• When using Integrated Windows Authentication and providing a Windows service account to trust. This is normally done for Web applications (such as SharePoint) that are installed on a different server than the REST API.

  See Integrated Windows Authentication for more about this authentication mode.

• When using the Task Notification feature. In this case, you must:

  • Use Integrated Windows Authentication.
  • Set the Windows service account to trust.
  • Configure the HMAC keys.

  This ensures the security of the task information.

HMAC relies on HMAC keys to encrypt information and ensure that the message the REST API receives from the application has not been changed during transmission. When using HMAC with your authentication mode, you need to configure these keys; see Configure the HMAC Keys.

Select the Authentication Mode

You set the authentication mode in InterAction Administrator.

1. From the main entity list in InterAction Administrator, double-click InterAction API Configuration.
2. Choose Authentication.
3. Under API Authentication Mode, select the mode you want to use.
   • For more about possible modes, see InterAction Authentication and Integrated Windows Authentication.
   • Note that you can select both InterAction Authentication and Integrated Windows Authentication.

4. If you selected Integrated Windows Authentication and enabled the Windows service account to trust, enter the account or accounts in the text box. This is normally the account your Web application runs under (in IIS, this is the account configured for the application pool).

   See Web Application Identity and Windows Authentication for more details.

5. If the mode you selected requires HMAC, set up your HMAC keys as described in Configure the HMAC Keys.

   If HMAC is required for your authentication mode, the HMAC Settings button is enabled. If HMAC is not required, the button is disabled.

6. Choose OK to close the dialog box and save your changes.

7. Check your IIS configuration to ensure that it is set correctly for this authentication method.

   See Review and Update IIS Settings for the REST API Virtual Directory.

Configure the HMAC Keys

HMAC relies on keys that can be used to encrypt information and to ensure that the message the REST API receives from the application has not been changed during transmission. Depending on the authentication settings you choose, you may need to generate these keys.

You use the HMAC Settings dialog box to generate the keys. This stores them in the InterAction database. There are two separate items you may need to generate:

• The password encryption key pair
• The HMAC key

The Password Encryption Key Pair

The password encryption key pair consists of two keys. One is a public key that applications calling the REST API use to encrypt the user’s InterAction password before sending it to the server. The other is a private key stored in the InterAction database. The REST API uses this to decrypt the InterAction password.

Note that the password encryption key pair is only required when you are using InterAction Authentication. The Integrated Windows Authentication option does not require the key pair since it does not need to send the user’s InterAction password to the REST API.

It is possible to select both InterAction Authentication and Integrated Windows Authentication. In this case, you do need the password encryption key pair since you are using InterAction Authentication.

To create the password encryption key pair:

1. From the main entity list in InterAction Administrator, double-click InterAction API Configuration.
2. Choose Authentication, then choose HMAC Settings.
3. Under Password Encryption Key Pair, choose Create New Keys.
4. Choose OK. Note that the new key pair is not saved until you choose OK.

You can view the public key by choosing the View Public Key button. Note that you cannot view the private key; this is only used internally by the REST API for decrypting the password.

Creating the Password Encryption Key Pair

[A] Choose this to create the key pair.

[B] Choose this to view the public key and copy it to the clipboard if necessary.

The HMAC Key

The HMAC Key is used to sign the authentication information when sending it to the REST API. This is required when using either InterAction Authentication or Integrated Windows Authentication (when using a Windows service account to trust).

When using this type of authentication, the application uses the HMAC key to verify the information sent to the REST API.

To create the HMAC key:

1. From the main entity list in InterAction Administrator, double-click InterAction API Configuration.
2. Choose Authentication, then choose HMAC Settings.
3. Under HMAC Key, choose Create New Key.
4. Choose OK. Note that the new key is not saved until you choose OK.

Creating the HMAC Key

[A] Choose this to create the key.

Review and Update IIS Settings for the REST API Virtual Directory

When you install the REST API, the installation creates a virtual directory in IIS called InterActionAPI. You should review the settings for this directory to make sure they are correct.

Both types of authentication (InterAction Authentication and Integrated Windows Authentication) require the following settings for the InterActionAPI virtual directory:

• Anonymous Access must be selected.
• Integrated Windows Authentication must be selected.

To review and update the IIS settings:

1. On the server where the REST API has been installed, start IIS (usually Start > Administrative Tools > Internet Information Services (IIS) Manager).
2. In the tree view, expand the item for your server, then Sites, then Default Web Site.
3. Under Default Web Site, select InterActionAPI.
4. Double-click Authentication.
5. Make sure the correct options are selected.
   • Anonymous Access must be enabled.
   • Windows Authentication must be enabled.

After making any IIS changes or changing the REST API authentication settings, you should always reset IIS. The specific command to do so varies depending on your version of IIS; see the Microsoft IIS documentation for details.

Review and Update IIS Settings for Web Applications that call the API

If you are deploying a Web application that uses the InterAction API, you need to configure that application to work with the selected authentication method. This is in addition to configuring IIS settings for the REST API itself.

IIS Settings for the Web Application

The specific settings you need for your Web application depend on the authentication method you are using. The following table summarizes these settings for the available authentication methods. Again, these are settings for the Web application that uses the API, not settings for the REST API itself.

IIS Settings for Web Applications that call the REST API

API Authentication Method	IIS Settings for the Web Application
InterAction Authentication	Virtual Directory Settings: Anonymous Access can be selected, but is not required. Windows Authentication can be selected, but is not required.
Integrated Windows Authentication with no Windows service account to trust	Virtual Directory Settings: Anonymous Access must be turned off. Windows Authentication must be selected. Other Settings: If your Web application is installed on a different server than the API, you need to configure it to use Kerberos delegation.
Integrated Windows Authentication with a Windows service account to trust	Virtual Directory Settings: Anonymous Access must be turned off. Windows Authentication must be selected. Application Pool Settings The identity under which the Web application runs should be entered as the Windows service account to trust when selecting the REST API authentication method (Web Application Identity and Windows Authentication).
InterAction Authentication AND Integrated Windows Authentication with no Windows service account to trust	Virtual Directory Settings: Anonymous Access must be turned off. Windows Authentication must be selected. Other Settings: If your Web application is installed on a different server than the API, you need to configure it to use Kerberos delegation.
InterAction Authentication AND Integrated Windows Authentication with a Windows service account to trust	Virtual Directory Settings: Anonymous Access must be turned off. Windows Authentication must be selected. Application Pool Settings: The identity under which the Web application runs should be entered as the Windows service account to trust when selecting the REST API authentication method (see Web Application Identity and Windows Authentication).

Web Application Identity and Windows Authentication

Web applications run under a specified identity. This is defined in IIS in the Advanced Settings for the application pool.

IIS Application Pool Identity Tab

When configuring the REST API to use Windows Authentication, you need to specify the account used for this identity as the Windows service account to trust. You can provide multiple accounts separated by semi-colons (;).

Ideally, you should run your Web application under a domain service account. However, if that is not possible you can use the Network Service account, which is the default in SharePoint environments. In this case, the Windows service account to trust should be:

• NT Authority\Network Service (if the REST API and the Web application are on the same server)
• <Domain>\<name of computer>$ (if the REST API and the Web application are on different machines.

Setting the Windows Service Account to Trust

[A] Enter the account or accounts under which the Web applications that communicate with the REST API run.

To verify the account under which your Web application runs, do the following:

1. On the server where the Web application has been installed, start IIS (usually Start > Administrative Tools > Internet Information Services (IIS) Manager).
2. In the tree view, expand the item for your server, then select Application Pools. The application pools are shown in a table.
3. For the application pool for your application, note the value in the Identity column.
4. If you need to change the account, right-click the application pool and choose Advanced Settings. Then under Process Model edit the Identity row.

To specify the account under which the Web application runs as the Windows service account to trust, do the following:

1. From the main entity list in InterAction Administrator, double-click InterAction API Configuration.
2. Choose Authentication.
3. Under API Authentication Mode, select Integrated Windows Authentication with HMAC Enabled.

4. Enter the account your Web application runs under in the Windows service account to trust field.

   See Web Application Identity and Windows Authentication for more details.

5. Choose OK to save your changes.

Configuring the Virtual Directory Settings for the Web Application

To review and update the IIS settings for your Web application:

1. On the server where the Web application has been installed, start IIS (usually Start > Administrative Tools > Internet Information Services (IIS) Manager).
2. In the tree view, expand the item for your server, then Sites, then Default Web Site.
3. Under Default Web Site, select the virtual directory for your application.
4. Double-click Authentication.

5. Review and change the authentication options as needed.

   See the table "IIS Settings for Web Applications that call the REST API" in Review and Update IIS Settings for Web Applications that call the API for the specific settings you need.

After making any IIS changes or changing the REST API authentication settings, you should always reset IIS. The specific command to do so varies depending on your version of IIS; see the Microsoft IIS documentation for details.

Using Both Windows Integrated and InterAction Authentication and Connecting from Untrusted Domains

If you need to use both Windows Integrated Authentication and InterAction Authentication and have clients that connect from untrusted domains, you need to do some additional configuration steps. This includes both configuring within IIS and updating the web.config file for the REST API.

You need to create a second virtual directory (IIS 6.x) or application (IIS 7.x) for the API and configure it in IIS with Windows Authentication disabled. This new virtual directory or application needs to have the following settings:

1. In IIS, expand the node for your server > Sites item in the Connections pane.
2. Right-click the same Site that contains the original InterActionAPI application and choose Add Application.
3. For the Alias, enter a name. You will need to know this name later. Use a name that reflects the purpose of this new application, such as InterActionAPIAnon.
4. If necessary, change the Application Pool to the same pool used for the original InterActionAPI application.
5. For the Physical Path, use the REST API installation directory (normally C:\Inetpub\wwwroot\InterActionAPI).
6. Choose OK.
7. Select the newly created application.
8. Double click the Authentication item and verify that Anonymous Authentication is Enabled and Windows Authentication is Disabled.
9. Update the REST API web.config file. See “Update the REST API Web.config File,” later

Update the REST API Web.config File

Update the web.config file for the API with a new appSetting to identify this new directory:

• The web.config file is located in the installation location for the REST API. In a normal environment, this would be C:\Inetpub\wwwroot\InterActionAPI.
• You need to add the setting AnonymousVirtualDirectory with the name of the new virtual directory you created previously.

• For example, if your new virtual directory was called InterActionAPIAnon, you would add this line within the <appSettings> section:

  <add key="AnonymousVirtualDirectory" value="InterActionAPIAnon"/>

Use the Correct URL for API Applications

After setting up the second virtual directory, API applications connecting from untrusted domains need to use a URL that specifies the new virtual directory rather than the normal InterActionAPI virtual directory.

For example, assume the following:

• Your REST API Server is called "IAAPIServer".
• The alternative virtual directory is called InterActionAPIAnon.

In this case, you would use these URLs for your API applications:

• For applications connecting from trusted domains:

  http://IAAPIServer/interactionapi/

• For applications connecting from untrusted domains using InterAction Authentication:

  http://IAAPIServer/InterActionAPIAnon/

Configuring Secure Communications (HTTP/HTTPS)

You can use SSL with the REST API if necessary. To do so, you need to configure it within IIS settings. The REST API uses your IIS settings for secure communications.

Normally you configure SSL at the Default Web Site level rather than just for the API.

The steps to configure SSL vary depending on your version of IIS.

For details about SSL and configuring IIS, see Microsoft’s documentation.

Configuring SSL for IIS 7.x

You need to obtain a valid certificate to configure SSL.

1. If not already done, install your certificate.
   • In IIS, select the node for your server from the Connections pane and then double-click Server Certificates in the right pane.

   • Choose Create Certificate Request and complete the wizard.

     For testing purposes, you can use the Create Self-Signed Certificate option. This is much simpler and useful for testing, but not for your production environment.

2. Create an SSL binding for your server.
   • Select the node for your server > Sites > Default Web Site from the Connections pane, then choose Bindings from the Actions pane.
   • Choose Add to add a new binding.
   • Select https as the Type and select the SSL certificate you previously installed, then choose OK.
3. Optionally configure your server to require SSL. Note that this is not required for InterAction.
   • Select the node for your server > Sites > Default Web Site > InterActionAPI from the Connections pane.
   • Double-click SSL Settings in the right pane.
   • Select or clear the Require SSL check box.
4. After completing these steps, reset IIS.

After configuring IIS to use SSL, the client machines that connect to the API using HTTPS need to be configured to trust the signer of the server certificate.

For more about configuring IIS with SSL security, see Microsoft’s documentation.

Managing Server Certificates in IIS7

Setting IIS to Require SSL in IIS Version 7.x