Configuring OAuth2-secured APIs

This guide describes how to configure Gelato to connect to OAuth2-secured APIs in Kong.

We will create a sample API in Kong, secure it with OAuth2, and then configure Gelato to connect to it. The steps required vary depending on the grant type used, so there are examples below for all support grant types: client credentials, authorization code, implicit, and password. This guide assumes you are familiar with OAuth2. For more information, see the OAuth 2.0 Authorization Framework.

Steps for all Grant Types

Regardless of the grant type you support, you'll need the following set up in the Kong instance that your Gelato portal is connected to:

  • An API secured by OAuth 2,
  • A consumer that will use the API,
  • A client application belonging to that consumer.

This guide assumes you are running the most recent version of Kong, and that the Kong Admin API is accessible at http://localhost:8001.

Create the API

Our sample API will be named cats.

curl -X POST http://localhost:8001/apis \
-d "name=cats" \
-d "uris=/cats" \
-d "upstream_url=http://mockbin.org"

Create the consumer

This consumer represents the Gelato API Explorer.

curl -X POST http://localhost:8001/consumers \
-d "username=api-explorer"

Create the client application

The API Explorer will use this application to access your API.

export PORTAL_URL=<your portal URL; e.g., https://developer.mycompany.com>

curl -X POST http://localhost:8001/consumers/api-explorer/oauth2/ \
-d "name=Hello World App" \
-d "redirect_uri=$PORTAL_URL/oauth-callback"

Kong returns a response describing the new client application. Make a note of the client_id and client_secret in the response for configuring authentication in Gelato later.

Example 1: Client Credentials Grant

Secure your API

Secure the Cats API. This example sets up the client credentials grant type and requires the user to request at least one of the three allowed scopes.

curl -X POST http://localhost:8001/apis/cats/plugins/ \
-d "name=oauth2" \
-d "config.scopes=email, phone, address" \
-d "config.mandatory_scope=true" \
-d "config.enable_client_credentials=true" \
-d "config.accept_http_if_already_terminated=true"

Note: See the OAuth2 plugin documentation for a complete listing of configuration options.

Configure API Authentication in Gelato

This section assumes that you have already created an API Doc and a version for it in Gelato.

Set the Base URI for this version to point to your Kong-managed API. Replace test.com with your API domain.

Api Version

Select the cats API that you created above.

Api Kong Integration

Gelato reads much of your OAuth2 configuration from Kong; however there are a few settings you must adjust. After the initial save, return to the Edit API Version page to make any customizations you need. Be sure to refresh the page before making your changes.

Note that changes you make here are only saved in Gelato for use by the API Explorer -- they do not update the configuration of your Kong OAuth2 plugin.

Authentication Client Creds

  • Grant Type: This value is read from Kong. Do not adjust.
  • OAuth Host: For the client credentials grant, you may leave this blank.
  • Token Path: Defaults to /oauth2/token. In our example, only the Cats API is secured by OAuth2, so include the cats prefix in your Token Path.
  • Authorize Path: Not needed for the Client Credentials flow.
  • Explorer Client ID: The client ID you saved for the api-explorer consumer you created earlier.
  • Explorer Client Secret: The client secret for the api-explorer consumer.
  • Explorer Scope: This value is read from Kong. Do not adjust.

Your developers can now request access tokens and use the API Explorer to experiment with your API.

Example 2: Authorization Code Grant

Secure your API

Secure the Cats API. This example sets up the authorization code grant type and requires the user to request a scope.

curl -X POST http://localhost:8001/apis/cats/plugins/ \
-d "name=oauth2" \
-d "config.scopes=email, phone, address" \
-d "config.mandatory_scope=true" \
-d "config.enable_authorization_code=true" \
-d "config.accept_http_if_already_terminated=true"

Make a note of the provision_key in the response for use later.

Set up your Authorization Server

If you already have an authorization server, make a note of the URL for authorizing users and the URL for issuing tokens.

export AUTH_ENDPOINT=https://your.authserver.com/your-authorize-endpoint
export TOKEN_ENDPOINT=https://your.authserver.com/your-token-endpoint

If you don't have an auth server yet, you can use the Kong Sample Authorization Server by following the steps below.

Clone or download the sample app

git clone https://github.com/Mashape/kong-oauth2-hello-world

Check out the feat/kong-gelato-demo branch

