Send Docs Feedback

Setting up and configuring Edge Microgateway

Edge Microgateway v. 2.1.x

Audience

This topic is for operators who wish to set up and configure a working instance of Edge Microgateway. 

Overview

Structured as a step-by-step tutorial, this topic shows you how to set up and configure a working Edge Microgateway instance. In general, you'll need to follow these same steps each time you set up a new instance of Edge Microgateway. 

After completing the steps in this topic, you'll have a fully configured, working Edge Microgateway installation capable of processing API requests. You'll test the setup by making secure API calls through Edge Microgateway to a backend target. At the end of this topic, you will learn how to add a spike arrest plugin to the Microgateway. You can follow the same pattern to install and use other available plugins. 

This guide is divided into these parts:

 

Prerequisite: Install Edge Microgateway

Follow the instructions in Installing Edge Microgateway. When you complete the installation, you'll be ready to follow the steps in this setup topic. 

When you are finished with the installation, proceed to the next section, "Part 1: Configure Edge Microgateway".

Part 1: Configure Edge Microgateway

In this part you'll use a command-line interface (CLI) command to configure Edge Microgateway to work with your Apigee Edge instance. If you are using Apigee Cloud, then follow the Apigee Cloud configuration steps. If you are on Apigee Private Cloud, follow the steps for Private Cloud.

Apigee Cloud configuration steps

Follow these steps to use Edge Microgateway with Apigee Cloud:

  1. (Optional) Print help for the edgemicro configure command. You can print help this way for any Edge Microgateway CLI command or command option.
edgemicro configure -h
  1. Execute the following command. It requires standard information about your Apigee Edge account: organization name, environment name, username (email address), and password. You must be an Edge organization administrator to use this command:
edgemicro configure -o <org-name> -e <env-name> -u <your Apigee email> 

For example:

edgemicro configure -o docs -e test -u jdoe@example.com

Sample output:

./edgemicro configure -o docs -e test -u wwitman@apigee.com
password:
deleted /Users/ApigeeCorporation/.edgemicro/docs-test-config.yaml
init config
file doesn't exist, setting up
checking for previously deployed proxies
copy auth app into tmp dir
copy config into tmp dir
Give me a minute or two... this can take a while...
App edgemicro-auth added to your org. Now adding resources.
App edgemicro-auth deployed.
checking org for existing vault
creating vault
adding private_key
adding public_key
configuring host edgemicroservices-us-east-1.apigee.net for region us-east-1
updating agent configuration

saving configuration information to: /Users/ApigeeCorporation/.edgemicro/docs-test-config.yaml

vault info:
 -----BEGIN CERTIFICATE-----
MIICpDCCAYwCCQCGOBgzyhn9jANBgkqhkiG9w0BAQsFADAUMRIwEAYDVQQDEwls
b2NhbGhvc3QwHhcNMTYwNDyMjEwMzIzWhcNMTYwNDEzMjEwMzIzWjAUMRIwEAYD
VQQDEwlsb2NhbGhv3QwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDP
1fPS53qJCl1D1nYSjVLoCM4hh5Fk7asxyvk6Hr2iMPskRUuo+JylLxof8YjeK4w
PsrljyL/T6ndrUAJlPngomcszdAr93D1NukikQkVC3PAeRatRN9TFGM1P4TD0pf
vUQF50UB1Y5Fd6R0laVdoeKzGByQ6b8tbYhYNXKFcv423f/qHyZ80w5+2iVItU/
ms/4lvDA1BiURr4z55D0L88L1ihnHnXd8JDL7gSa76gfigitcwVMaYyMemyhxJz
BFTaLn9RcB5TO7apbC9w4lC/Qbtq2Rvyv/Dc0iYD/0dezC7NrulFiykAV66IV5I
OYajNwsfX/c+pvKx+a1HAgMBAAEwDQYJKoZIhvcNAQELBQADgEBALJx+qEhMFKp
2OgNbpBqllPNrrTTcVvulYdtPQZHbvYZk6ijI8+SuA8SzMPbSISJxDPydqtf0mm
74iREoFSVfMzySh+UtF+i0r4RJ+QejvauOB+pwtJ4ohYBDfMZ2pifhJxUWzsNiX
8E3LA34ikutygxYPCHG15nczUPzncgfrmAsZAaJ4PkevqHLN83AqDcXOfMqRP72
xmYHmDMr9dT+DLn3Ez/VpS0LJ/EEXgTUp21HHrNhRmUtaQhQZy9NYYFs+9l9MfC
5BiyaWIS2lprnmyMRg6KuwxOIs/kYUZlf3KFAr5hKvOKcLKB0LOKRB3n9QNtjpM
Rv3Yozcw6lw=
-----END CERTIFICATE-----

