11436 SSO

Tutorial: Using Remote Services and API Key Security

Feb 11, 2015

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.


Scaling Microservices