git checkout feat/kong-gelato-demo

Install dependencies

npm install

Start the authorization server

Set the required environment variables:

export PROVISION_KEY=<provision key saved in prior step>
export KONG_ADMIN=<URL to Kong Admin API>
export KONG_API=<URL to your Kong Gateway>
export API_PATH="/cats"
export SCOPES="{ \
  \"email\": \"Grant permissions to read your email address\", \
  \"address\": \"Grant permissions to read your address information\", \
  \"phone\": \"Grant permissions to read your mobile phone number\" \
}"

Start the server:

node app.js

Make the authorization server publicly accessible. One popular tool for this is ngrok.

Then, set an environment variable to the authorize URL.

export AUTH_ENDPOINT=https://<sample-auth-server-domain>/authorize

Configure API Authentication in Gelato

This section assumes that you have already created an API Doc and a version for it in Gelato.

If you've added new APIs to Kong since the initial connection between Kong and Gelato, make sure to re-sync the connection via Gelato.

Set the Base URI for this version to point to your Kong-managed API. Replace test.com with your API domain.

Api Version

Select the cats API that you created above.

Api Kong Integration

Gelato reads much of your OAuth2 configuration from Kong; however there are a few settings you must adjust. After the initial save, return to the Edit API Version page to make any customizations you need. Be sure to refresh the page before making your changes.

Note that changes you make here are only saved in Gelato for use by the API Explorer -- they do not update the configuration of your Kong OAuth2 plugin.

Auth Code

  • Grant Type: This value is read from Kong. Do not adjust.
  • OAuth Host: You may leave this blank.
  • Token Path: Defaults to /oauth2/token. In our example, only the Cats API is secured by OAuth2, so include the cats prefix in your Token Path.
  • Authorize Path: Set this to the URL of your authorization endpoint ($AUTH_ENDPOINT).
  • Explorer Client ID: The client ID for the api-explorer consumer you created earlier.
  • Explorer Client Secret: The client secret for the api-explorer consumer.
  • Explorer Scope: This value is read from Kong. Do not adjust.

Your developers can now request access tokens and use the API Explorer to experiment with your API.

Example 3: Implicit Grant

Follow the same steps as for Authorization Code, but when creating the OAuth2 plugin, use the following:

curl -X POST http://localhost:8001/apis/cats/plugins/ \
-d "name=oauth2" \
-d "config.scopes=email, phone, address" \
-d "config.mandatory_scope=true" \
-d "config.enable_implicit_grant=true" \
-d "config.accept_http_if_already_terminated=true"

Example 4: Password Grant

Please note: The Kong Sample Authorization Server does not implement the password grant type. You will need to use your own authorization server for this example.

Follow the steps for Authorization Code, but when creating the OAuth2 plugin, use the following:

curl -X POST http://localhost:8001/apis/cats/plugins/ \
-d "name=oauth2" \
-d "config.scopes=email, phone, address" \
-d "config.mandatory_scope=true" \
-d "config.enable_password_grant=true" \
-d "config.accept_http_if_already_terminated=true"

Configure API Authentication in Gelato

This section assumes that you have already created an API Doc and a version for it in Gelato.

Set the Base URI for this version to point to your Kong-managed API. Replace test.com with your API domain.

Api Version

Select the cats API that you created above.

Api Kong Integration

Gelato reads much of your OAuth2 configuration from Kong; however there are a few settings you must adjust. After the initial save, return to the Edit API Version page to make any customizations you need. Be sure to refresh the page before making your changes.

Note that changes you make here are only saved in Gelato for use by the API Explorer -- they do not update the configuration of your Kong OAuth2 plugin.

Password

  • Grant Type: This value is read from Kong. Do not adjust.
  • OAuth Host: You may leave this blank.
  • Token Path: Set this to the URL of the token endpoint ($TOKEN_ENDPOINT) on your authorization server.
  • Authorize Path: The password grant does not use this field.
  • Explorer Client ID: The client ID for the api-explorer consumer you created earlier.
  • Explorer Client Secret: The client secret for the api-explorer consumer.
  • Explorer Scope: This value is read from Kong. Do not adjust.

Your developers can now request access tokens and use the API Explorer to experiment with your API.

Using Tokens with the API Explorer

Make sure your API documentation includes instructions for how to send the access token in API requests. Developers will need these instructions in order to make API requests in their applications and in the API Explorer.