The following credentials are required to start edge micro
  key: a3f8f3dfe39158fc3c50b274f0af2234246e0d5f6ea4dd09389b645147151ba3
  secret: 3e9904802fb3c0e8ca408128a11119cf13546d54dac30ace944c097a726a1263

edgemicro configuration complete!

You'll need the returned key and secret later when you start Edge Microgateway.

Apigee Private Cloud configuration steps

Follow these steps to use Edge Microgateway with Apigee Private Cloud.

  1. Print help information for the edgemicro private configure command. You can print help this way for any Edge Microgateway CLI command or command option.
edgemicro private configure -h
  1. Execute the following command. It requires standard information about your Apigee Edge Private Cloud account: organization name, environment name, username (email address), password, management server IP and router IP. You must be an Edge organization administrator to use this command:


    Important: If you have a virtual host alias defined, then use the alias for the -r <router-ip> parameter. You can view virtual hosts in the Edge UI for your organization, under APIs > Environment Configuration > Virtual Hosts.
edgemicro private configure -o <org-name> -e <env-name> -r <router-ip> -m <management-server-ip> -u <your Apigee email>

For example:

edgemicro private configure -o docs -e test -u jdoe@example.com -r http://192.162.52.106:9001 -m http://192.162.52.106:8080

or, if you have a virtual host alias of myorg-test.mycompany.com, you would use a command like this:

edgemicro private configure -o docs -e test -u jdoe@example.com -r myorg-test.mycompany.com -m http://192.162.52.106:8080

Sample output:

delete cache config
checking for previously deployed proxies
configuring edgemicro internal proxy
deploying edgemicro internal proxy
deploying  edgemicro-auth  app
copy auth app into tmp dir
copy config into tmp dir
Give me a minute or two... this can take a while...
App edgemicro-auth added to your org. Now adding resources.

checking org for existing vault creating vault adding private_key adding public_key
configuring host http://192.168.52.106:9001 for region dc-1

The following credentials are required to start edge micro key: a3f8f3dfe39158fc3c50b274f0af2234246e0d5f6ea4dd09389b645147151ba3 secret: 3e9904802fb3c0e8ca408128a11119cf13546d54dac30ace944c097a726a1263
saving configuration information to: /Users/ApigeeCorporation/.edgemicro/docs-test-config.yaml 
vault info: 
-----BEGIN CERTIFICATE----- 
MIICpDCCAYwCCQDpIvWlpaZJGDANBgkqhkiG9w0BAQFADAUMRIwEAYDVQQDEwls 
b2NhbGhvc3QwHhcNMTYwNDA3MTcxNTM5WhcNMTYwND4MTcxNTM5WjAUMRIwEAYD 
VQQDEwlsb2NhbGhvc3QwggEiMA0GCSqGSIb3DQEBAUAA4IBDwAwggEKAoIBAQD3 
OAQ+kf5FH0S0yuj05ITqUODuUJspBPberRMbqOZYHcFswhB0Yvg6JKWxKWBDP9o 
Xl96dtgH7xPFRqIU0zI452jkMQ1fPz2mSaGwik245yfBku7olooXKRKTRKOUoXa 
q3Hld/RPxGSsWtiyyYtKex7tuFdq0Knm1EhowdTRGIgjNvudeYMka/XPRXuykhd 
xIDxWj4rdX+4GPx9qT2eTQC5nOAC7XHVL7ys4KqsAiv28vw10u400KstFFS8Qho 
7FaE0bOKLolKKadKyA60ha1XIw/uSTD6ZQFWQ+XM3OaRbXePWXnSZioSxXcZT7L 
hMUKbsRXw/TCvRB51LgNAgMBAAEwDQYJKoZIhvcNAQELBQADgEBAOuR1OmE/W6j 
gRAarJB5EQuTEpI/9Zpg5c5RAGjzLhkazsycn7pal+IymUjCV7D0oIxTVuTM8ZZ 
57kR5hF/C1ZypDN9i+KGP2ovX8WOCCXYtIQECgZPB/L/7/k7BDuKN4vFBvWUe3X 
s2oyjnVWy+ASqsW8gHfj8ekhe22bP240Oqkbyg9SZP9ol1tvJX6+M0thYwcTwAd 
ft929Icey/MOTQC0jB2qm0gnIx/7KInFXfS5KoFRJoGrWDeckr3RdBo2LhnPaeZ 
1gPYIqphZ3HfisF5KlBXoR8oT/Ilym/nq5COlv+3L4tMIk18F7BQZB60SRazifz 
pFkIxepyr/0= 
-----END CERTIFICATE----- 

