You're viewing **Apigee Edge** documentation. [Go to the **Apigee X** documentation](http://cloud.google.com/apigee/docs). 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](https://docs.apigee.com/api-platform/microgateway/3.3.x/setting-and-configuring-edge-microgateway#Prerequisite) - **Part 1:** [Configure Edge Microgateway](https://docs.apigee.com/api-platform/microgateway/3.3.x/setting-and-configuring-edge-microgateway#Part1) - **Part 2:** [Create entities on Apigee Edge](https://docs.apigee.com/api-platform/microgateway/3.3.x/setting-and-configuring-edge-microgateway#Part2) - **Part 3:** [Operate Edge Microgateway](https://docs.apigee.com/api-platform/microgateway/3.3.x/setting-and-configuring-edge-microgateway#Operating%20Edge%20Microgateway) - **Part 4:** [Secure Edge Microgateway](https://docs.apigee.com/api-platform/microgateway/3.3.x/setting-and-configuring-edge-microgateway#Secure) - **Part 5:** [Add the Spike Arrest plugin](https://docs.apigee.com/api-platform/microgateway/3.3.x/setting-and-configuring-edge-microgateway#Part4) - **Part 6:** [View Analytics data on Apigee Edge](https://docs.apigee.com/api-platform/microgateway/3.3.x/setting-and-configuring-edge-microgateway#Part5) ## Prerequisite: Install Edge Microgateway Follow the instructions in [Installing Edge Microgateway](https://docs.apigee.com/api-platform/microgateway/3.3.x/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](https://docs.apigee.com/api-platform/microgateway/3.3.x/overview-edge-microgateway#whatyouneedtoknowaboutedgemicrogateway-dependencyonapigeeedge). - If you are using Apigee Edge Cloud, then follow the [Apigee Edge Cloud configuration steps](https://docs.apigee.com/api-platform/microgateway/3.3.x/setting-and-configuring-edge-microgateway#Cloud%20config). - If you are on Apigee Private Cloud, follow the [Apigee Edge Private Cloud steps](https://docs.apigee.com/api-platform/microgateway/3.3.x/setting-and-configuring-edge-microgateway#Private%20config). ### Apigee Edge Cloud configuration steps Follow these steps to use Edge Microgateway with Apigee Edge Cloud: 1. Initialize Edge Microgateway (you only need to do this step one time): ``` edgemicro init ``` 2. 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`. 3. All CLI commands have a help function. Print help for the **edgemicro configure** command: ``` edgemicro configure -h ``` 4. 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](https://docs.apigee.com/api-platform/microgateway/3.3.x/cli-reference-edge-microgateway#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 ``` > [!NOTE] > **Note:** 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. Initialize Edge Microgateway (you only need to do this step one time): ``` edgemicro init ``` 2. 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 ``` 3. 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] > **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](https://docs.apigee.com/api-platform/microgateway/3.3.x/cli-reference-edge-microgateway#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] > **Note:** If you have a virtual host alias defined, then use the alias for the `-r ` parameter. You can view virtual hosts in the Edge UI for your organization, under **APIs \> Environment > Configuration \> Virtual Hosts**. ### Verify the installation > [!NOTE] > **Note:** If you have [enabled SAML](https://docs.apigee.com/api-platform/system-administration/enabling-saml-authentication-edge) in your organization, you must update your Edge Microgateway config file with vhost url's, wherever micro-auth proxy was being referred. By default its pointing to saml login page. 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. > [!NOTE] > 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?](https://docs.apigee.com/api-platform/faq/edge-microgateway-faq#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](https://docs.apigee.com/api-platform/microgateway/3.3.x/overview-edge-microgateway#whatyouneedtoknowaboutedgemicrogateway-whatyouneedtoknowaboutedgemicrogatewayawareproxies)" in the [Overview of Edge Microgateway](https://docs.apigee.com/api-platform/microgateway/3.3.x/overview-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?](https://docs.apigee.com/api-platform/publish/what-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](https://docs.apigee.com/api-platform/microgateway/3.3.x/overview-edge-microgateway#whatyouneedtoknowaboutedgemicrogateway-dependencyonapigeeedge) - 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 > [!NOTE] > **Note:** 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 either the ScriptTarget or LocalTargetConnection element. ScriptTarget is used to specify Node.js target applications and LocalTargetConnection is used for proxy chaining. > [!NOTE] > **Note:** Do not attach policies or make conditional flows in microgateway-aware proxies, because microgateway proxies never execute on Apigee Edge. Microgateway-aware proxies only serve to provide configuration information to your locally running Edge Microgateway and as a way to surface analytics data in the Edge analytics system. 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](https://docs.apigee.com/api-platform/microgateway/3.3.x/use-plugins). See also [Develop custom > plugins](https://docs.apigee.com/api-platform/microgateway/3.3.x/develop-custom-plugins). 1. Log in to your organization on Apigee Edge. 2. Select **Develop \> API Proxies** in the side navigation menu. 3. Click **+ Proxy**. The Build a Proxy wizard is invoked. 4. In the first wizard page, select **Reverse proxy (most common)**. 5. Click **Next**. 6. In the Details page of the wizard, configure as follows. Be sure to fill in the wizard exactly as shown: > [!NOTE] > **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] > **Note:** Be sure to enter the basepath **/hello**. Don't accept the default, which is to use the proxy name as the base path. 7. Click **Next**. 8. In the Security page of the wizard, select **Pass through (none)**. 9. Click **Next**. 10. In the Virtual Hosts page of the wizard, accept the defaults. 11. Click **Next**. 12. In the Build page of the wizard, review your proxy settings. Make sure the **test** environment is selected. 13. Click **Build and Deploy**. ### 2. Create an API product > [!NOTE] > **Note:** Be sure to create an API product that contains **two > proxies** : > > - Your microgateway-aware proxy: **edgemicro_hello** > - The authentication proxy that was installed by Edge Microgateway: **edgemicro-auth**. > > The edgemicro-auth proxy must be present in the product if you want to use API Key or OAuth > security. 1. Select **Publish \> API Products** in the side navigation menu. 2. **Click + API Product**. 3. 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 | 4. In the API resources section, add the API proxy you just created and the **edgemicro-auth** proxy: - **edgemicro_hello** - **edgemicro-auth** 5. 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: 1. Select **Publish \> Developers** in the side navigation menu. 2. 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. Select **Publish \> Apps** in the side navigation menu. 2. Click **+ App**. The Developer App Details page appears. 3. 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) 4. Click **Save**. 5. You're back in the Apps list page. 6. Select the app you just created, **EdgeMicroTestApp**. 7. Click **Show** next to the **Consumer Key** and **Consumer Secret**. ![](https://docs.apigee.com/static/api-platform/images/edge-micro-dev-app.png) > [!NOTE] > **Note:** 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. 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 ``` 2. (Optional) Print help information for the `edgemicro start` command. ``` edgemicro start -h ``` 3. 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 ``` 4. 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] > **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](https://docs.apigee.com/api-platform/microgateway/3.3.x/operation-and-configuration-reference-edge-microgateway#debuggingandtroubleshooting). You can also check the Edge Microgateway log files when debugging a problem. For details, see [Managing log files](https://docs.apigee.com/api-platform/microgateway/3.3.x/operation-and-configuration-reference-edge-microgateway#managinglogfiles). ### 4. Stop Edge Microgateway 1. In a separate terminal window, `cd` to **the same directory** where you started Edge Microgateway. 2. Enter the stop command: ``` edgemicro stop ``` > [!NOTE] > **Note:** There are three commands that you must run from the same directory where you started Edge Microgateway. These include **stop** , **reload** , and **status**. ## 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](https://docs.apigee.com/api-platform/microgateway/3.3.x/setting-and-configuring-edge-microgateway#Oauthtoken) - [Secure API calls with an API Key](https://docs.apigee.com/api-platform/microgateway/3.3.x/setting-and-configuring-edge-microgateway#apikey%20option) ### Secure API calls with an OAuth2 access token > [!NOTE] > **Note:** 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. Get the required keys** 1. In the Edge UI, navigate to the Developer App you created previously. The name of the App was EdgeMicroTestApp. > [!NOTE] > **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. 2. 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. 1. (Optional) View help for the **token get** command: ``` edgemicro token get -h ``` 2. 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** 1. Open the file `$HOME/.edgemicro/org-env-config.yaml`. See [Where is Edge Microgateway installed](https://docs.apigee.com/api-platform/microgateway/3.3.x/installing-edge-microgateway#whereisedgemicrogatewayinstalled) if you can't locate this file. 2. 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 `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 ``` 4. 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** 1. In the Edge UI, navigate to the Developer App you created previously. The name of the App was EdgeMicroTestApp. > [!NOTE] > **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. 2. 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** 1. Open the file `$HOME/.edgemicro/org-env-config.yaml. `See [Where is Edge Microgateway installed](https://docs.apigee.com/api-platform/microgateway/3.3.x/installing-edge-microgateway#whereisedgemicrogatewayinstalled) if you can't locate this file. 2. 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 ``` 3. 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 ``` 4. 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](https://docs.apigee.com/api-platform/microgateway/3.3.x/use-plugins). ### Adding a spike arrest plugin A [spike arrest plugin](https://docs.apigee.com/api-platform/microgateway/3.3.x/use-plugins#usingthespikearrestplugin) 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. Open the file `$HOME/.edgemicro/org-env-config.yaml.`[Where is Edge Microgateway installed](https://docs.apigee.com/api-platform/microgateway/3.3.x/installing-edge-microgateway#whereisedgemicrogatewayinstalled) if you can't locate this file. 2. Add the following element. You can add it anywhere in the file. ``` spikearrest: timeUnit: minute allow: 10 buffersize: 0 ``` 3. 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 ``` 4. Save the config file. 5. 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 ``` 6. 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](https://docs.apigee.com/api-platform/microgateway/3.3.x/use-plugins#usingthequotaplugin). 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: 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 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](https://docs.apigee.com/api-platform/microgateway/3.3.x/use-plugins)