API Security

Secure your API with a Layer of Indirection

A popular principle among computer scientists states that every problem can be solved by adding a layer of indirection. When it comes to API and cloud security, this principle can work wonders. A layer of indirection (also referred to as a layer of abstraction) in the cloud with security built into the platform can help mitigate threats including the recently discovered “FREAK” SSL/TLS vulnerability, and can ease concerns for enterprises who migrate workload or services to the cloud.

The FREAK vulnerability, which emerged last week, enables attackers to intercept HTTPS connections between vulnerable clients and servers and force them to use “export-grade” cryptography, which can then be decrypted or altered.

With the emergence of threats like this, the ability to configure security at the edge of your enterprise—quickly—has become critical. With API security, the primary goal is to protect the APIs exposed, from your data centers and cloud services, to your developers and partners. So how do you do this, without compromising your application security but allowing app developers to innovate at warp speed?

Here is where applying the principle of indirection to your APIs by using an API management platform offers protection in a seamless way. An API indirection layer with a strong security facade helps developers consume APIs in a frictionless way. It also enables API teams to govern the APIs with consistent security aligned with their enterprise security architecture. The benefits of a secure API facade on your APIs include the ability to:

  • mitigate any application security weakness by taking advantage of the API management platform's threat protection features, including 2-way TLS, OWASP Top 10 protection, rate limiting, and quota restrictions for private or public apps

  • provide a strong authentication mechanism using OAuth 2.0 for mobile and web apps, even though your API doesn’t support newer and stronger security protocols

  • support fine-grained authorization for your APIs for developers and partners without requiring you to redesign your APIs

  • buy additional time to patch your APIs from zero-day security threats such as Poodle, Ghost, and FREAK attacks; a secure facade facilitates configuration in seconds instead of the days required to code and deploy security controls necessary to protect your vulnerable APIs

So when the next zero-day security vulnerability rears its ugly head, you can simply configure your blacklist to block the vulnerable protocols (such as the Poodle vulnerability in SSL3.0), ban the weak ciphers (like the FREAK vulnerability, which is due to weak export cipher suites), and be assured of your API protection.

The strength of an API security program is not only determined by prevention controls such as OAuth-based authentication, but also your ability to react to new zero-day security threats such as FREAK. We’ll witness more of these attacks; the only way to future proof your security response is to create an architecture that enables you to configure security at the edge of your enterprise in near real-time, without impacting your enterprise’s mission-critical APIs.

Photo: Holly Victoria Norval/Flickr

Tutorial: Using Remote Services and API Key Security

In the past few Apigee-127 tutorials, we’ve explored core features like OAuth 2.0 security, quotas, and caching—key ingredients for building enterprise-quality APIs. Here, we'll explore two new Apigee-127 features: remote services and API key security. We’ll show you how to create a remote service and bind it to an Apigee-127 project. Then, we’ll use that service to handle API key security validation for the API.

What are remote services?

A remote service is available to an Apigee-127 project no matter where the project is deployed. Currently, the only Apigee-127 service available is the RemoteProxy service, which is used with the Apigee OAuth provider. It provides endpoints for creating and verifying OAuth 2.0 tokens, and it's deployed on the Apigee Edge platform.

What is API key security?

An API key enables an API provider to uniquely identify a developer app. Typically, an app developer must register an app with the API provider to obtain the key, which remains confidential between the two parties.

Whenever the app calls the API, it typically passes the key either in a query parameter or header. For example:

If the key is valid, the call proceeds; otherwise, an error is returned.

What version of Apigee-127 do I need?

To use remote services and API keys, you need to install Apigee-127 v0.11.0, or a later version. Verify your version with the command:

$ a127 -- version

Check out the doc wiki for installation instructions and release notes.

Before you begin

The currently active Apigee-127 account must have the "apigee" provider. You can list all accounts, check the current account properties, and create new accounts with the Apigee-127 command-line tool. Just enter $a127 account -h for command options.

Create a new service

There are two ways to create a new service:

  • when you create a new account, you have the option of also creating a service

  • you can use the Apigee-127 command-line tool’s service option to create services directly

Let's look at the command-line tool option:

$ a127 service create
[?] Service Type? RemoteProxy
[?] Service name? RemoteProxyBlog
Creating service RemoteProxyBlog from myaccount...
Remember to bind your service to any projects that require it.


 account: myaccount
 type: RemoteProxy
 uri: 'http://myorg-prod.apigee.net/remoteproxyblog'
 key: f34RUcMxFGwTe6e5KnpZIJfT

