Setting up and configuring Edge Microgateway

You're viewing Apigee Edge documentation.
Go to the Apigee X documentation. info

Edge Microgateway v. 3.3.x

Overview

After completing the steps in this setup guide, 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. You will also learn how to add a spike arrest plugin to the Microgateway.

This guide is divided into these parts:

Prerequisite: Installing Edge Microgateway
Part 1: Configure Edge Microgateway
Part 2: Create entities on Apigee Edge
Part 3: Operate Edge Microgateway
Part 4: Secure Edge Microgateway
Part 5: Add the Spike Arrest plugin
Part 6: View Analytics data on Apigee Edge

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 tutorial.

Part 1: Configure Edge Microgateway

In this part you'll use a command-line interface (CLI) command to configure Edge Microgateway to communicate with Apigee Edge.

If you are using Apigee Edge Cloud, then follow the Apigee Edge Cloud configuration steps.
If you are on Apigee Private Cloud, follow the Apigee Edge Private Cloud steps.

Apigee Edge Cloud configuration steps

Follow these steps to use Edge Microgateway with Apigee Edge Cloud:

Initialize Edge Microgateway (you only need to do this step one time):
```
edgemicro init
```
A config file called default.yaml file was placed in your home directory in a subdirectory called .edgemicro. Check now to be sure this file exists:
```
ls ~/.edgemicro
default.yaml
```
Note: In the Edge Microgateway docs, we refer to the home directory with the tilde (~), which is a UNIX shortcut. If you're on Windows, if you're running a shell that does not support the tilde, you will need to substitute the appropriate environment variable for the tilde in commands that reference the home directory. For example: %USERPROFILE%/.edgemicro.
All CLI commands have a help function. Print help for the edgemicro configure command:
```
edgemicro configure -h
```
Execute the following command to configure Edge Microgateway:
```
edgemicro configure -o [org] -e [env] -u [username] 
```
Where:
- org: Your Edge organization name (you must be an org administrator).
- env: An environment in your org (such as test or prod).
- username: The email address associated with your Apigee account.
  
  Note: The configure command allows additional parameters. For a complete list, see Configuring Edge Microgateway for Apigee Edge Cloud.

Example

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

Output

./edgemicro configure -o docs -e test -u jdoe@apigee.com
password:
current nodejs version is v12.5.0
current edgemicro version is 3.1.0
password:
file doesn't exist, setting up
Give me a minute or two... this can take a while...
App edgemicro-auth deployed.
checking org for existing KVM
error checking for cert. Installing new cert.
creating KVM
adding private_key
adding public_key
configuring host edgemicroservices-us-east-1.apigee.net for region us-east-1

saving configuration information to: $HOME/.edgemicro/docs-test-config.yaml

vault info:
 -----BEGIN CERTIFICATE-----
MIICpDCCAYwCCQCQ2mJZJGbPPTANBgkqhkiG9w0BAQsFADAUMRIwEAYDVQQDEwls
b2NhbGhvc3QwHhcNMTcwOTA3MjA0ODA4WhcNMTcwOTA4MjA0ODA4WjAUMRIwEAYD
VQQDEwlsb2NhbGhvc3QwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDw
yzmqi5CelqqtTr6IaFe1ssrMXEDnNtkBh95U6F5zHLsNQhJcyNUAO9um6FLMSqSd
fTztXfWUZzDgmbb6sfbx/9cqpvQ8TIjxyIz8xGM9H4legRQmsCQoYGkLjpPE5ZOa
wZrI5IaVm8LY6vbopPFwxgKOQ9bphx6k9Na055DmNyZAOTMD+4I0m/RdsrnZnYih
3DaFj1tXHKZI1jfAt/QOif5Nmk4+JckYwF+9HBysWUbbvj/gnBjVYF2Isb7q7oFD
lPGhwFoIebMqHMWD8lG7+9RJDO9dDV6f1g1/9waIrq1D+MoVXos9VMstNrPp0cKF
Ue+lAkct8tylH+2MosF7AgMBAAEwDQYJKoZIhvcNAQELBQADggEBAJMRdcQh3ayy
csVVT4TYwxV7MKWRfhDRz6X+MM9frB+Z7sI4+ZoZbXKOoZI2hSjmbdLpkNR/m9eJ
+1Uk0JKmpSY7Q+1rRrvcHsWNysGf4z+zDJXYECTrtSnXKBXtb9SJ8JAfoZOQD0lA
zmKuJjQMLTdiYMHOBR6ZWnaKaRvrQwGHcQrheJm4a90XgZF6jcRR8CPrBzkmsbCp
IU/Ux3E17wDGYPxjJs5otyQG8rN/88RGyaSeXK8rjKr9D4KFGJeasXBKmTG2afAr
yfBvS4h6s42FCOR/eLpmMllVoO9up71Fa3EtV+aK+FNNY9uMbgUHeLQE7z9nn06q
PTmvExZLkLQ=
-----END CERTIFICATE-----

