plans-and-policies-101.md

description
Add layers of security and functionality to your backend resources

Plans and Policies 101

{% hint style="warning" %} This is the second section of the Quickstart Guide.

• By this point, you should already have created a Gateway API.
• Steps will be provided for both traditional proxy and message proxy Gateway APIs. {% endhint %}

Overview

The next two core Gravitee API Management (APIM) concepts we will focus on are plans and policies:

• Plan: Provides a service and access layer on top of your API that specifies access limits, subscription validation modes, and other configurations to tailor your API to a specific subset of API consumers. An API consumer always accesses an API by subscribing to one of the available plans.
• Policies: Customizable rules or logic the Gateway executes during an API transaction. Policies generally fall into the categories of security, transformation, restrictions, performance, routing, or monitoring & testing.

Plans and policies are managed by the API publisher to add different layers of security and functionality to the backend resources they own.

Plans

There are many possible API access scenarios, any of which can be difficult to encode into your backend services. Plans are a powerful way to decouple the business logic from the access control of your backend services.

In APIM, all APIs require at least one plan before they can be deployed on the Gateway. The most important part of plan configuration is selecting the security type. APIM supports the following five security types:

• Keyless (public)
• Push
• API Key
• OAuth 2.0
• JWT

APIM intelligently routes API consumers to plans based on specific criteria in the API request. APIM then uses an application-based subscription model to decide whether to accept or deny an incoming API request.

Applications and subscriptions

Plans are an access layer around APIs. An application allows an API consumer to register and agree to this plan. If the registration is approved by the API publisher, the result is a successful contract, or subscription.

To access your APIs, consumers must register an application and submit a subscription request to a published API plan. Applications act on behalf of the user to request tokens, provide user identity information, and retrieve protected resources from remote services and APIs.

API publishers can modify a subscription at any time, which includes transferring API consumers to a different plan, pausing the subscription, setting an expiration date, or permanently closing a subscription.

Keyless plan subscriptions

Because keyless plans do not require authorization, APIs with keyless plans do not require the API consumer to create an application or submit a subscription request. Deployed APIs with a keyless plan will be publicly available on the Gateway's network.

Policies

A policy modifies the behavior of the request or response handled by APIM Gateway. Policies can be considered a proxy controller, guaranteeing that a given business rule is fulfilled during request/response processing.

The request and response of an API transaction are broken up into phases. Policies can be applied to these phases in policy chains of arbitrary length.

Phases

Gateway APIs have the following phases:

• Request: For both traditional and message proxy APIs, this phase is executed before invoking the backend service. Policies can act on the headers and content of traditional proxy APIs.
• Publish: This phase occurs after the request phase and allows policies to act on each incoming message before it is sent to the backend service. This phase only applies to message proxy APIs.
• Response: For both traditional proxy and message proxy APIs, this phase is executed after invoking the backend service. Policies can act on the headers and content of traditional proxy APIs.
• Subscribe: This phase is executed after the response phase and allows policies to act on each outgoing message before it is sent to the client application. This phase only applies to message proxy APIs.

Policies are scoped to different API consumers through flows. Flows are a method to control where, and under what conditions, a group of policies act on an API transaction.

Example

Let's say you have a backend API server architected around flight data. This data is not sensitive and you want to allow anyone to easily access it. However, because the data is supplied by verified airlines, you want to limit data modifications to specific API consumers who are explicitly granted permission.

This is easily achieved with APIM and does not require any changes to the backend API server.

First, you could create two plans in APIM: A keyless plan and a JWT plan. The keyless plan does not require API consumers to create an application or submit a subscription request and allows API consumers on the Gateway's network to immediately begin sending requests through the available entrypoints.

However, you would also configure the keyless plan with a flow containing a resource filtering policy applied to the request phase. This policy would be configured to grant read access only to the backend API. All other types of API requests (e.g., POST, PUT, DELETE, etc.) would be denied.

The flow with the resource filtering policy does not apply to the JWT plan and API consumers subscribed to it could modify data associated with their airline. However, to be granted access to the JWT plan, users need to first create an application and submit a subscription request that must be approved by you, the API publisher.

---

Add a policy

Let's work through how to add a simple policy to modify the behavior of the Gateway API we created in the first part of the Quickstart Guide.

Access API

First, we need to open the API in the APIM Console. You may already have it open from the previous part of the Quickstart Guide. If not, simply head back over to the APIs homescreen and select the API you created.

APIs homescreen

• Select APIs in the sidebar
• Select the API you created in Gateway APIs 101

Policy Studio

Once you're back to your API's General Info page, go to the Policy Studio.

API General Info page

• Select Policy Studio from the inner sidebar

Creating a flow

The Policy Studio is a powerful interface for visually designing flows and applying policies to APIs. Remember, flows are a way to group policies and set conditions that determine which API requests trigger the flow.

One way to condition a flow is by plan. Every plan that is added to an API can have its own set of flows.

You should see your Default Keyless (UNSECURED) plan on the left side of the Policy Studio. Additionally, you should see Common flows. Let's add a flow to Common flows to ensure our policy applies to all consumers of our API, regardless of the plan they are subscribed to.

Adding a flow under Common flows

• Select the + icon to the right of Common flows
• Provide a name for the flow and select Create

Flow conditions

We are purposefully keeping this flow very simple. However, the conditions that trigger a flow can be fine-tuned beyond assigning the flow to a plan:

• Operator and path: Use this to trigger a flow based on the path of the API request. The condition is evaluated for every request and the flow is only triggered if it evaluates to true.
• Methods: Select the HTTP methods this flow applies to.
• Expression Language Condition: Use Gravitee's Expression Language (EL) to provide a custom condition. The condition is evaluated for every request and the flow is only triggered if it evaluates to true.