You’ll need to remember the service name (remoteproxyblog in this example) for later when you configure your API.

Here's what happens behind the scenes:

  • an API proxy called RemoteProxyBlog is deployed to Apigee Edge

  • a developer, a product, and a developer app are created on Apigee Edge

  • Apigee-127 retrieves the proxy URI and key from the developer app, along with some other information, and stores it in ~/.a127/services; this information enables your Apigee-127 project to communicate with the service

Bind the service to a project

Next, use this a127 command to bind the new service to your project. This binding enables the service to be used wherever the project is deployed:

$ a127 project bind RemoteProxyBlog

Service RemoteProxyBlog bound to Project myblogproject.
If this project is deployed, you will need to redeploy to activate the new configuration.

As the message says, if your project was already deployed (to Apigee Edge, for instance), you need to redeploy it. If you’re running your API project locally, you don’t have to deploy your project.

Configure an API key policy in your Swagger file

Next, we add an API key “policy” to the API by editing the project’s ./api/swagger/swagger.yaml file. No coding is required!

Let’s go step by step. First, the API key policy requires a Swagger security definition. You can add this stanza at the end of the Swagger file, after the response definitions section, like this:

       type: apiKey
       name: apiKey
       in: query

We’re specifying a name for the security policy (apiKeyQuery), the type of policy (apiKey), and how the key will be passed in API requests (a query parameter named apiKey).

Next, configure the parameters for the RemoteProxy service in the x-a127-config section of the project’s Swagger file. This is where you must supply the name of the RemoteProxy service and the required key and uri parameters, like this:

     RemoteProxyBlog.key: &apigeeProxyKey CONFIGURED
     RemoteProxyBlog.uri: &apigeeProxyUri CONFIGURED

Now declare the API key policy in the x-a127-services section of your project’s swagger.yaml file. The policy options are the key and uri references that you configured previously. The name of the policy (specified in the security definition) is apiKeyQuery, and you'll reference that name when you add the policy to an API path.

       provider: volos-oauth-apigee
         key: *apigeeProxyKey
         uri: *apigeeProxyUri

Finally, add the security policy to one or more API paths. Here's a sample path, with the apiKeyQuery policy applied to the GET operation (the last two lines):

       # binds a127 app logic to a route
       x-swagger-router-controller: hello_world
       x-a127-apply: {}
         description: Returns 'Hello' to the caller
         # used as the method name of the controller
         operationId: hello
           - apiKeyQuery: []

That's it! Now, let’s see how to call the API with an API key. You can find a working example of this code here: https://github.com/apigee-127/a127-samples/tree/master/security-apikey-apigee.

Get the API key

Where does the API key come from? It’s a valid client ID (also called a consumer key) associated with a developer app registered on Apigee Edge. On Apigee Edge, you can find developer apps in the UI under Publish > Developer Apps.

The way this typically works in production is this: a developer first registers an app with Apigee Edge. This can be done through a developer portal, or through the Edge management interface. In return, the developer receives the client ID. That value is the API key.

Any valid client ID within the organization specified in your Apigee-127 account will work (for example, prod or test). For testing purposes, you can use the key that was returned when you created the RemoteProxy service, because that key represents a valid client ID.

Call the API

To call the API, just add an apiKey query parameter, passing it a valid API key, like this:

$ curl


Hello, Will

For more information

Check out the a127 doc wiki for more details on API key, basic auth, and OAuth 2.0 security options. You can also find a working sample on GitHub here: https://github.com/apigee-127/a127-samples/security-apikey-apigee.


Lessons from a Customer Security Incident

Building products used by demanding customers is hard. Running operations is hard. Safeguarding customer data and infrastructure is hard. We’ve benefitted from all who have traveled on this journey before us, and we’d like to share our experiences and lessons learned: what works, and what doesn’t.

In this post, we share a summary of a recent security incident and the lessons we learned from handling the attack.

In early December, an unauthorized party accessed credentials for two of our customers for accessing the Apigee Management Service. These credentials were stored in a third-party hosting service, which hosts our developer portal. The intruder accessed the credentials by exploiting a known Drupal vulnerability before the fix patch was applied, and then made a few configuration changes using the compromised credentials. Since these changes were unusual, they caught our attention. Following our standard first-response security procedures, we acted quickly to protect our customers by disabling public access to our Management Service.  