The following credentials are required to start edge micro
  key: 27ee39567c75e4567a66236cbd4e86d1cc93df6481454301bd5fac4d3497fcbb
  secret: 4618b0008a6185d7327ebf53bee3c50282ccf45a3cceb1ed9828bfbcf1148b47

Apigee Private Cloud configuration steps

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

Initialize Edge Microgateway (you only need to do this step one time):
```
edgemicro init
```
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
```
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:
```
edgemicro private configure -o [org] -e [env] -u [username] -r [runtime_url] -m [mgmt_url] -v [virtual_host]
```
Where:
- org is your Edge organization name (you must be an org administrator).
- env is an environment in your org (such as test or prod).
- runtime_url is the runtime URL for your private cloud instance.
- mgmt_url is The URL of the management server for your private cloud instance.
- username is the email address associated with your Apigee account.
- virtual_host is a comma-separated list of virtual host names. The default values are default,secure
  Note: By default, the edgemicro-auth proxy expects to connect through a virtual host called secure. If your Private Cloud installation does not have this virtual host defined, you will receive a configuration error. Be sure to specify on the command line a virtual_host that exists. It is generally safe to specify a virtual host called default.
  
  Note: The configure command allows additional parameters. For a complete list, see Configuring Edge Microgateway for Apigee Edge Private Cloud.

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 -v default

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 -v default

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 deer
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 KVM
error checking for cert. Installing new cert.
creating KVM
adding private_key
adding public_key
configuring host http://192.168.52.106:9001 for region dc-1

saving configuration information to: $HOME/.edgemicro/jdoe-test-config.yaml
vault info: 
-----BEGIN CERTIFICATE----- 
MIICpDCCAYwCCQDpIvWlpaZJGDANBgkqhkiG9w0BAQFADAUMRIwEAYDVQQDEwls 
b2NhbGhvc3QwHhcNMTYwNDA3MTcxNTM5WhcNMTYwND4MTcxNTM5WjAUMRIwEAYD 
VQQDEwlsb2NhbGhvc3QwggEiMA0GCSqGSIb3DQEBAUAA4IBDwAwggEKAoIBAQD3 
OAQ+kf5FH0S0yuj05ITqUODuUJspBPberRMbqOZYHcFswhB0Yvg6JKWsKWBDP9o
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----- 

The following credentials are required to start edge micro 
   key: a3f8f3dfe39158fc3c50b274f0af2234246e0d5f6ea4ad09389b645147151ba3
   secret: 3e9904802fb3c0e8ca408128a11119cf13546d54dac10ace944c097a726a1263

edgemicro configuration complete!

Note: 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.

Verify the installation

Run 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 [org] -e [env] -k [key] -s [secret]

Where:

org is your Edge organization name (you must be an org administrator).
env is an environment in your org (such as test or prod).
key is the key returned previously by the configure command.
secret is the key returned previously by the configure command.

Example

edgemicro verify -o docs -e test -k 93b01fd21d86331459ae52f624ae9aeb13eb94767ce40a4f621d172cdfb7e8e6 -s c8c755be97cf56c21f8b0156d7132afbd03625bbd85dc34ebfefae4f23fbcb3c

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.

If you installed Edge Microgateway on or before October 5, 2018, Apigee recommends that you consider taking steps to protect the /products endpoint of the edgemicro-auth proxy. For details, see How do I protect the /products resource?.

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 from Apigee Edge. In the next part of this tutorial, you will create a Microgateway-aware proxy. Edge Microgateway restricts clients to calling only the APIs fronted by these Microgateway-aware 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

In this part, you will 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 begin with edgemicro_. For example edgemicro_hello or edgemicro_userinfo. When Edge Microgateway starts, it retrieves from Edge a list of microgateway-aware proxies from the same Edge organization and environment that you specified when you started Edge 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.
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 your Apigee Edge organization. It uses this information to verify API calls made through Edge Microgateway with API keys or OAuth2 access tokens.

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

Log in to your organization on Apigee Edge.
Select Develop > API Proxies in the side navigation menu.
Click + Proxy. The Build a Proxy wizard is invoked.
In the first wizard page, select Reverse proxy (most common).
Click Next.
In the Details page of the wizard, configure as follows. Be sure to fill in the wizard exactly as shown:

Note: Edge Microgateway-aware proxy names must always begin with the prefix edgemicro_. For example: edgemicro_hello.
- Proxy Name: edgemicro_hello
- Proxy Base Path: /hello
- Existing API: http://mocktarget.apigee.net/
Note: Be sure to enter the basepath /hello. Don't accept the default, which is to use the proxy name as the base path.
Click Next.
In the Security page of the wizard, select Pass through (none).
Click Next.
In the Virtual Hosts page of the wizard, accept the defaults.
Click Next.
In the Build page of the wizard, review your proxy settings. Make sure the test environment is selected.
Click Build and Deploy.

2. Create an API product

Select Publish > API Products in the side navigation menu.
Click + API Product.

Enter the product details shown in the following table:

Field	Description
Name	EdgeMicroTestProduct
Display name	Edge Microgatway Test Product
Environment	test
Access	Public
Key Approval Type	Automatic

In the API resources section, add the API proxy you just created and the edgemicro-auth proxy:
- edgemicro_hello
- edgemicro-auth
Click Save.

3. Create a 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:

Select Publish > Developers in the side navigation menu.
Click + Developer.
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:

Select Publish > Apps in the side navigation menu.
Click + App. The Developer App Details page appears.
Fill out the Developer App page 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. Credentials:
  1. Select Expiration: Never.
  2. Click + Product and select EdgeMicroTestProduct (the product you just created)
Click Save.
You're back in the Apps list page.
Select the app you just created, EdgeMicroTestApp.
Click Show next to the Consumer Key and Consumer Secret.

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.

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: da4778e7c240a5d4585fc559eaba5083328828bc9f3a7f583e8b73e
secret: 3aad7439708b4aeb38ee08e82189921ad00e6fc1ba8a8ae9f929ee2

(Optional) Print help information for the edgemicro start command.
```
edgemicro start -h
```

To start Edge Microgateway, execute the following command:

edgemicro start -o [org] -e [env] -k [key] -s [secret]

Where:

org is your Edge organization name (you must be an org administrator).
env is an environment in your org (such as test or prod).
key is the key returned previously by the configure command.
secret is the key returned previously by the configure command.

Example

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

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:

...

current nodejs version is v12.5.0
current edgemicro version is 3.1.0
info: jwk_public_keys download from null returned 200 undefined
info: jwt_public_key download from https://docs-test.apigee.net/edgemicro-auth/publicKey returned 200 OK
info: products download from https://docs-test.apigee.net/edgemicro-auth/products returned 200 OK
info: config download from https://edgemicroservices-us-east-1.apigee.net/edgemicro/bootstrap/organization/docs/environment/test returned 200 OK
PROCESS PID : 17991

Check the microgateway status. In another terminal window, cd to the same directory where you started Edge Micro and enter this command:
```
edgemicro status
current nodejs version is v12.5.0
current edgemicro version is 3.1.0
edgemicro is running with 8 workers
```

What happened?

A payload of Edge Microgateway configuration information is downloaded from Apigee Edge and cached locally. This information includes:

The public key we created and stored previously in an encrypted Key Value Map (KVM).
A 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 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

With Edge Microgateway running, you can call the proxy. The configuration for the edgemicro_hello proxy was downloaded from Edge when you started Edge Microgateway. Remember, the proxy basepath is /hello.

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:

curl -i http://localhost:8000/hello/echo
{"error":"missing_authorization","error_description":"Missing Authorization header"}

The error occurs because you 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.

Note: If you have a problem, you can restart Edge Microgateway in debug mode using the --debug flag. For details on running in debug mode, see Debugging and troubleshooting. You can also check the Edge Microgateway log files when debugging a problem. For details, see Managing log files.

4. Stop Edge Microgateway

In a separate terminal window, cd to the same directory where you started Edge Microgateway.
Enter the stop command:
```
edgemicro stop
```

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
Secure API calls with an API Key

Secure API calls with an OAuth2 access token

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

1. Get the required keys

In the Edge UI, navigate to the Developer App you created previously. The name of the App was EdgeMicroTestApp.
Note: Be sure that you have both the edgemicro_hello and edgemicro-auth proxies listed in the product associated with the app. Also, make sure the developer you associated with the app is active.
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.

Using the CLI to get an access token

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 edgemicro-auth proxy that was deployed when you configured Edge Microgateway.

(Optional) View help for the token get command:
```
edgemicro token get -h
```

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 [consumer_key] -s [consumer_secret]

Where:

org is your Edge organization name (you must be an org administrator).
env is an environment in your org (such as test or prod).
consumer_id is the Consumer ID in the Developer App you created previously.
consumer_secret is the Consumer Secret in the Developer App you created previously.

Example

edgemicro token get -o docs -e test -i G0IAeU864EtBo99NvUbn6Z4CBwVcS2 -s uzHTbwNWvoSmOy

Output (Sample)

current nodejs version is v12.5.0
{ token: 'eyJ0eXAiOiJKV1QiLCJhbGciSUzI1NiJ9.eyJhcHBsaWNhdGl
vbl9uYW1lIjoiNWNiMGY0tOWMzOC00YmJjLWIzNzEtZGMxZTQzOGYxZGMxI
iwiY2xpZW50X2lkIjoiNVVdBWEdvSU9lbzYwYWV3OTRQN0c1TUFaRTNhSnA
iLCJzY29wZXMiOltdLCJhcGlfcHJvjdF9saXN0IjpbIsVkZ2VNaWNyb1Rlc
3RQcm9kdWN0IlmlhdCI6MTQ3ODIwODMzMiwiZXhwIjoxNDc4MjEwMTMxfQ.
v3Q8Rs0W9FO_XpERwIAMMXhjGamRmmmWgrAy1wJv0-99oajx5ASI5qjNubM
nCF14xxwlVXHcz1VfedA8Nx7Ih145zhWWuPKL9muzhXXnVBRFeBMeeLqJk4
QQ7Bhst7xH_68nJSTE20Egu95DHOCUemfrepDFH0VggY4BmzvwLkBNfz_te
E_YqwKZbpGOLMdKK1vMk0fk0x19SieIMS_aJYeOAklrzUhnFxWJFrsAWsax
NLx_BbQcZzYfK1JSDUrhRNVBuPHMnGjNA_oHw2J4qa6Hsp62PfchG-DIW_t
-0BFnYf3rYXmqyNORqFrOMdl4VxqQ' }

(Optional) Using the 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 "http://[org]-[env].apigee.net/edgemicro-auth/token" -d '{ "client_id": "your consumer key", "client_secret": "your consumer secret", "grant_type": "client_credentials" }' -H "Content-Type: application/json"

Where:

org is your Edge organization name (you must be an org administrator).
env is an environment in your org (such as test or prod).
client_id is the Consumer ID in the Developer App you created previously.
client_secret is the Consumer Secret in the Developer App you created previously.

Output (Sample)

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+kf5FH0S0yuj05ITqUODuUJspBPberRMbqOZYHcFsnhB0Yvg6JKWxKWBDP9o
Xl96dtgH7xPFRqIU0zI452jkMQ1fPz2mSaGwik241yfBku7olooXKRKTRKOUoXa
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. Check the configuration in Edge Microgateway

Open the file $HOME/.edgemicro/org-env-config.yaml. See Where is Edge Microgateway installed if you can't locate this file.
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
```
Also in the org-env-config.yaml file, be sure that the oauth plugin is added to the plugins:sequence element, like this::
```
plugins:
   dir: ../plugins
   sequence:
   - oauth
```
If you make any changes to the file, reload the changes into the running Edge Microgateway instance. This command reconfigures Edge Microgateway with zero-downtime:
```
edgemicro reload -o [org] -e [env] -k [key] -s [secret]
```
Where:
- org is your Edge organization name (you must be an org administrator).
- env is an environment in your org (such as test or prod).
- key is the key returned previously by the configure command.
- secret is the key returned previously by the configure command.
Example
```
edgemicro reload -o docs -e test -k 701e70ee718ce6dc188016b3c39177d64a88754d615c74e1f78b6181d
```

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.PL30Y6uK1W1f2ONPEsBDB_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. Get the API key

