Secure REST API application using Gluu Gateway and OAuth plugins
By: Gluu Federation
Tags: Secure Rest Api, Kong, Oauth2, Oauth

The request hits Gluu Gateway first — it is the Internet facing endpoint.

You need to send the access token in the Authorization header — just like you would do for any OAuth protected API.

The GG OAuth plugin introspects the token (or validates the signature if it’s a JWT). If the token is not active, GG returns 401 — Unauthorized.

Before proxying the request to the upstream API endpoint, GG checks to make sure the access token has the required scopes.

If the required scopes are present, GG proxies the request, gets a response, which is returned to the Client. If the required scopes are not present, GG returns 403–Forbidden.

Voila! OAuth access management without a single line of code! All you need to do it to install Gluu Gateway, map your OAuth client to a Kong consumer, and register the upstream API. Following is a more detailed description of how to do this.

Prerequisites

Gluu Server

This is our OAuth Authorization Server. The Client software, or Relying Party (“RP”) will get an access token from the Gluu Server /token endpoint — requesting the required scopes. So the first step is to install a Gluu Server, if you don’t already have one. There are a number of ways to do this — you can use one of the Linux packages (Ubuntu, Centos, Red Hat or Debian), you can use Docker, or you can even use Kubernetes. Probably the simplest way is to use the Linux packages, which install all the components of the Gluu Server in a simple file system container (in /opt/gluu-server). This is normally a three step process: install the package, start the gluu server, run setup. But for detailed instructions, see the Installation Guide for the current version in the official Gluu Server documentation.

Gluu Gateway (GG)

In OAuth jargon, GG is our Resource Server (“RS”). For example, it publishes the endpoints that the Client will call, presenting the access token. Gluu Gateway also has a number of distributions. See the docs for Gluu Gateway to pick the distribution that makes the most sense for you. Note: you probably want to install GG on a different VM then your Gluu Server. If you do install GG on the same VM, I would suggest setting up a different virtual ethernet interface and making sure that the GG processes bind to this IP. This is a little out of scope of this howto article… so the easiest things is to probably just use a different VM!

After installation of GG you will get the following components:

Kong Community Edition 2.x: Kong Provides the core API gateway functionality. This is the software which handles the request, applies the security plugins , and enforces the security policy per the plugin configuration. It provides two endpoints: Admin Endpoint and Proxy Endpoint . The Admin Endpoint is used to configure upstream apps, services, routes, consumers, and plugins. The Proxy Endpoint is the final endpoint which accept request from clients — in our case, the angular application calling this endpoint for protected resources.

GG UI : You can configure your backend API, routes, consumer, and plugins in the Admin GG UI Panel

: You can configure your backend API, routes, consumer, and plugins in the Admin GG UI Panel GG Plugins : Gluu Gateway provides custom plugins to enable access management policy enforcement using OAuth, UMA, OpenID Connect and Open Policy Agent (OPA). Check here for the list.

: Gluu Gateway provides custom plugins to enable access management policy enforcement using OAuth, UMA, OpenID Connect and Open Policy Agent (OPA). Check here for the list. OXD: oxd is a client middleware. GG doesn’t obtain a token directly. It calls an oxd API, which does the heavy lifting. This keeps the code simple in the Kong plugin. Implementing asymetric client authentication in Lua would have been a lot of work for the GG developers. oxd is a certified OpenID Client, so calling one method, like “getToken”, was a lot easier. Learn more about oxd here.

Backend API(Protected Resources)

Also known as Protected resources, Upstream App, target or backend API . For this post, I am using a demo Node.js application available here. This is the backend application which is called by the frontend software client.

Angular Client

I am using an Angular Client to access protected resources. This is the frontend application which sends a request to Gluu Gateway. Check out Single Page Application SSO With Gluu CE using AppAuth JS for configuration and implementation details.

Consumer OP Client

This is the same client that I am using in the Angular App. I call this the Consumer OP Client . You will need to register your clients client_id in GG in order to grant them access to protected resources.

Configuration

There are 4 main steps:

Configure your Backend API Application into Gluu Gateway Service Configure Kong Gateway Routes Add OAuth Security Configure Consumer OP Client

1. Configure your Backend API Application into Gluu Gateway Service

We need to register the Backend API application with Gluu Gateway’s Service Kong entity. After authentication, GG uses this configuration to request and get a response from the Backend API.

My API backend is running on http://localhost:3000 so I configured service for this. You will need to configure service based on your API.

Follow these step to add a Service using GG UI :

Click SERVICES on the left panel

on the left panel Click the + ADD NEW SERVICE button

Fill in the following boxes:

Name: test-app (you can use any name here)

(you can use any name here) URL: http://localhost:3000

2. Configure Kong Gateway Routes

The Routes is specifically used by the GG Kong to recognize and accept the request. It is a child entity that we need to add to the Service object.

Follow these steps to add a Route using GG UI :

Click SERVICES on the left panel

on the left panel Click test-app service, which we created on the above step

service, which we created on the above step Click Routes

Click + ADD ROUTE button

Fill in the following boxes and click enter:

Name: test-api (you can use any name here)

(you can use any name here) Hosts: <your-server-host> (this is the host of the Gluu Gateway proxy, which will be requested by the angular app)

I have GG on my server so I will use gluu.local.org as an example. You will need to replace this with your host. Check the Gluu Gateway docs for more routing capabilities.

3. Add OAuth Security

There are many plugins available in GG which provide security. To make it simple, we will configure just one for this example.

Click ROUTES on the left panel

on the left panel Click route id/name with gluu.local.org as the host

with as the host Click Plugins

Click + ADD PLUGIN button

button You will see Gluu OAuth Auth and PEP title and + icon

Now you will see below the form and from here:

Set Disable to OAUTH PEP Scope expression configuration

to Set blank to OXD Id , Client Id , and Client Secret (GG UI will create one separate client for plugin usage)

, , and (GG UI will create one separate client for plugin usage) Leave Headers as is or configure per your requirements

as is or configure per your requirements Click ADD Plugin button

GG OAuth plugin configuration Section

Tip: If you are a frontend developer, you know the CORS origin problem and preflight request problem. This problem occurs when you are calling APIs from a browser different from its origin(domain), in which case you need to add the Cors plugin, which by default comes with Kong CE. Check here for the Cors plugin configuration.

4. Configure Consumer OP Client

Follow these steps to configure the consumer using GG UI:

Click CONSUMERS on the left panel in GG UI

on the left panel in GG UI Click + CREATE CONSUMER button

button Add client_id in the Gluu Client Id field. (this is the same client that you are using in the Angular App)

Now, we need to register this client client_id into Gluu Gateway Consumer to allow them access to protected resources.

Configuration is finished here. Now you will need to call the protected API using GG Kong Proxy Endpoint.

Request to Proxy

GG Kong exposes the proxy endpoint on the port :443 so you need to call the API in your angular app and pass access_token in the authorization header.

As per my configuration, I am calling my proxy endpoint https://gluu.local.org:443/posts with access_token .

Below is the angular code to call GG Proxy Endpoint:

this.http.get(

'https://gluu.local.org:443/posts',

{headers: {authorization: 'Bearer ' + this.accessToken}}

).subscribe((response) => {

this.images = response;

}, (error) => {

console.log(error);

});

If all is OK, you will get a response from the GG.

Conclusion

At a high level, implementing a piece of infrastructure like an API gateway makes sense when you have a lot of APIs. If you have just a few endpoints, it may be overkill. But there are advantages to this approach:

Policy enforcement is not in code — it’s in the HTTP routing infrastructure. That means you can change the required scopes without touching your code. Your backend APIs are not Internet facing You can implement other security, like limiting transaction volume (i.e. how many calls per hour, day etc can a client make). Developers don’t need to know anything about OAuth — they can just code the functionality they need, and focus on fine grain authorization.

So this approach may not be for everyone. But GG is a great tool to have in your back pocket when the right use case presents itself.

Thank you!