-
Notifications
You must be signed in to change notification settings - Fork 14
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #102 from Moesif/add-wip-readmes
Add WIP READMEs
- Loading branch information
Showing
3 changed files
with
254 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,70 @@ | ||
| # Configuring Kong API Gateway | ||
|
|
||
| ## Setup the Gateway | ||
|
|
||
| The Moesif Developer Portal can be used with a running instance of Kong. To integrate Moesif and Kong, you can follow our guide that covers [integrating Moesif and Kong in detail](https://www.moesif.com/docs/guides/guide-kong-gateway-integration/). Alternatively, you can also check out [our integration documentation for Kong](https://www.moesif.com/docs/server-integration/kong-api-gateway/) if you’re already an experienced Kong user. Once you have the integration set, you’ll be able to complete the rest of the Kong setup for the Developer Portal. | ||
|
|
||
| ## Configure the Gateway | ||
|
|
||
| ### Creating an Endpoint in Kong Manager | ||
|
|
||
| In order to use the developer portal to monetize your APIs, you'll require an endpoint in Kong. If you already have an endpoint created, you can use this existing endpoint. | ||
|
|
||
| If you are using Kong Manager, you can create the endpoint by clicking **Services** in the left-side menu, under the **API Gateway** section. On the **Services** page, click the **New Service** button in the top-right corner to add a new service. | ||
|
|
||
| On the **Create Service** page, You will need to fill out the **Name** and, after selecting the **Add using URL** option, the **URL** field. For this example, you can fill them out with the following values: | ||
|
|
||
| | Field | Value | | ||
| |-----------|---------------------------| | ||
| | Name | `HttpBin` | | ||
| | URL | `https://www.httpbin.org` | | ||
|
|
||
| Once populated, click **Create** to create the service. After this, you’ll see your new services viewing page. | ||
|
|
||
| Next, we will create a route that will expose this service. To do this, click on **Routes** in the left-side menu, which is also under the **API Gateway** section. | ||
|
|
||
| On the **Routes** page, click on the **Create Route** button in the top-right corner of the screen to add the new route. On the **Create Route** screen, you’ll have a few values to fill out including the **Service, Name**, **Protocols**, **Method(s)**, and **Path(s)** fields on the screen. For this example, you can fill out these fields with the following values: | ||
|
|
||
| | Field | Value | | ||
| |------------|----------------------------------| | ||
| | Service | The service you just created, `HttpBin` | | ||
| | Name | `TestService` | | ||
| | Protocols | `http, https` | | ||
| | Method(s) | `GET` | | ||
| | Path(s) | `/test-service` | | ||
|
|
||
| Once populated, click **Create** to create the route. After this, you’ll see your new routes viewing page. With the endpoint creation complete, we can now move on to testing it to ensure it is configured correctly. | ||
|
|
||
| ### Testing the Endpoint | ||
|
|
||
| To test your newly created endpoint, you’ll want to use a tool like [Postman](https://www.postman.com/) or [Insomnia](https://insomnia.rest/). Alternatively, you could also just use a browser at this point too. In your tool, add your endpoint URL which will look like `{KONG_URL}:PORT/test-service/` and send a GET request. If you are running Kong in Docker and have set up the endpoint as shown above, your URL will look like `localhost:8000/test-service/`. | ||
|
|
||
| After the request has been sent, you should see a `200 OK` response as well as a response body containing the HttpBin contents (essentially a webpage). With our endpoint working, now let’s move on to securing it with an API key. | ||
|
|
||
| ## Configure Gateway Authentication | ||
|
|
||
| ### Adding Key Auth to All Endpoints | ||
|
|
||
| Since the Developer Portal generates API keys, is you must add and enable the **Key-Auth** plugin to our Kong endpoint. For simplicity, you can enable this plugin globally. If only you want to only apply **Key-Auth** to specific/monetized routes, you can do that as well. | ||
|
|
||
| In the Kong Manager Dashboard, you can add the plugin by clicking **Plugins** in the left-side menu, under the **API Gateway** section. On the **Plugins** page, you’ll click the **New Plugin** button to add a new plugin. On the **Add New Plugin** screen, you’ll find the **Key-Authentication** plugin by scrolling or searching, once found, click **Enable**. | ||
|
|
||
| On the **Create new key-auth plugin** screen, you’ll want to make sure that the **This plugin is Enabled** toggle is set to `on`, the **Global** radio button is selected, and that **Config.Key Names** field is set to `apikey`. By setting this to `apikey` we can pass a field of the same name in the header and include our API key as the value. | ||
|
|
||
| Lastly, to save our plugin configuration, scroll down to the bottom of the screen and click **Create**. Now, our endpoint will be secured by the kay-auth plugin. To test it out, resend the request from earlier and you should get a `401 Unauthorized` response, and a message body stating `No API key found in request`. If you are not getting this response, please refer to the [Kong documentation for key-auth](https://docs.konghq.com/hub/kong-inc/key-auth/). | ||
|
|
||
| ## Configure the Developer Portal | ||
|
|
||
| ### Configuring the .env File | ||
|
|
||
| In the `my-dev-portal-api` project, for the `KONG_URL`, you'll need to add in the URL of your Kong instance. Specifically the Kong admin API URL/port, not the gateway URL/port where traffic is proxied. If you’re running a local instance of Kong, by default this will be running on `http://localhost:8001`. If this is the case, you can leave the value as is. If it is different or running remotely, you can change the value to point to the correct URL/port. | ||
|
|
||
| ### Connecting Kong to Moesif | ||
|
|
||
| The Moesif-Kong plugin makes it easy to get API call analytics funneled into Moesif. For instructions on how to do this, you can reference [our integration documentation](https://docs.konghq.com/hub/moesif/kong-plugin-moesif/) or a more in-depth step-by-step approach in [our integration guide](https://www.moesif.com/docs/guides/guide-kong-gateway-integration/). | ||
|
|
||
| Once the Moesif-Kong integration and **key-auth** is been enabled, you should begin to see some API call metrics flowing into Moesif. You may also want to ensure that API calls are being blocked by the **key-auth** plugin in Kong for unauthenticated calls. When unauthorized calls are sent to Kong, the `401 Unauthorized` responses should also show up in Moesif. | ||
|
|
||
| ## Testing the Developer Portal | ||
|
|
||
| Once the Developer portal is configured, testing out all of the moving parts of the Developer Portal is crucial. Doing this ensures that everything is working as intended. See our detailed testing process [here](https://www.moesif.com/docs/developer-portal/using-the-portal/). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,106 @@ | ||
| # Configuring Kong Konnect | ||
|
|
||
| ## Setup the Gateway | ||
|
|
||
| The Moesif Developer Portal can be used with a running instance of Kong. To integrate Moesif and Kong, you can follow our guide that covers [integrating Moesif and Kong in detail](https://www.moesif.com/docs/guides/guide-kong-gateway-integration/). Alternatively, you can also check out [our integration documentation for Kong](https://www.moesif.com/docs/server-integration/kong-api-gateway/) if you’re already an experienced Kong user. Once you have the integration set, you’ll be able to complete the rest of the Kong setup for the Developer Portal. | ||
|
|
||
| ## Configure the Gateway | ||
|
|
||
| ### Creating an Endpoint in Kong Manager | ||
|
|
||
| In order to use the developer portal to monetize your APIs, you'll require an endpoint in Kong. If you already have an endpoint created, you can use this existing endpoint. | ||
|
|
||
| If you are using Kong Manager, you can create the endpoint by clicking **Services** in the left-side menu, under the **API Gateway** section. On the **Services** page, click the **New Service** button in the top-right corner to add a new service. | ||
|
|
||
| On the **Create Service** page, You will need to fill out the **Name** and, after selecting the **Add using URL** option, the **URL** field. For this example, you can fill them out with the following values: | ||
|
|
||
| | Field | Value | | ||
| |-----------|---------------------------| | ||
| | Name | `HttpBin` | | ||
| | URL | `https://www.httpbin.org` | | ||
|
|
||
| Once populated, click **Create** to create the service. After this, you’ll see your new services viewing page. | ||
|
|
||
| Next, we will create a route that will expose this service. To do this, click on **Routes** in the left-side menu, which is also under the **API Gateway** section. | ||
|
|
||
| On the **Routes** page, click on the **Create Route** button in the top-right corner of the screen to add the new route. On the **Create Route** screen, you’ll have a few values to fill out including the **Service, Name**, **Protocols**, **Method(s)**, and **Path(s)** fields on the screen. For this example, you can fill out these fields with the following values: | ||
|
|
||
| | Field | Value | | ||
| |------------|----------------------------------| | ||
| | Service | The service you just created, `HttpBin` | | ||
| | Name | `TestService` | | ||
| | Protocols | `http, https` | | ||
| | Method(s) | `GET` | | ||
| | Path(s) | `/test-service` | | ||
|
|
||
| Once populated, click **Create** to create the route. After this, you’ll see your new routes viewing page. With the endpoint creation complete, we can now move on to testing it to ensure it is configured correctly. | ||
|
|
||
| ### Testing the Endpoint | ||
|
|
||
| To test your newly created endpoint, you’ll want to use a tool like [Postman](https://www.postman.com/) or [Insomnia](https://insomnia.rest/). Alternatively, you could also just use a browser at this point too. In your tool, add your endpoint URL which will look like `{KONG_URL}:PORT/test-service/` and send a GET request. If you are running Kong in Docker and have set up the endpoint as shown above, your URL will look like `localhost:8000/test-service/`. | ||
|
|
||
| After the request has been sent, you should see a `200 OK` response as well as a response body containing the HttpBin contents (essentially a webpage). With our endpoint working, now let’s move on to securing it with an API key. | ||
|
|
||
| ## Configure Gateway Authentication | ||
|
|
||
| ### Adding Key Auth to All Endpoints | ||
|
|
||
| Since the Developer Portal generates API keys, is you must add and enable the **Key-Auth** plugin to our Kong endpoint. For simplicity, you can enable this plugin globally. If only you want to only apply **Key-Auth** to specific/monetized routes, you can do that as well. | ||
|
|
||
| In the Kong Manager Dashboard, you can add the plugin by clicking **Plugins** in the left-side menu, under the **API Gateway** section. On the **Plugins** page, you’ll click the **New Plugin** button to add a new plugin. On the **Add New Plugin** screen, you’ll find the **Key-Authentication** plugin by scrolling or searching, once found, click **Enable**. | ||
|
|
||
| On the **Create new key-auth plugin** screen, you’ll want to make sure that the **This plugin is Enabled** toggle is set to `on`, the **Global** radio button is selected, and that **Config.Key Names** field is set to `apikey`. By setting this to `apikey` we can pass a field of the same name in the header and include our API key as the value. | ||
|
|
||
| Lastly, to save our plugin configuration, scroll down to the bottom of the screen and click **Create**. Now, our endpoint will be secured by the kay-auth plugin. To test it out, resend the request from earlier and you should get a `401 Unauthorized` response, and a message body stating `No API key found in request`. If you are not getting this response, please refer to the [Kong documentation for key-auth](https://docs.konghq.com/hub/kong-inc/key-auth/). | ||
|
|
||
| ## Configure the Developer Portal | ||
|
|
||
| ### Configuring the .env File | ||
|
|
||
| In the `my-dev-portal-api` project, for the `KONG_URL`, you'll need to add in the URL of your Kong instance. Specifically the Kong admin API URL/port, not the gateway URL/port where traffic is proxied. If you’re running a local instance of Kong, by default this will be running on `http://localhost:8001`. If this is the case, you can leave the value as is. If it is different or running remotely, you can change the value to point to the correct URL/port. | ||
|
|
||
| ### Kong Konnect | ||
|
|
||
| For Kong Konnect, the setup also requires you to add a few additional environment variables to the `my-dev-portal-api/.env` file. You'll want to add in the following key-values to the file: | ||
|
|
||
| ``` conf | ||
| KONNECT_API_URL="https://us.api.konghq.com" | ||
| KONNECT_API_VERSION="v2" | ||
| KONNECT_RUNTIME_GROUP_NAME="default" | ||
| KONNECT_PAT="" | ||
| ``` | ||
|
|
||
| for the `KONNECT_API_URL` and `KONNECT_API_VERSION` values, you'll want to log into your Kong Konnect control plane and retrieve this. You can get this value by going to the **Gateway Manager** screen and selecting your control plane. In the next screen, you can grab the **Admin API** value (located in near the top of the screen) and truncate anything we don't need. | ||
|
|
||
| The raw value will look like this: `https://us.api.konghq.com/v2/control-planes/123-asd-etc` | ||
|
|
||
| From this, we can populate our values like so: | ||
|
|
||
| ``` conf | ||
| KONNECT_API_URL="https://us.api.konghq.com" | ||
| KONNECT_API_VERSION="v2" | ||
| ``` | ||
|
|
||
| For the `KONNECT_RUNTIME_GROUP_NAME`, you'll use your **Control Plane** name. By default, this will be fittingly named `default`. | ||
|
|
||
| ``` conf | ||
| KONNECT_RUNTIME_GROUP_NAME="default" | ||
| ``` | ||
|
|
||
| Lastly, we will generate a Konnect Personal Access Token. This can be done through the Konnect UI by going to your initials in the top-right of the screen and from the dropdown, selecting **Personal Access Tokens**. | ||
|
|
||
| From here, click **Generate Token**, give the token a **Name** and **Expiration**, then click **Generate**. Paste the returned value into the `KONNECT_PAT` value. | ||
|
|
||
| ```conf | ||
| KONNECT_PAT="kpat_FIZqQxICG6aEpA10nQ1TesTtEStTEST" | ||
| ``` | ||
|
|
||
| ### Connecting Kong to Moesif | ||
|
|
||
| The Moesif-Kong plugin makes it easy to get API call analytics funneled into Moesif. For instructions on how to do this, you can reference [our integration documentation](https://docs.konghq.com/hub/moesif/kong-plugin-moesif/) or a more in-depth step-by-step approach in [our integration guide](https://www.moesif.com/docs/guides/guide-kong-gateway-integration/). | ||
|
|
||
| Once the Moesif-Kong integration and **key-auth** is been enabled, you should begin to see some API call metrics flowing into Moesif. You may also want to ensure that API calls are being blocked by the **key-auth** plugin in Kong for unauthenticated calls. When unauthorized calls are sent to Kong, the `401 Unauthorized` responses should also show up in Moesif. | ||
|
|
||
| ## Testing the Developer Portal | ||
|
|
||
| Once the Developer portal is configured, testing out all of the moving parts of the Developer Portal is crucial. Doing this ensures that everything is working as intended. See our detailed testing process [here](https://www.moesif.com/docs/developer-portal/using-the-portal/). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,78 @@ | ||
| # Configuring Tyk API Gateway | ||
|
|
||
| ## Setup the Gateway | ||
|
|
||
| The Moesif Developer Portal can be used with a running instance of Tyk API Gateway. To integrate Moesif and Tyk, you can follow our guide that covers [integrating Moesif and Tyk in detail](https://www.moesif.com/docs/guides/integrating-api-analytics-with-tyk-api-gateway/). Alternatively, you can also check out [our integration documentation for Tyk](https://www.moesif.com/docs/server-integration/tyk-api-gateway/) if you’re already an experienced Tyk user. Once you have the integration set, you’ll be ready to move to the next step in the Moesif Developer Portal setup process. | ||
|
|
||
| ## Configure the Gateway | ||
|
|
||
| ### Creating an Endpoint in Tyk Dashboard | ||
|
|
||
| For the Moesif Developer Portal to help you monetize your APIs, you'll require an endpoint in Tyk. If you already have an endpoint created, feel free to skip ahead to the next step in the guide. If you need to create an endpoint and are using the Tyk Dashboard, you can create the endpoint by following these steps: | ||
|
|
||
| **Log in to Tyk Dashboard:** | ||
| If you already have an account, log in to the Tyk Dashboard. If not, sign up for an account to get started. | ||
|
|
||
| **Create a New API:** | ||
|
|
||
| - Navigate to the dashboard's main page. | ||
| - Click on the **APIs** section, located in the main navigation menu. | ||
| - Click the **Add New API** button to begin the API creation process. | ||
|
|
||
| **API Details:** | ||
|
|
||
| - Enter a suitable **API Name**, such as `TestService`. | ||
| - Under **Type**, select **HTTP**. | ||
| - Fill in the **Upstream URL** field with the URL of the service you want to expose. For this example, use `http://www.httpbin.org`. | ||
|
|
||
| Select **+ Configure API** to explore some more advanced configuration settings. | ||
|
|
||
| **API Configuration:** | ||
|
|
||
| - Under **Listen path**, set the listen path to whatever you would like, we will be setting it to **/test-service/**. Unselect **strip the listen path** | ||
| - Choose whether to enable SSL/TLS encryption for the API in the **Enable SSL/TLS** field. | ||
| - Specify supported protocols in the **API Protocol** field, such as `http, https`. | ||
| - Set allowed HTTP methods in the **Allowed HTTP Methods** field. Choose `GET` for this case. | ||
| - Under **Authentication**, we will want to set the **Authentication Mode** to **Authentication Token**. Under **Authentication Token > Auth Key Header Name**, type **Authorization**. If you would like to test your endpoint without any authentication you can set this to **Open (Keyless)**. This is assumed in the next testing step. | ||
|
|
||
| **Save Changes:** | ||
|
|
||
| - After completing the necessary fields and configuring API settings, save the changes by clicking the **Save** button. | ||
|
|
||
| ### Testing the Endpoint | ||
|
|
||
| To test your newly created endpoint, you’ll want to use a tool like [Postman](https://www.postman.com/) or [Insomnia](https://insomnia.rest/). Alternatively, you could also just use a browser. In your tool, add your endpoint URL, which will look like `{TYK_URL}:PORT/test-service/`, and send a `GET` request. | ||
|
|
||
| After the request has been sent, you should see a `200 OK` response as well as a response body containing the HttpBin contents. | ||
|
|
||
| ## Configure Gateway Authentication | ||
|
|
||
| ### Adding Authentication to Your Endpoint | ||
|
|
||
| Ensure that you have set the **Authentication Mode** to **Authentication Token** within your API configuration for your endpoint. Under **Authentication Token > Auth Key Header Name**, type **Authorization**. | ||
|
|
||
| ## Configure the Developer Portal | ||
|
|
||
| ### Configuring the .env File | ||
|
|
||
| In the Developer Portal code, there are a few environment variables that you will need to populate for Tyk. Below are the details on how to find and populate these variables in the `my-developer-portal-api/.env` file. | ||
|
|
||
| #### Tyk Gateway | ||
|
|
||
| For the `TYK_GATEWAY_URL`, If you’re running a local instance of Tyk, by default this should be running on `http://localhost:8080`. If this is the case, you can leave the value as is. If it is different or running remotely, you can change the value to point to your Tyk gateway. | ||
|
|
||
| #### Tyk Gateway Secret | ||
|
|
||
| This would also be a good time to grab your `TYK_GATEWAY_SECRET_KEY`. If running in docker, your `TYK_GATEWAY_SECRET_KEY` can be found in the `tyk.conf` file in the Gateway container under the `"secret"` variable. | ||
|
|
||
| ### Connecting Tyk to Moesif | ||
|
|
||
| Now that we have our endpoints in Tyk set up and our base developer portal code pulled down, we can start to get analytics flowing into Moesif from Tyk. For instructions on how to integrate Tyk and Moesif, you can reference [our integration documentation](https://www.moesif.com/docs/server-integration/tyk-api-gateway/) or a more in-depth step-by-step approach in [our integration guide](https://www.moesif.com/docs/guides/integrating-api-analytics-with-tyk-api-gateway/). | ||
|
|
||
| ### Tyk Master Key Creation | ||
|
|
||
| For the developer portal, an additional step is required within the Tyk configuration. In the `tyk.conf` file, we also need to set `allow_master_keys` to `true`. This allows us to automate authentication key creation via the Tyk API. | ||
|
|
||
| ## Testing the Developer Portal | ||
|
|
||
| Once the Developer portal is configured, testing out all of the moving parts of the Developer Portal is crucial. Doing this ensures that everything is working as intended. See our detailed testing process [here](https://www.moesif.com/docs/developer-portal/using-the-portal/). |