In the Edge UI, navigate to the Developer App you created previously. The name of the App was EdgeMicroTestApp.
Note: Be sure that you have both the edgemicro_hello and edgemicro-auth proxies listed in the product associated with the app. Also, make sure the developer you associated with the app is active.
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 authenticated API calls.

2. Check the configuration in Edge Microgateway

Open the file $HOME/.edgemicro/org-env-config.yaml. See Where is Edge Microgateway installed if you can't locate this file.
Make sure these oauth plugin properties are set to false. They're false by default, but you can double-check if you wish:
```
oauth:
   allowNoAuthorization: false
   allowInvalidAuthorization: false
```
Also in the org-env-config.yaml file, be sure that the oauth plugin is added to the plugins:sequence element, like this::
```
plugins:
   dir: ../plugins
   sequence:
   - oauth
    
```
If you make any changes to the file, reload the changes into the running Edge Microgateway instance. This command reconfigures Edge Microgateway with zero-downtime:
```
edgemicro reload -o [org] -e [env] -k [key] -s [secret]
```
Where:
- org is your Edge organization name (you must be an org administrator).
- env is an environment in your org (such as test or prod).
- key is the key returned previously by the configure command.
- secret is the key returned previously by the configure command.
Example
```
edgemicro reload -o docs -e test -k 701e70ee718ce6dc188016b3c30177d64a88754d615c74e1f78b6181d
```

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: [apikey]"