edgemicro configuration complete!

Verify the installation

Try running this command to verify the installation. If no errors are reported, everything is set up correctly and you will be able to start the Edge Microgateway successfully. 

edgemicro verify -o <your Apigee org name> -e <environment name> -k <the key returned by the previous command> -s <the secret returned by the previous command>

For example:

edgemicro verify -o docs -e test -k 93b01fd21d86331459ae52f664ae9aeb13eb94767ce40a4f621d172cdfb7e8e6 -s c8c755be97cf56c21f8b0556d7132afbd03625bbd85dc34ebfefae4f23fbcb3c

 

About the configuration

All of the configuration done so far allows Edge Microgateway to bootstrap itself to Apigee Edge. After the bootstrapping succeeds, Edge Microgateway retrieves a payload of additional configuration information from Apigee Edge.

What is this configuration information used for? As we'll discover in the next part of this tutorial, when Edge Microgateway starts, it needs to receive a list of special Edge Microgateway-aware API proxies that are already deployed on Apigee Edge. Edge Microgateway restricts clients to calling only the APIs fronted by these API proxies, and clients will be required (by default) to present a valid security token for each call. To read more about these proxies, see "What you need to know about Edge Microgateway-aware proxies" in the Overview of Edge Microgateway.

As an Edge org admin, you'll be interested to know that Edge Microgateway-aware proxies can be added to Edge products, just like any other proxies. Through the use of products and developer apps, you can generate client-specific security tokens to control access to APIs called through Edge Microgateway. Again, the patterns involved are identical to working with any API proxies, products, and developer apps on Apigee Edge. If you'd like to read up on products, start with What is an API product? in the Edge documentation.

Next we'll walk through how to create Edge Microgateway-aware proxies, and after that, we'll start Edge Microgateway and test the setup.

 

Part 2: Create entities on Apigee Edge

The main goals of this part are to create these entities on Edge:

  • A microgateway-aware proxy - This is a special proxy that Edge Microgateway can discover upon startup. Microgateway-aware proxies have a naming convention that you must follow: the name must being with edgemicro_. For example edgemicro_hello. When Edge Microgateway starts, it retrieves from Edge a list of any of these microgateway-aware proxies that exist in your Edge organization and environment that you specify when you start the microgateway.

    For each microgateway-aware proxy, Edge Microgatway retrieves the target URL of the proxy and its base path. Microgateway-aware proxies also provide a convenient way to associate analytics data generated by Edge Microgateway with a proxy on the Edge platform. As the microgateway handles API calls, it asynchronously pushes analytics data to Edge. Analytics data will show up in the Edge Analytics UI under the microgateway-aware proxy name(s), as it does for any other proxy.

    Note: Do not attach policies or make conditional flows in microgateway-aware proxies, because they will never execute. Microgateway-aware proxies are never called directly -- they only serve to provide configuration information to Edge Microgateway and as a way to surface analytics data in the Edge analytics system.
  • A product, developer, and developer app - Edge Microgateway uses products, developers, and developer apps to enable OAuth2 access token or API key security. When Edge Microgateway starts, it downloads all of the product configurations from Edge (for the org/environment against which Edge Microgateway is started). It uses this information to verify API calls made through Edge Microgateway with API keys or OAuth2 access tokens. 

Read more: See also "What you need to know about Edge Microgateway-aware proxies" in the Overview of Edge Microgateway.

1. Create an Edge Microgateway-aware API proxy on Edge