We then performed a thorough investigation to assess the extent of the attack and found it was limited to the two customers and the set of configuration changes made. We restored all the customers’ original configuration from backups and took steps to prevent similar attacks.

A painful lesson learned from this incident: we weren’t following the principle of "least privilege.” The credentials stored in the third-party service had more privilege than they should have. Had we been more diligent about this, the intruder would have had a much harder time accessing the credentials.

The incident raises several important security best practices to keep in mind:

  • Limit your user list to those who actually need to use the product

  • Periodically review your user access list to ensure an up-to-date user list; delete users no longer associated with your organization or the job function

  • Use RBAC (role based access control) to assign users the level of access they need to get their jobs done and no more—we’ve defined several roles to make it easy for you to do this

In our cloud offering, we run tens of billions of API calls per month that interact with our customers’ back-end systems. Our on-premises software handles an equally large number. The lessons we’ve learned and the myriad architectural choices we’ve made enable our customers to: scale their API traffic (both stateless and stateful); create isolation in a multi-tenant environment; provide flexibility to configure or code; support an analytical system that doesn't require tuning as apps and APIs change; and enforce security with access control and threat mitigation.

For more on security best practices, see the following articles and posts:

Apigee is hiring. If you’re an engineer excited about tackling challenging problems, visit our careers page.

Security as an Enabler for the Digital World: The CISO Perspective (webcast & podcast)

A successful API strategy requires a strong partnership between the business, IT, and security functions. Rather than as a hindrance, security increasingly is viewed as a business enabler, with CISOs and CSOs playing a critical role in implementing “guardrails” for safe, secure and compliant API services and security architectures free of unnecessary complexity.

Ultimately, a secure API platform enables developers and DevOps to focus on innovation—by improving the mobile user experience and deploying apps in the cloud, with appropriate security controls built in. In this webcast, Apigee’s Subra Kumaraswamy and Saba Software CSO Randy Barr explore how CISOs and CSOs partner with IT and business leaders for a safe and secure journey to cloud, SaaS, and mobile services.

Subra and Randy also discuss:

  • The role of the security officer in helping IT and business leaders meet objectives
  • How smart and secure API guardrails remove friction in consuming APIs while protecting sensitive data exposed via APIs
  • Best practices that work for an API-centric enterprise


The New Security Vulnerability: Third-party Apps Exposing Enterprise Data

In 2014, cyber criminals targeted thirty-party apps with the sole aim of gaining unauthorized access to consumers’ personal and private data. Third-party apps in the social and consumer services domain, with easily exploitable vulnerabilities, became a weak link in the cyber security chain. We saw hackers access Snapchat users‘ private data by exploiting vulnerabilities in a client app built by a third-party developer, for example.

Attackers have now turned their attention to the corporate crown jewels: enterprise data. Similar techniques can be used to intrude the enterprise: targeting apps developed by third-party developers and partners with access to trusted services that deal with sensitive data, including employee information, competitive intelligence, and intellectual property.

Given the explosion of mobile apps, vulnerability detection tools employed by criminals to automate the discovery of app weaknesses will likely become more advanced. These new tools could enable the exploitation of: unencrypted access to API services; unprotected mobile data caches that store sensitive data such as credit cards and protected health information (PHI); and weak protection of key and credential data by mobile apps.

Armed with these tools, cyber criminals could go after third-party apps that tap sensitive corporate data, especially if these apps are not fully vetted from a security standpoint and lack the necessary security controls that enterprises use to lock down the front door access. In other words, they lack strong application and API security. There’s also the risk that corporate users will fall victim to social engineering techniques and inadvertently installing malware-infected third-party apps that masquerade as legitimate apps.

New attack techniques are emerging, too, including:

  • inroads into the process of vetting developers who need access to sensitive data; for example, a brute force attack on the registration process, or account takeovers of partner admin accounts

  • exploitation of mobile and app vulnerabilities with insecure API access 

  • stealing of sensitive data cached by apps that don’t follow security best practices

  • social engineering of developers to gain unauthorized access of developer keys and credentials.

So what can you do to protect your organization from such attacks?

