Using Gravitee policies to secure your APIs

December 18, 2019 4-minute read

Gravitee • OIDC • OAuth • JWKS • API Management • Security

Gravitee?

Spoiler: I have been keen on Gravitee since its first days, back in 2015…

Gravitee Source, the company behind Gravitee, actively work on two open-source products beside their consulting activities.

These products are open, simple, efficient, scalable and made for one single purpose.

Gravitee API Manager is the right tool for helping companies to manage and expose their APIs.
Gravitee Access Management is a great Authorization gateway, with OAuth 2 at its heart and OpenID Connect certified.

Presentations made, let’s dive into Gravitee APIM (API Manager) policies!

APIM policies and security

Available policies are numerous out-of-the-box. And the combination of them give you a very large number of possibilities to play around resources of your API.

In this article, I’ll focus on policies likely to help you in securing an API.

I will try to categorize them but it’s just to make it more readable.

Input validation

Validate Request - mostly designed to validate HTTP headers and query parameters. It can run a set of rules on requests and responses.
Rules can be applied on headers, body or parameters. They can be REGEX patterns or predefined patterns, like MAX value, MIN value, NOT NULL value, MAIL value, etc.

More coming soon: dynamic input validation based on a Swagger / OpenAPI!

Transform Headers - can remove, whitelist, update or add a set of headers.
JSON validation - check if a JSON payload is conform to a JSON-schema.
More information can be found here: https://docs.gravitee.io/apim_policies_json_validation.html

Client requests limitation

Quota - Apply a quota to a Client according to the plan it was attributed (and potentially how much he paid such usage 😉).
Example: 1 000 calls per day
Rate limit - Prevents flooding a backend.
Example: 100 calls / sec
IP filtering - whitelist or blacklist client IPs. Can use a set of discrete IPs and / or CIDRs. Can apply to every IP present in the X-Forwarded-For header or not.
Request content limit - Forbids too large payloads.

Authentication & Authorization

OpenID Connect - UserInfo - Fetch the user claims from the referenced AS (Authorization Server). So, it calls the UserInfo endpoint with the provided access_token and, optionally, put the response payload in the request context for further usage.
If you want to first validate the signature of the token, then place a JSON Web Tokens policy before.
OAuth2 - Validates an OAuth token by calling the introspection endpoint of the AS and, optionally, checks scopes. Also, it can extract the AS response claims and pass them to the next policy or upstream server.
JSON Web Tokens - Checks the signature of a JWT, picked from the Authorization header. The signature can be RSA or HMAC. If RSA, the policy can lookup for some PEM locally/internally or fetch the public key from an exposed JWKS. Claims are extracted for further usage if needed. Expiration date is checked.
Generate JWT - Generates a JWT that, for example, attests that the request went through the API platform and thus can be trusted by backends.
This new JWT can be added to the request via other policies (Transform Headers for example) before reaching any backend.
Resource filtering - Filters a set a API resources so that they are not accessible to the Client. So, it can whitelist or blacklist multiple set of resource paths. Can use regex.

Of course, you had better use a combination of them to protect your endpoints.

Real world use-cases

1. First example, you may want to first check the authorization of an application before validating the request payload.
So you would drag & drop policies in that order, because order matters:

2. Another example, you may want to check the identity of an end-user before letting him go through the gateway. Once validated, you can pick some claims from the original id_token and wrap them into another JWT, that your API gateway is the only one able to sign.
That allows backends to delegate some security concerns, like authentication, to your API gateway layer.

3. Finally, if you want to apply some rules at a global level, it’s fine to apply them on a plan. The plan will be applied to each resource of your API, for all applications that choose that plan.

First, you might want to apply global limitations on HTTP hits:

Then, apply global policies. Here, it enforces the retrieval of user profile:

Once again, possibilities are huge!

Conclusion

I hope that helped you in your reflexions about security capabilities with an API Manager.

Enjoy Gravitee! 😉