Edge Microgateway-aware proxies must point to an HTTP  target endpoint. In other words, the TargetEndpoint for the proxy must include an HTTPTargetConnection. Edge Microgateway is not designed to work with proxies that use the ScriptTarget element to point to Node.js applications as backend targets. See also Endpoint properties reference and Specify the Node.js target with ScriptTarget

Important: Do not apply policies or create conditional flows in the microgateway-aware (edgemicro_*) proxy described in this step. This proxy is used by Edge Microgateway to obtain configuration that it uses to make secure API calls to the target endpoint specified by this proxy. Policies attached to this proxy will never execute. If you want to add policy functionality, such as quota, spike arrest, or OAuth2 security, you need to use Edge Microgateway plugins. For details, see Use plugins. See also Overview of Edge Microgateway.

  1. Log in to your organization on Apigee Edge.
  2. Select APIs > API Proxies from the top menu.
  3. In the API Proxies page, click + API Proxy.
  4. In the Build a Proxy wizard, select Reverse proxy (most common).
  5. In the Details page of the wizard, configure as follows, where we point to an example target API that we can use for testing purposes:
    • Proxy Name: edgemicro_hello
    • Proxy Base Path: /hello
    • Existing API: http://mocktarget.apigee.net/
  6. Click Next.

    Important: Edge Microgateway-aware proxy names must always begin with the prefix edgemicro_.
     
  7. In the Security page of the wizard, select Pass through (none).
  8. Click Next.
  9. In the Virtual Hosts page of the wizard, accept the defaults.
  10. Click Next.
  11. In the Build page of the wizard, review your proxy settings. Make sure the test environment is selected.
  12. Click Build and Deploy.

2. Create a product