First, implement a governance process that oversees the lifecycle management of third party apps—from onboarding to decommissioning the apps. Governance processes should include:

  • Contractual safeguards such as indemnification and liability for third-party developers, when appropriate

  • Conforming to strong security standards when accessing corporate services via APIs or other means; all API calls should be TLS or HTTPS, for example

  • Enforcing a “least-privilege” access model, in which third-party developer and partner apps are provisioned with API keys with the least privileges required for the app to access and transact via APIs

  • Creating policy templates for developers and partners based on their trust level;  they should dictate the level of access given to the apps as well as verification requirement for their trust category

  • Instituting an audit process to periodically verify the security controls of apps as well as revisit the access control requirements for APIs; for example, reducing the API privileges associated with a partner who downgraded from a premium to a standard service level (any changes to the API access level will not become effective unless the current app key is decommissioned and replaced with a new key)

In summary, third-party apps are the side doors into your digital assets and can cause great damage to your organization when not properly secured. An enterprise security strategy should include the third-party app governance, an API management platform that is developer centric, and tools to enforce and verify security controls employed by the third-party apps.

Photo: Simon Cocks/Flickr


Tutorial: Securing your Apigee-127 API with OAuth 2.0

Let's continue our series on Apigee-127. This time, we'll walk through the basic steps for adding OAuth 2.0 security to an Apigee-127 API.

Why do you need OAuth?

Let's say an app needs to access account information from your bank. Do you want to give that app your banking password? Do you know who wrote the app or where it's running? How will the app protect your password? Can it be trusted?

OAuth 2.0 addresses this problem. It allows an app to request an access token from a trusted authorization server. The access token (a random-looking string) is a kind of stand-in for username/password credentials and gives the client app limited access to private data owned by the end user or by the app itself.

One nice thing about an access token is that it can be revoked at any time. Let's say your app is hacked. If you have OAuth, the hacker doesn't have your username and password—just an access token. That access token can be revoked, rendering it useless. And you won't have to change your login credentials for all of your bank accounts, social media sites, or whatever services that the app uses on your behalf.

Add an OAuth provider to your API

To use OAuth with Apigee-127, you need to add one of two OAuth providers to your API: Apigee or Redis. For this example, we'll use Apigee.

To use the Apigee OAuth service provider, you need to create an Apigee-127 account by specifying the "apigee" provider when prompted. This is required because, behind the scenes, Apigee-127 communicates with Apigee Edge to generate access tokens. All the details are handled for you when you create your account.

Add the provider to your project's swagger.yaml file as an x-a127-services extension, like this:

       provider: "volos-oauth-apigee"
         key: *apigeeProxyKey
         uri: *apigeeProxyUri
         tokenLifetime: 300000
           - client_credentials
           - authorization_code
           - implicit_grant
           - password
         tokenPaths: # These will be added to your paths section for you
           token: /accesstoken
           invalidate: /invalidate
           refresh: /refresh
           authorize: /authorize


Grant types

Grant types are essentially OAuth "flows" you can implement to obtain an access token. Each grant type is suited for a specific use case.

In this example, we're going to use the client credentials grant type. This grant type is best suited for cases where the client app is also the owner of the protected resources. For example, the app might require the use of cloud storage to do its work. An end user isn't really involved with this flow:

The token paths are API endpoints exposed by the authorization server (Apigee Edge in this example). An app makes API calls to these endpoints to obtain or refresh access tokens and perform other functions.

The key and uri values are generated for you when you create your Apigee-127 account with "apigee" as the provider. They allow Apigee-127 to communicate with Apigee Edge. The tokenLifetime parameter specifies, in milliseconds, when the generated token will expire.

Apply the OAuth provider to your API

Now that the provider is added, you need to apply it to whichever API paths you wish to protect. Here's how you would secure a path called /weather using the x-a127-authorizations extension. This configuration says: whenever /weather is called, enforce OAuth security!

       x-swagger-router-controller: weather
           oauth2: {}


Get an access token

To get an access token, you can make an API call to your local instance of Apigee-127. For example:

$ curl -X POST "https://localhost:10010/accesstoken" -d "grant_type=client_credentials&client_id=hTYG6fcQGpsO9ZvRke1MiQZ4GAJ&client_secret=we2YiMkZ1vjC"

The parameters are all required. The grant_type parameter simply identifies the grant type so the authorization server knows what to expect. But what about client_id and client_secret?

Briefly, these values come from an app that is registered with the authorization server. Upon successful registration, client ID and client secret keys are generated for the app along with some other metadata. They enable the authorization server to uniquely identify the source of an API call when it receives requests, and are required for most OAuth interactions.