Where:

apikey is the Consumer Key value taken from EdgeMicroTestApp.

For example:


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

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 Edge Microgateway.

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.

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 Use plugins.

Adding a spike arrest plugin

A spike arrest plugin 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.

Open the file $HOME/.edgemicro/org-env-config.yaml.Where is Edge Microgateway installed if you can't locate this file.

Add the following element. You can add it anywhere in the file.

   spikearrest:
      timeUnit: minute   
      allow: 10   
      buffersize: 0

Add spikearrest to the edgemicro:sequence element, 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:
    - oauth
    - spikearrest

Save the config file.
Reload Edge Microgateway with the reload command. You must run this command from the directory where you started Edge Microgateway.
```
edgemicro reload -o [org] -e [env] -k [key] -s [secret]
```
Where:
- org is your Edge organization name (you must be an org administrator).
- env is an environment in your org (such as test or prod).
- key is the key returned previously by the configure command.
- secret is the key returned previously by the configure command.
Example
```
edgemicro reload -o docs -e test -k 701e70ee718ce6dc188016b3c39177d64a88754d615c74e1f78b6181d
```
Try calling the API several times in quick succession. After the second call, Edge Microgateway returns this error:
```
{"message":"SpikeArrest engaged","status":503}
```

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.

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).

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:

Log in to your organization on Apigee Edge.
Select Analytics > Proxy Performance.
In the Proxy Performance dashboard, select the edgemicro_hello proxy.
The graph shows you information about 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 Use plugins