You just need a product that contains your Edge Microgateway-aware proxy(s):

  1. Log in to the Edge management UI.
  2. Go to Publish > Products.
  3. In the Products page, click + Product.
  4. Fill out the Product Details dialog as follows:
    1. Name: EdgeMicroTestProduct
    2. Display Name: EdgeMicroTestProduct
    3. Environment: test and prod
    4. Access: Public
    5. Key Approval Type: Automatic
    6. Resources:
      • API Proxy: Add these two proxies: edgemicro_hello and edgemicro-auth
      • Revision: 1
      • Resource Path: /**
  5. Click Import Resource.
  6. Click Save.

3. (Optional) Create a test developer

For the purpose of this tutorial, you can use any existing developer for the next step, creating a developer app. But if you wish, create a test developer now:

  1. Go to Publish > Developers.
  2. In the Products page, click + Developer.
  3. Fill out the dialog to create a test developer.

4. Create a developer app

You are going to use the client credentials from this app to make secure API calls through Edge Microgateway:

  1. Go to Publish > Developer Apps.
  2. In the Developer Apps page, click + Developer App.
  3. Fill out the Developer App dialog as follows:
    1. Name: EdgeMicroTestApp
    2. Display Name: EdgeMicroTestApp
    3. Developer: If you created a test developer, select it. Or, you can use any existing developer for the purpose of this tutorial.
    4. Products: Select EdgeMicroTestProduct (the product you just created)
  4. Click the checkmark button next to the Products field to add the product.
  5. Click Save.
  6. You're back in the Developer Apps list page.
  7. Select the app you just created, EdgeMicroTestApp.
  8. Click Show next to the Consumer Key and Consumer Secret.

You'll need to use these keys later when you configure use API Key or OAuth2 access token security for your API.

Part 3: Operate Edge Microgateway

Now that you have a configured Edge Microgateway and at least one Edge Microgateway-aware proxy on Edge, it's time to start up Edge Microgateway. An Edge Microgateway HTTP server will run on your local machine, and you'll make API calls directly to that server.

1. Start Edge Microgateway

Use the edgemicro start command to start Edge Microgateway.

  1. Print help information for the edgemicro start command. We're going to use the -k, and -s options to start Edge Microgateway. Execute the help command to see all the command options. For more information on startup options, see CLI reference for Edge Microgateway.
edgemicro start -h
  1. Now, be sure you have the keys that were returned previously when you ran the edgemicro configure command. That output looked something like this:
You need key and secret while starting edgemicro instance

key: da4778e7c240a5d4585fc559eaba5083328828ac9f3a7f583e8b73e
secret: 3aad7439708b4aeb38ee08e87189921ad00e6fc1ba8a8ae9f929ee2
  1. To start Edge Microgateway, execute the following command, substituting names for your Edge org and environment, and the key and secret values.
edgemicro start -o <your org> -e <your env> -k <key> -s <secret>

For example:

 edgemicro start -o docs -e test -k 701e70e718ce6dc1880616b3c39177d64a88754d615c7a4e1f78b6181d000723 -s 05c14356e42d136b83dd135cf8a18531ff52d7299134677e30ef4e34ab0cc824

Sample output

The start command retrieves a lot of configuration information from Apigee Edge (which scrolls into the terminal window). In the output, you'll see a list of microgateway-aware proxies and products that were discovered. At the end of the output, you should see something like this:

installed plugin from analytics
installed plugin from oauth
578dc8a0-f2aa-11e5-9078-47057a418de6 edge micro listening on port 8000
edge micro started
command started successfully.

What happened?

Look at the terminal where you ran the edgemicro config command. Scrolling up through the standard output, you can see that the command retrieves a payload of Edge Microgateway configuration information from Apigee Edge. This information includes:

  • The public key we created and stored previously in the Apigee vault.
  • A JSON representation of all Edge Microgateway-aware proxies that exist in the organization/environment. These are all proxies that are named with the prefix edgemicro_.
  • A JSON representation of all of the API products that exist in the organization/environment.

With this information, Edge Microgateway knows which proxies and proxy paths it is allowed to process. It uses the product information to enforce security (in exactly the same way as any API proxy does on Apigee Edge, where developer app keys have an association with products). We'll go through the steps to secure Edge Microgateway shortly.

2. Test Edge Microgateway

Now Edge Microgateway is running, and it is configured to be able to call the /hello base path and the backend target http://mocktarget.apigee.net/. It knows about these paths because they were specified in the edgemicro_hello proxy. The configuration for that proxy was downloaded from Edge when you started Edge Microgateway.

To test Edge Microgateway, we start with the base path and add a resource path /echo. Note that everything after the base path (including any query parameters) is simply passed through to the backend target.

  1. Call the API as follows.
curl -i http://localhost:8000/hello/echo
{"error":"missing_authorization","error_description":"Missing Authorization header"}

This error occurs because we did not send a valid API key or access token with the request. By default, Edge Microgateway requires either an API key or an access token on every API call. In the next step of the tutorial, we'll secure this API properly and show you how to obtain a valid access token and include it with the request.

3. Stop Edge Microgateway

Hit Control-C in the terminal window where Edge Microgateway is running. 

Part 4: Secure Edge Microgateway

You can secure API calls made through Edge Microgateway using an  API key or an access token.

Secure API calls with an OAuth2 access token

Edge Microgateway does not invoke regular Edge API proxies. An access token generated for Edge Microgateway cannot be used to invoke Edge proxies protected by the OAuthV2 policy. Conversely, access token granted to access Edge proxies cannot be used to access APIs called through Edge Microgateway. To use OAuth2 with Edge Microgateway you must follow the specific instructions provided below in this section. 

Follow these steps if you want to authenticate API calls with an OAuth2 access token:

1. Configuration in the Edge UI

You can skip these Edge UI steps if you already created the product called EdgeMicroTestProduct, and if it lists the edgemicro_hello and edgemicro-auth proxies, as explained in Part 2: Create entities on Apigee Edge. Here are the steps again if you need to create this product:

  1. Go to Publish->Products.
  2. Select the Product containing the Edge Microgateway-aware proxy you wish to protect. This is the same product you set up previously in the tutorial in Part 2: Create entities on Apigee Edge. We called the product EdgeMicroTestProduct.
  3. Be sure that you have both the edgemicro_hello and edgemicro-auth proxies listed in the product. If not continue with the next step.
  4. Select Edit.
  5. Under Resources > API Proxies, click + API Proxy.
  6. In the dropdown menu, select the Edge Microgateway authentication proxy. The proxy is called edgemicro-auth. This proxy was deployed when Edge Microgateway was originally set up and configured. Both the edgemicro_hello and edgemicro-auth proxies must be listed in the product.
  7. Click Save.
  8. In the same Product page, under Developer Apps, click the developer app. Earlier in the tutorial, we called it EdgeMicroTestApp.
  9. In the Developer App page, show the Consumer Key and the Consumer Secret, and copy them. These values are required to obtain an access token in the next step.

2. Get an access token

There are two ways to get an access token. We'll show you both methods:

  • You can use the Edge Microgateway CLI, or
  • You can make an HTTP request directly to the token endpoint on Apigee Edge.

The first method is convenient, and follows the pattern we've used throughout the tutorial. The second method is generally more useful for client app developers who need to request tokens. The actual token endpoint is implemented in the proxy you deployed earlier with the deploy-edge-service CLI command.

Using the CLI to get a token

  1. View help for the token get command:
edgemicro token get -h
  1. Generate the token, substituting your Consumer Key and Consumer Secret values from the developer app you created on Apigee Edge in the -i and -s parameters:
edgemicro token get -o <org> -e <env> -i G0IAeU864EtBo99NvUbn6Z4CBwVcS2 -s uzHTbwNWvoSmOy

Using an API to get a token

If you're used to calling Edge proxies using curl or another HTTP client, you'll be interested to know that you can call the token endpoint directly, rather than using the edgemicro token command. Here's a curl example. Just substitute your org and environment names in the URL, and pass the colon-separated Consumer Key:Consumer Secret values in a Basic Authentication header:

curl -i -X POST --user 4t8X137pOUUtMR7wag3M1yZTcRxeK:RAcOFVOvO0jns "http://<org>-<env>.apigee.net/edgemicro-auth/token" -d '{"grant_type": "client_credentials"}' -H "Content-Type: application/json"

Output:

The command, whether you used the edgemicro token CLI command or called the endpoint using curl, returns a signed access token that can be used to make client calls. Something like this:

MIICpDCCAYwCCQDpIvWlpaZJGDANBgkqhkiG9w0BAQFADAUMRIwEAYDVQQDEwls 
b2NhbGhvc3QwHhcNMTYwNDA3MTcxNTM5WhcNMTYwND4MTcxNTM5WjAUMRIwEAYD 
VQQDEwlsb2NhbGhvc3QwggEiMA0GCSqGSIb3DQEBAUAA4IBDwAwggEKAoIBAQD3 
OAQ+kf5FH0S0yuj05ITqUODuUJspBPberRMbqOZYHcFswhB0Yvg6JKWxKWBDP9o 
Xl96dtgH7xPFRqIU0zI452jkMQ1fPz2mSaGwik245yfBku7olooXKRKTRKOUoXa 
q3Hld/RPxGSsWtiyyYtKex7tuFdq0Knm1EhowdTRGIgjNvudeYMka/XPRXuykhd 
xIDxWj4rdX+4GPx9qT2eTQC5nOAC7XHVL7ys4KqsAiv28vw10u400KstFFS8Qho 
7FaE0bOKLolKKadKyA60ha1XIw/uSTD6ZQFWQ+XM3OaRbXePWXnSZioSxXcZT7L 
hMUKbsRXw/TCvRB51LgNAgMBAAEwDQYJKoZIhvcNAQELBQADgEBAOuR1OmE/W6j 
gRAarJB5EQuTEpI/9Zpg5c5RAGjzLhkazsycn7pal+IymUjCV7D0oIxTVuTM8ZZ 
57kR5hF/C1ZypDN9i+KGP2ovX8WOCCXYtIQECgZPB/L/7/k7BDuKN4vFBvWUe3X 
s2oyjnVWy+ASqsW8gHfj8ekhe22bP240Oqkbyg9SZP9ol1tvJX6+M0thYwcTwAd 
ft929Icey/MOTQC0jB2qm0gnIx/7KInFXfS5KoFRJoGrWDeckr3RdBo2LhnPaeZ 
1gPYIqphZ3HfisF5KlBXoR8oT/Ilym/nq5COlv+3L4tMIk18F7BQZB60SRazifz 
pFkIxepyr/0=
3. Configuration in Edge Microgateway
  1. Stop Edge Microgateway by pressing control-c in the window where the process is running.
  2. Be sure that the oauth plugin is configured properly.  Open <microgateway-root-dir>/config/default.yaml, where <microgateway-root-dir> is the directory where Edge Microgateway was installed when you ran the npm install command, and make sure these oauth plugin properties are set to false. They're false by default, but it's a good idea to double-check:
    oauth:
       allowNoAuthorization: false
       allowInvalidAuthorization: false
  3. Also in the default.yaml file, be sure that the oauth plugin is added to the plugins sequence element, like this::
    plugins:
       dir: ../plugins
       sequence:
       - oauth
  4. Reconfigure Edge Microgateway:
    edgemicro configure -o docs -e test -u jdoe@example.com
  5. Restart Edge Microgateway, using the new key and secret values returned by the config:
    edgemicro start -o docs -e test -k a48148fde021a14ad89de0e5322de29587e36208faba8bdc62e4bb921ed90ff7 -s 6d9a401a6be70c220758efd4792993dae2e66a60e592d88f38e748b674bd5c22

4. Call the API securely

With an access token in hand, you can now make the API call securely. For example:

  curl -i -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhcHBsaWNhdGlvbl
9uYW1lIjoiYmU2YmZjYjAtMWQ0Ni00Y2IxLWFiNGQtZTMxNzRlNTAyMDZkIiwiY2xpZW50X2lkIjoiOGxTTTVIRHdyM
VhIT1ZwbmhURExhYW9FVG5STVpwWk0iLCJzY29wZXMiOltdLCJhcGlfcHJvZHVjdF9saXN0IjpbIk1pY3JvZ2F0ZXdh
eVRlQcm9kdWN0Il0sImCI6MTQzNTM0NzY5MiwiZXhwIjoxNDM1MzQ5NDkxfQ.PN30Y6uK1W1f2ONPEsBDB_BT31c6
IsjWGfwpz-p6Vak8r767tAT4mQAjuBpQYv7_IU4DxSrnxXQ_q536QYCP4p4YKfBvyqbnW0Rb2CsPFziy_n8HIczsWO
s0p4czcK63SjONaUpxV9DbfGVJ_-WrSdqrqJB5syorD2YYJPSfrCcgKm-LpJc6HCylElFDW8dHuwApaWcGRSV3l5Wx
4A8Rr-WhTIxDTX7TxkrfI4THgXAo37p3au3_7DPB_Gla5dWTzV4j93xLbXPUbwTHzpaUCFzmPnVuYM44FW5KgvBrV0
64RgPmIFUxSqBWGQU7Z1w2qFmWuaDljrMDoLEreI2g" http://localhost:8000/hello/echo

The API returns headers and other information from the mock server.

Securing the API with an API key

If you wish to use an API key for authorization, follow these steps:

1. Configuration in the Edge UI

You can skip these Edge UI steps if you already created the product called EdgeMicroTestProduct, and if it lists the edgemicro_hello and edgemicro-auth proxies, as explained in Part 2: Create entities on Apigee Edge. Here are the steps again if you need to create this product:

  1. Go to Publish->Products.
  2. Select the Product containing the Edge Microgateway-aware proxy you wish to protect. This is the same product you set up previously in the tutorial in Part 2: Create entities on Apigee Edge. We called the product EdgeMicroTestProduct.
  3. Select Edit.
  4. Under Resources > API Proxies, click + API Proxy.
  5. In the dropdown menu, select the Edge Microgateway authentication proxy. The proxy is called edgemicro-auth. This proxy was deployed when Edge Microgateway was originally set up and configured. 
  6. Click Save.
  7. In the same Product page, under Developer Apps, click the developer app. Earlier in the tutorial, we called it EdgeMicroTestApp.
  8. In the Developer App page, show the Consumer Key, and copy it. This value is the API key. You'll use this key to make an authenticated call to the API.

2. Configuration in Edge Microgateway

To pull the Edge changes you just made into the Edge Microgateway configuration, follow these steps:

  1. Stop Edge Microgateway by pressing control-c in the window where the process is running.
  2. Be sure that the oauth plugin is configured properly. Open <microgateway-root-dir>/config/default.yaml, where <microgateway-root-dir> is the directory where Edge Microgateway was installed when you ran the npm install command, and make sure these properties are set to false. They're false by default, but it's a good idea to double-check:
    oauth:
       allowNoAuthorization: false
       allowInvalidAuthorization: false
  3. Also in the default.yaml file, be sure that the oauth plugin is added to the plugins sequence element, like this:
    plugins:
       dir: ../plugins
       sequence:
       - oauth
  4. Reconfigure Edge Microgateway:
    edgemicro configure -o docs -e test -u jdoe@example.com
  5. Restart Edge Microgateway, using the new key and secret values returned by the config:
    edgemicro start -o docs -e test -k a48148fde021a14ad89de0e5322de29587e36208faba8bdc62e4bb921ed90ff7 -s 6d9a401a6be70c220758efd4792993dae2e66a60e592d88f38e748b674bd5c22

3. Call the API securely with an API key

Call the API with the x-api-key header as follows. The Consumer Key value you copied from the Developer App is the API key. By default, Edge Microgateway expects you to pass the key in a header called x-api-key, like this:

curl -i http://localhost:8000/hello/echo -H "x-api-key: <Consumer key copied from the developer app>"

For example:

curl -i http://localhost:8000/hello/echo -H 'x-api-key: XsU1R4zGXz2ERxa0ilYQ5szwuljr5bB'

 

You now have a fully functioning and secure Edge Microgateway. In the next part of the tutorial, we'll take a look at plugins that add functionality to an Edge Microgateway instance.

 

Part 5: Add a Spike Arrest plugin

In this part, we'll add a rate-limiting feature called spike arrest to your instance of Edge Microgateway.

  • Adding the spike arrest plugin
  • Extra credit: Adding the quota plugin

What are plugins?

A plugin is a Node.js module that adds functionality to Edge Microgateway. Plugin modules follow a consistent pattern and are stored in a location known to Edge Microgateway, enabling the microgateway to discover and load them automatically. You can read more about plugins in the Develop custom plugins.

Adding the spike arrest plugin

Spike Arrest protects against traffic spikes. It throttles the number of requests processed by an Edge Microgateway instance.

In Edge Microgateway, spike arrest is implemented as a plugin module. To enable it, you need to add it to the Edge Microgateway configuration file.

  1. Stop Edge Microgateway by pressing control-c in the window where the process is running.
  2. Open ~/.edgemicro/<org>-<env>-config.yaml in an editor. See also "Making configuration changes".
  3. Add the following element. You can add it anywhere in the file.
   spikearrest:
      timeUnit: minute   
      allow: 10   
      buffersize: 0   
  1. Add spikearrest element to the sequence element under plugins, as shown below. The sequence configuration property tells Edge Microgateway the order in which the plugin modules are executed.
edgemicro:
  home: ../gateway
  port: 8000
  max_connections: -1
  max_connections_hard: -1
  logging:
    level: info
    dir: /var/tmp
    stats_log_interval: 60
  plugins:
    dir: ../plugins
  sequence:
    - spikearrest
    - oauth 
  1. Save the config file.
  2. Restart Edge Microgateway with the edgemicro start command as explained previously.
  3. Try calling the API several times in quick succession. After the second call, Edge Microgateway returns this error:
{"error": "spike arrest policy violated"}

The reason is that spike arrest smooths out the number of calls that can be made over the specified time unit. So, in this case, you can make 10 calls in a minute, or one every 6 seconds.

For more information, see "How does spike arrest work?" in the Develop custom plugins.

Extra credit: Adding the quota plugin

Following the same pattern used to configure spike arrest, you can add other plugins, like the quota plugin. Like with spike arrest, the quota plugin is included with every Edge Microgateway installation. A quota specifies the number of request messages that an app is allowed to submit to an API over a specified time interval (minutes or hours).

To learn how quotas work, see "Using the quota plugin" in the Develop custom plugins.

Part 6: Viewing analytics on Apigee Edge

We now have a fully functioning Edge Microgateway instance, let's see what's it's been up to! By default, the analytics plugin module is added to Edge Micro. This module silently pushes analytics data from Edge Micro to Apigee edge, where it is consumed by the Edge Analytics system. Let's see:

  1. Log in to your organization on Apigee Edge.
  2. Select Analytics > Proxy Performance.
  3. In the Proxy Performance dashboard, select the edgemicro_hello proxy.
  4. The graph shows you information about the the proxy's traffic patterns, such as total traffic, average response time, average target response time, and more.

You can read more about Edge Analytics dashboards on the Analytics Dashboards home page in the Edge documentation. To learn more about plugins, see the Develop custom plugins.

Help or comments?