On Apigee Edge, you can register and discover developer apps under the Publish > Developer Apps menu.

Call the API with the access token

To call your secured API, you need to send the access token with every request to a protected path (such as /weather in our example). Access tokens are submitted in the request header as a "Bearer" token. For example:

curl -i -H 'Authorization: Bearer 3JTnOwzrfTtnbMGDdys2ZymGAA7t' 

When Apigee-127 receives this request, it validates the access token, and, if the token is valid, the API call proceeds to the target.

Code samples and more

If you'd like to try out a complete, working example, see the oauth-cc-example in the Apigee-127 samples repo on GitHub. It's easy to install and run, and the README explains how it works. Also, check out our password grant type example.

The IETF OAuth 2.0 specification includes a good introduction to OAuth 2.0 and each of the grant types.

In a future blog, we'll look at how to use OAuth 2.0 scopes to limit an app's access to protected data. In the meantime, visit our Apigee-127 YouTube playlist.

API Security Hygiene: Floss and Brush Daily

October is an important month for security practitioners. It’s National Cyber Security Awareness Month, but it also happens to be National Dental Hygiene Month. October reminds us not only that safeguarding digital assets is everyone's business, but also of the security hygiene that we need to practice on a daily basis.  

How does security hygiene manifest itself in the API-centric world? What kind of flossing and brushing should be part of your API security routine?

The answer depends on the role you play in protecting digital assets in the API value chain. First let's review the roles of API protectors within an API value chain:

•  The app developer is responsible for creating apps (web, mobile, desktop) consumed by end users.

•  The API developer creates and exposes APIs that are consumed by apps.

•  The business user is responsible for business impact and overall governance, sponsors digital transformation in the organization, and consumes analytics data to gain insights into the API program and platform.

•  The IT manager ensures API services availability and security, and manages IT governance.

The API value chain and the API protector roles


There’s a baseline level of security hygiene applicable to all of these roles, including:

•  Role Base Access Control (RBAC) for all users - Every user should be provisioned with the least privilege (permissions) required to accomplish the role. This ensures the protection of data and API management functionality from user errors and malicious behavior.

Rigid password policy compliance - Strong passwords should be used for accessing tools such as developer portals and management consoles; passwords should also be changed periodically. Most organizations follow a 90-day password change policy to protect users and organization from password theft.

•  Fine granular keys - Application keys provisioned to the developers should follow the least-privilege model to minimize unnecessary exposure of API services to apps. For example, if an application doesn’t need to update a user profile, the key associated with the application must not have the privilege to invoke an API that performs a profile update. Furthermore, every app should be provisioned with a unique key to limit damage from key exposure.

There’s a certain amount of additional security hygiene expected from each of the roles supporting the API value chain.

On the app developer front, API key theft is one of the major threats that organizations face today. In addition to user-level authentication, apps authenticate to the APIs using a key and a key secret, which is typically embedded in the app. Any exposure of the app key can potentially result in unauthorized access of data (via published APIs) by malicious users and bots. So app keys should be rotated periodically to mitigate any risk to organizations by way of key theft. Note that key rotation involving mobile, web, and desktop apps will require additional steps, such as updating the app with the new key while supporting the existing application with an older key.

API developers periodically need to review the API products exposed to app developers and ensure that the APIs exposed to internal users, partners, and external users are provisioned with the right API access control. An example would be the use of the OAuth grant type within APIs, and OAuth scope to protect APIs.

Business users should review the requirements of data protection standards and factor in any new privacy and compliance requirements for the data delivered via APIs. For example, personally identifiable information (PII) data delivered via APIs may have cross-border protection requirements. It’s important to verify that consumer data is being collected with user consent and to ensure governance of the PII and sensitive data.

IT managers should periodically review the API audit logs to detect any suspicious activities. This can be automated by feeding the audit logs into security information and event management (SIEM) tools such as our predictive analytics platform Apigee Insights, or Splunk and Sumo Logic. These tools, when configured with appropriate anomaly rules, can detect unusual API access patterns or management activities and alert the security operations staff.  

Good security hygiene prepares organizations to fend off new threats and avoid a painful “root canal” type exercise to respond to the next Heartbleed or Shellshock event. Take a moment to review and improve your security practices so no one gets spooked (this month does end with Halloween, by the way) by any security incident that could have been prevented by meticulous hygiene.

image: Simon Cocks/Flickr