API keys in Vantage

For third-party applications that integrate with Vantage, you must use API keys to authenticate them.

General

You can integrate Vantage with your third-party solutions. These applications connect to Vantage through the Nozomi Networks application programming interface (API) to update data in Vantage, or to retrieve data from it. For example, you might use Splunk for security information and event management (SIEM). In this case, Splunk would connect to Vantage through the Nozomi Networks API. Through various API endpoints, your third-party applications can perform many actions, such as creating and deleting user groups or modifying alert rules.

Third-party applications

In order to authenticate, third-party applications must pass credentials in the form of an API key and token. To do this, you must:
  1. Generate the API key and token in Vantage
  2. Use your third-party application to call Vantage and pass the key and token for authentication
Nozomi Networks recommends that you:
  • Assign a different key to each application
  • Create a single user that all of your applications use to access Vantage
When you assign a different key to each application, audit log entries correctly attribute each action to the service that performed it.

When you use a single user to access Vantage, it keeps maintenance simple. However, for your specific use case, and security requirements, it is possible that it will be better to associate each application to a different user.

For more information on choosing the right approach for your implementation, see Considerations when you connect multiple applications to Vantage.

Application IP address ranges

Your applications might connect from a completely different internet protocol (IP) address range than your other Vantage users. For example, your SIEM might operate in the cloud. If you limit the range of IP addresses from which connections to Vantage must originate, you can override the IP address range that is defined in the General settings with a range that is defined for a specific API key.

Users

For API keys and users:
  • Each API key is associated with a Vantage user. Keys are generated in the user's profile.
  • The user associated with the API key must have sufficient permissions in Vantage. This user should be the security assertion markup language (SAML) account of the person responsible for the integration.
  • Your third-party application must pass the API key name and token in order to authenticate with Vantage.
  • An API key remains valid until it is revoked, or until the user it belongs to is deleted
    Note:
    When an API key has been generated in the context of SAML-managed users, a SAML user's keys are not automatically revoked when the SAML-created user object is deleted. This is because your identity provider (IdP) is not aware of API keys. Therefore, you must manually revoke keys that have been generated for SAML users.
When you define a user to associate with your API key, you should carefully define the access that they are granted. You should consider limiting a:
  • Scope
  • Permissions
  • Allowed IP address ranges
These precautions limit the actions your third-party applications can take in Vantage. For more details, see:

These factors take on added importance in cases where multiple applications use them. For more details, see Considerations when you connect multiple applications to Vantage.

User scope and permissions

The user associated with the API key needs explicit access to data and tasks in Vantage. This means that you should assign the user to a group and role which has appropriate permissions for the application's responsibilities. For example, if your application needs access to read all data, assign its group the Superobserver role. Or, assign the related group the role of Assets Operator if the user needs to:
  • Create assets
  • Read assets
  • Update assets
  • Delete assets

You should also limit access to the organizational scope where this application is permitted to act. If your application only needs data about one specific organization, select that organization when creating the user's group role assignments.