5 minutes to secure an API with the Gravitee.io’s stack

As you may already know, Gravitee.io API Platform is composed by different and independent modules: API Management, Access Management and Alert Engine (included as part of Gravitee.io Enterprise API Platform).

In this post, we will see how to easily and quickly secure a third party API using Gravitee.io API Management (APIM) and Gravitee.io Access Management (AM).

Note that this post is based on the V3 of Gravitee.io’s stack which is still under intensive development.

Requirements

For this post we are assuming that you already have docker up and running and docker-compose installed.

Type the following command to start the Gravitee.io API Platform:

$ curl -L http://bit.ly/graviteeio-platform | bash -s -- --version=nightly

You’ll also need to install newman command.

Using NPM:

$ npm install -g newman

Using Homebrew:

$ brew install newman

Newman is a command-line collection runner for Postman. It allows you to effortlessly run and test a Postman collection directly from the command-line. It is built with extensibility in mind so that you can easily integrate it with your continuous integration servers and build systems.
More details here.

Pet Store API

For simplicity, we will rely on the already existing Pet Store API maintained by the Swagger team: https://petstore.swagger.io/v2.

Basically, the Pet Store API allows to list or create pets and do some other stuffs (see the swagger api documentation for more details). As you can see, this api is freely accessible and you can create or delete any pet you want.

Our final objective is to expose the Pet Store API through Gravitee.io APIM and disallow all write accesses by default using a Keyless plan and an RBAC policy. We’ll also see how to unlock all features by providing an OAuth2 plan relying on Gravitee.io AM.

How-to secure Pet Store API

Want to get more information about all steps ? Have a look below.
Want the short story ? You can directly run the following command and get a complete secured API in few seconds:

$ newman run -k \
    --global-var RANDOM_STRING=$RANDOM \
    -e http://bit.ly/graviteeio-local-dc-env \
    --export-globals /tmp/global.json \
    --export-environment /tmp/env.json \
    http://bit.ly/graviteeio-5-minutes-to-secure-an-api-postman

API declaration

This is the easy part where we’ll declare an API and create a simple keyless plan named ‘Freemium’. Then, we will create a policy to restrict PUT/POST/DELETE methods only to users having the ‘writer’ role.

The following figure illustrates what we will create and how anonymous consumer will be able to invoke the Pet Store API.

Pet Store API — Keyless Plan

You can run the following command in order to declare the Pet Store API and define a keyless plan on it:

$ newman run -k \
    --global-var RANDOM_STRING=$RANDOM \
    --folder "Import Pet Store API definition" \
    --folder "Create Freemium Plan" \
    --folder "Publish Freemium Plan" \
    --folder "Start Pet Store API" \
    -e http://bit.ly/graviteeio-local-dc-env \
    --export-globals /tmp/global.json \
    --export-environment /tmp/env.json \
    http://bit.ly/graviteeio-5-minutes-to-secure-an-api-postman

You should now see a new API in the Gravitee.io APIM Portal. This API should have a Freemium plan attached to and be fully working.

APIM — Freemium plan

Let’s now verify that our API is effectively accessible doing some checks:

• Create a new pet should be forbidden in Freemium plan
• Get a pet by id should return either a 200 Ok either a 404 Not Found if the pet does not exists

$ newman run -k \
    --folder "Post a new pet in free plan mode" \
    --folder "Get a pet in free plan mode" \
    -g /tmp/global.json \
    -e /tmp/env.json \
    --export-globals /tmp/global.json \
    --export-environment /tmp/env.json \
    http://bit.ly/graviteeio-5-minutes-to-secure-an-api-postman

Anonymous Consumption Tests

Securing with OAuth2

For now, we only have a free plan allowing to anonymous users to consume the Pet Store API. Thanks to our RBAC policy, all sensitive routes require a ‘writer’ role.

Let’s go deeper and secure the Pet Store API with OAuth2 using Gravitee Access Management. We first need to declare few things on the Access Management side before creating the OAuth2 plan on the Api Management side:

• Declare a security domain named ‘GraviteeShowcases’
• Define a new ‘writer’ scope
• Declare ‘Gravitee APIM’ and ‘Consumer’ applications

Access Management Domain And Applications

Launch the following command to run each AM step:

$ newman run -k \
    --folder "Login to Gravitee AM" \
    --folder "Create Gravitee Showcase security domain" \
    --folder "Create writer scope in Gravitee Showcase security domain" \
    --folder "Enable Gravitee Showcase security domain" \
    --folder "Create Gravitee APIM application in AM" \
    --folder "Create consumer application in AM" \
    --folder "Configure consumer application in AM" \
    -g /tmp/global.json \
    -e /tmp/env.json \
    --export-globals /tmp/global.json \
    --export-environment /tmp/env.json \
    http://bit.ly/graviteeio-5-minutes-to-secure-an-api-postman

AM — Applications

AM — Writer Scope

Now that everything is ready on the AM side, we can create an OAuth2 plan on the APIM side. Here is an overview of what we will declare in Gravitee APIM and how the different third parties are interacting alltogether.

Pet Store API — OAuth2 Plan

You can launch the following command to create the OAuth2 plan and a consumer application to subscribe to:

$ newman run -k \
    --folder "Create Authorization Server Resource on Pet Store API" \
    --folder "Create Oauth2 Plan" \
    --folder "Publish Oauth2 Plan" \
    --folder "Deploy Pet Store API" \
    --folder "Create consumer application in APIM" \
    --folder "Subscribe to Oauth2 plan of the Pet Store API" \
    --folder "Accept Oauth2 subscription" \
    -g /tmp/global.json \
    -e /tmp/env.json \
    --export-globals /tmp/global.json \
    --export-environment /tmp/env.json \
    http://bit.ly/graviteeio-5-minutes-to-secure-an-api-postman

You should now have a new OAuth2 plan attached to the Pet Store API and have an accepted subscription on it.

APIM — OAuth2 Plan

APIM — OAuth2 Subscription

Let’s try to consume the API using OAuth2 plan:

$ newman run -k \
    --folder "Get consumer application access token" \
    --folder "Post a new pet in Oauth2 plan mode" \
    --folder "Get a pet in Oauth2 plan mode" \
    -g /tmp/global.json \
    -e /tmp/env.json \
    --export-globals /tmp/global.json \
    --export-environment /tmp/env.json \
    http://bit.ly/graviteeio-5-minutes-to-secure-an-api-postman

We can also check that Freemium plan is still working as expected:

$ newman run -k \
    --folder "Post a new pet in free plan mode" \
    --folder "Get a pet in free plan mode" \
    -g /tmp/global.json \
    -e /tmp/env.json \
    --export-globals /tmp/global.json \
    --export-environment /tmp/env.json \
    http://bit.ly/graviteeio-5-minutes-to-secure-an-api-postman

That’s all !

Next post we will show you how to auto-magically declare consumer application in Gravitee.io AM when consumer declares its application from Gravitee.io APIM thanks to OpenID Connect Dynamic Client Registration