Best Security Practices for Your Vonage API Account

Question

How can I best secure my Vonage API account?

Applies To

• Account Dashboard
• Password
• API Secret
• Security

Answer

Vonage provides several ways to protect your account. However, utilizing these security features alone may not be enough to avoid your account getting compromised. In this article we describe some of the key security features and additionally, some basic security best practices customers should follow to protect their Vonage API accounts.

Authentication

Passwords and Secrets

The first line of defense when protecting your account is using a strong password that others cannot guess. Vonage recommends configuring a password that is at least 12 characters long, contains both upper- and lower-case letters, numbers and at least 1 special character for both primary and any secondary accounts. Visit the Change Password page to configure a strong password.

When interacting with Vonage API services it is not only the Dashboard that requires authentication but each API request submitted has to be authenticated as well. There are several ways to perform authentication and in each case you have to make sure it is done in a secure way. For example, you can use request signing as a form of authentication or use the traditional API secret-based authentication. As both the signature secret and API secret (from now on referred to as secrets) basically functioning like passwords, the same rules apply: make sure others cannot guess it. Vonage recommends using at least 20 characters long secrets that include both upper- and lower-case letters, at least 1 number and where allowed special characters. You can configure your secrets via the Settings page of the Dashboard.

Two-Factor Authentication

Besides using a strong password it is also recommended to enable two-factor authentication (2FA) for your account, which should include both primary and any secondary users. When 2FA is enabled, every time you log in from a new location Vonage will send you an SMS with a PIN code. You will be asked to enter this PIN on the dashboard in order to gain access your account. Having 2FA enabled drastically reduces the likelihood of an account compromise simply because the attacker would have to know your password and have access to your mobile phone at the same time, which is, less likely to happen. Each user in your team can turn on 2FA from their Edit profile page in the Dashboard (don't forget to click Save when making the change).

Protecting Your Credentials

Encrypted Communication

While having strong passwords is mandatory in order to successfully protect your account, they are pretty much useless if the communication between you, your systems, and Vonage is not encrypted. A well-positioned attacker may be able to intercept your communication and obtain your credentials. Vonage API services are accessible via HTTPS to ensure encrypted communication. Additionally, the certificates presented by our systems were issued by a trusted, 3rd party certificate provider. If your browser or library is raising any alarms related to our certificates do not attempt to authenticate without performing a thorough investigation in advance to identify the reason of the issue.

Do Not Expose Your Secrets

As sharing or exposing your secrets can lead to account compromise or fraud it is important not to share them with anyone, not even with Vonage. Vonage will never ask for any of your secrets. As of this, if anyone pretending to be representing Vonage and asking for any of your secrets you can be sure that it is a phishing attack. In fact, we do not need to know any of your secrets, not even when you are contacting support. Before submitting any support request please make sure you are not posting any secrets in your request.

Attackers are continuously on the lookout for exposed authentication credentials and secrets. Committing your secrets (API secret, signature secret, private keys or dashboard password) to public code repositories (such as GitHub) will definitely result in account compromise or fraud. Before committing your code to any public repositories make sure secrets are not present in any of the files.

Similarly to the above, do not include your secrets in mobile applications. It is relatively easy to obtain such hardcoded secrets (even if you obfuscate it) by reverse engineering mobile applications. Including your API secret or signature secret for example will definitely result in account compromise or fraud. Additionally, worth noting that none of the Vonage API use cases support this scenario. If you need to empower your mobile applications to perform certain actions on behalf of your account you may want to consider using only Vonage API services that support JWT-based authentication. To see which services support JWT authentication refer to the documentation.

Design Your Applications Securely

Make sure your applications and services handle credentials (API secret, signature secret, or private key) securely. There are many ways to mishandle your credentials such as: hardcoding them, storing them in world-readable files, sharing them with untrusted or insecure internal or external services, accidentally exposing them via logs or error messages, and so on. It is highly recommended to design your environment, applications, and services in a way that provides adequate protection of these credentials. You may want to have a look at the OWASP Top 10 Project to learn more about the typical vulnerabilities and how to address them.

In addition it is also a good practice to have your application or service reviewed by a qualified, reputable 3rd party security service provider in order to identify security issues that could later negatively impact your business before going to production and after, when significant changes are made to the application or service.

Data Protection

Secondary Users

The Dashboard allows you to create secondary users. When creating a new secondary user make sure you double check the email address of the user. If you mistype an email address you may end up exposing your account to strangers.

Webhooks

Webhooks can potentially expose sensitive information if not configured properly. For example:

• Webhook URL for Inbound Message: When using inbound message webhooks Vonage sends the message to the URL provided. As the message may contains sensitive information ensuring its confidentiality is very important. A well-positioned attacker could intercept non-encrypted channels and obtain such sensitive information.
• Webhook URL for Delivery Receipt: Delivery receipts contain both the sender's mobile number and the name of the recipient. A well-positioned attacker being able to intercept this not only can tamper with the data but could use the information to target your customers via social engineering.

Make sure you always configure your webhooks to use encrypted channels by providing HTTPS URLs. This can be configured via the Settings page of the Dashboard.

In addition to the above, make sure you configure your webhooks so that Vonage uses POST requests this way proxies if configured will less likely to log potentially sensitive information.

Request Signing

In the traditional API key- and API secret-based authentication scenario, if you are using a proxy server, be it internal to your organization or provided by a 3rd party, your API secret may get logged as those are to be provided via the query parameters. If any of these proxies get compromised an attacker may be able to obtain your credentials and use them to perform fraudulent actions. The same applies to a scenario where for example an attacker managed to obtain the clear-text requests somehow.

Signed requests can be useful for multiple reasons. Besides providing additional integrity protection and protection against late replay attacks, using signed request can also help to protect your credentials as when using request signing the API secret is no longer exposed in the requests. The signature secret used to generate the signature is also not exposed. This means even if an attacker obtains the complete request data they will not be able to use any part of that. The worst that could happen when using signed requests on a compromised communication channel is that an attacker may be able to replay the requests for a limited period of time.

You can configure your signature secret and signature algorithm via the Settings page of the Dashboard. Vonage recommends using SHA-256 HMAC or SHA-512 HMAC as the signature algorithm.