Adding a policy

Creating a flow opens up the flow editor. This screen will look different based on whether you are working with a traditional or message proxy API. Follow the instructions that match your API's proxy type:

Traditional proxy

The only phases available to traditional proxy APIs are request and response. We will be adding a policy to the response phase.

• Select the + icon in the Response phase

Message Proxy

The phases available to message proxy APIs are request, response, publish, and subscribe. The publish and subscribe phases allow the policy to be applied at the message level. We will be adding the policy to the subscribe phase.

• Select the Event messages tab in the flow editor
• Select the + icon in the Subscribe phase

{% hint style="info" %} The next steps are the same for both traditional and message proxy APIs. {% endhint %}

The previous actions will open up the policy selector. We are going to add an Assign Content policy that allows us to modify the content of the payload before it reaches the API consumer.

Add an Assign Content policy

• Click Select under the Assign content policy

Every policy allows you to provide a Description and a Trigger condition. Trigger conditions for policies are just like trigger conditions for flows, except these allow you to set independent conditions for each policy.

Additionally, every policy has configuration settings specific to it. For the Assign Content policy, we can override the payload of the response or individual message by supplying a string in the Body content input box.

Configure the Assign Content policy

• Type a string in the Body content input box
• Select Add policy to add it the flow
• Select Save in the top right of the flow editor

You should now see the Assign Content policy added to the correct phase of the flow.

Redeploy an API

After saving, you'll notice a banner appears at the top of the Console that says This API is out of sync. This means the changes you made in the Console are saved but have not yet been propagated to the Gateway.

To ensure these changes are synced to the Gateway, the API must be redeployed.

Redeploy an API

• Select Deploy API in the top right
• Select Deploy in the modal that pops up on the screen

This is an essential concept to understand. API deployment is a syncing mechanism between the Console and Gateway. Changes in the Console must be synced to the Gateway for them to have any impact on the API consumers who send requests to the Gateway.

Test your policy

Try sending the same request from the first part of the Quickstart Guide.

{% code overflow="wrap" %}

curl -X GET -i "https://<your-gateway-server>/<your-context-path>"

{% endcode %}

{% hint style="success" %} Regardless of whether it's a traditional or message proxy API, the payload of the response will be set to whatever you provided as the body content of the Assign Content policy. {% endhint %}

Add a plan

Now let's see how we can manage the plans for this API.

Manage your API's plans

From the Policy Studio, go to the Plans page.

Policy Studio

• Select Plans from the inner sidebar

From here, we can manage all the plans and subscriptions for this API. Currently, the only plan you should see is the Default Keylesss (UNSECURED) plan that was added by default when creating the API.

This plan is currently in the published state. Plans can be in one of four states: staging, published, deprecated, or closed.

Four stages of a plan

Plan stages explained

Staging: This is the first stage of a plan, when the plan is in draft mode. You can configure your plan, but it won’t be accessible to users.

Published: Once your plan is ready, you can publish it to let API consumers view and subscribe to it on the APIM Portal, then consume the API through it. A published plan can still be edited.

Deprecated (optional state): You can deprecate a plan so it won’t be available on the APIM Portal and API consumers won’t be able to subscribe to it. Existing subscriptions remain, so deprecation doesn’t impact your existing API consumers.

Closed: Once a plan is closed, all associated subscriptions are closed. This cannot be undone. API consumers subscribed to the plan won’t be able to use your API.

Let's go ahead and add API security with an API key plan:

API Plans page

• Select + Add new plan in the top right
• Select API Key from the drop-down menu

This opens the General page of the plan creation wizard. The only required configuration is to provide the plan with a name.

General page of plan creation wizard

• Provide a Name for the plan
• Scroll down to the bottom of the page and click Next

The next step is to configure the security settings specific to the plan type you selected. For our API key plan, we will just keep the defaults.

Security configuration page of plan creation wizard

• Leave the defaults and click Next

Finally, you have the option to add restriction policies directly to the plan as part of the creation process.

Restrictions page of the plan creation wizard

• Leave the defaults and click Create

This will create the plan in the Staging state. To make it available to API consumers, we need to publish it.

Publish the API key plan

• Select the publish icon to the far right of the plan
• Select Publish in the modal that pops up on the screen

This will change the API key plan's state from staging to published.

To ensure our new API key plan can't be bypassed, we need to close the keyless plan and then sync all the changes we've made to the Gateway.

Closing the keyless plan

• Select the delete icon to the far right of the keyless plan
• Confirm the delete by typing in the name of the plan and then clicking Yes, close this plan
• Sync these changes to the Gateway by clicking Deploy API in the banner

Test the plan

One more time, try sending the same request from the first part of the Quickstart Guide.

{% code overflow="wrap" %}

curl -X GET -i "https://<your-gateway-server>/<your-context-path>"

{% endcode %}

{% hint style="success" %} The request will be denied with an HTTP 401 Unauthorized error response status code. {% endhint %}

The error response confirms the keyless plan was removed and all requests are now routed to the API key plan. We will need to subscribe to the API key plan and pass the proper authorization token with each request to continue to use the API.

Next steps

You should now be starting to grasp the power, versatility, and scope of the Gravitee APIM platform.

For the final part of the Quickstart Guide, we will be diving into the Developer Portal to show how API publishers can expose and catalog their APIs, and how API consumers can create applications and subscribe to APIs in a catalog.

	Developer Portal 101		developer-portal-101.md