Secure Web Application using Gluu Gateway Multi-step OpenID Connect OAuth security

You can now secure any API or web application with zero lines of code using a free open source proxy called Gluu Gateway. As application developers, we want to focus on core functionality — not security. Putting a proxy in front of web applications or API’s to enforce security is a well-trodden path to securing content. There are many excellent proxies out there that can help you do this. Gluu Gateway has some unique features — it is the only proxy to support the User-Managed Access protocol, which is handy if you need to interact with a user post-authentication (e.g. for consent). It can handle both simple and complex requirements for authorization, making it an interesting option to help you secure your web content.

What is Gluu Gateway?

Gluu Gateway (GG) is an authentication and authorization solution for APIs and websites.

GG bundles the open-source Kong Community Edition 2.x Gateway for its core functionality and adds a GUI and custom plugins to enable access management policy enforcement using OAuth, UMA, OpenID Connect, and Open Policy Agent (“OPA”). In addition, GG supports the broader ecosystem of Kong plugins to enable API rate limiting, logging, and many other capabilities.

In this blog, I am focusing on securing a Web application. To accomplish this, I will use the Gluu Gateway OpenID connect plugin to authenticate a request using the Code Flow. One nice feature of Gluu Gateway is the ability to implement “stepped-up authentication” for a part of the site. In my example, the /payments page requires OTP authentication. Gluu ships with many built in open and third party authentications solutions, including OTP, FIDO, Duo, and even facial recognition using BioID. Check Gluu Server docs here for more details. If you need a portal to enable end users to manage their 2FA credentials, you may also want to look at the Gluu Casa component, which is now included in the Gluu Server 4.2.x Community and Cloud Native editions.

You can read more about the OpenID Connect OAuth 2.0 Overview and Security Flows for a more detailed description of the terms. If you’re an Angular guru, you may also want to check out the Single Page Application SSO With Gluu CE using AppAuth JS. If you are having an API Application then check the Secure API(backend) application using Gluu Gateway and OAuth plugins

Flow

The flow is pretty simple because you don’t need to write a single line of code. You just need to configure the plugin, add multi-step auth is done!

The user first authenticates. When trying to access the /payments page, GG will elevate the authentication, for example by requiring an OTPtoken (or FIDO, or whatever mechanism you configure, by specifying the respective acr_values param).

Below is a sequence diagram if you are the type of person who likes these kind of things:

• The request hits Gluu Gateway first — it is the Internet-facing endpoint/page.
• As per the configuration, GG will behave and proceed with the OpenID Connect Code Authentication Flow.

Pre-requisites

OpenID Provider

This is our Gluu Server — or any conformant OpenID Provider (or “OP”). If you need an OP for testing, the Gluu Server has a number of distributions. It’s easy to install — normally a three step process: install the software, start the service, run setup. But for detailed instructions, see the Gluu Server documentation.

Gluu Gateway(GG)

In OAuth jargon, GG is our Resource Server (“RS”). In OpenID jargon, it’s the Relying Party (“RP”). 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 server 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 server!

After installation of GG you will find the following components:

Kong Community Edition 2.x: Kong Provides the core API gateway functionality. This is the software that handles the request, applies the security, and enforces the security policy per the plugin configuration. It provides two endpoints: Admin Endpoint andProxy 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.

• Gluu Gateway UI: This is the Admin web interface where you can configure your backend API, routes, consumer, and plugins. Note: the admin UI just calls the Kong Admin Endpoint. So anything you can do in the UI, you can do via API’s. There is even a log in the Admin UI which tells you the equivalent curl command you could have made.
• GG Plugins: Gluu Gateway provides several plugins. Check here for list. We are only using the gluu-oauth-auth plugin for request authentication.
• OXD: OXD exposes simple, static APIs web application developers can use to implement user authentication and authorization against an OAuth 2.0 authorization server like Gluu. The Gluu Plugins call oxd API’s. This reduced the amount of protocol code in the Kong plugins.

Backend Web-App (Protected Resources)

Also known as Protected resources, Upstream App, target or backend Web App. 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.

Configuration

Gluu Server enable OTP Auth

First, add OTP stepped-up authentication by enabling the OTP ACR in the OP Server. Configure the following settings inside your Gluu Server:

1. In oxTrust, navigate to Configuration > Person Authentication Scripts
2. Enable the otp script

3. Now just confirm that it is enabled successfully by checking your OP discovery endpoint https://<your_op_server>/.well-known/openid-configuration, it should show otp in the acr_values_supported property.

Gluu Gateway configuration

we are going to register and protect the whole upstream service (the website) using gluu-openid-connect plugin and for /payments path with the OTP ACR. As a result, a request for /payments will ask for an additional OTP authentication step to access the resource.

There are 3 Steps to configure GG:

1. Configure Service
2. Configure Route
3. Configure gluu-openid-connect plugin

1. Configure Service

You need to first register your Web Application into GG as a Service. Follow these steps to add a Service using GG UI:

• Click SERVICES on left panel
• Click on + ADD NEW SERVICE button
• Fill in the following boxes:
• Name: oidc-steppedup-demo
• URL: http://localhost:4400, register as per your web application configuration. My web app is running on 4400 port.

2. Configure Route

Follow these steps to add a route:

• Click on the oidc-steppedup-demo service
• Click the + ADD ROUTE button
• Fill in the following boxes:
• Name: oidc-steppedup-demo
• Hosts: <your-server-host>, Tip: Press Enter to accept the value. This tutorial uses a server with an updated /etc/hosts file. This is the host that will be requested in the browser after configuration. If you are using live servers, register the domain host instead. The rest of the tutorial will use dev1.gluu.org as an example, replace it with your host. Check the Kong docs for more routing capabilities.

3.Configure Plugin

Follow these steps to add a route:

• Click ROUTES on the left panel
• Click on the route id/name with dev1.gluu.org as the host
• Click on Plugins
• Click on + ADD PLUGIN button
• You will see Gluu OIDC & UMA PEP title and + icon in pop-up.
• Click on the + icon and it will show the below form. Add the ACR expression as in the below screenshots.
• OTP stepped-up auth for path /payments/??
• simple_password_auth authentication for all other paths. Check here for more details about ACR expressions.

Voila! Configuration is done here. Not even a single line of code. Next, request the Kong proxy https://<your_host> in the browser. In this example, the host is https://dev1.gluu.org.

Authentication

1. Once you send a request to the Kong proxy, the plugin will redirect the request to the OP side. The OP will request for the username and password, because we added the simple_password_auth ACR for any path /??.

After successful authentication, the OP will display all requested permissions. Click Allow.

2. After clicking allow, you will get back to the Kong proxy and the plugin will serve the default home page of the upstream service.

3. Click on Flights. It is also in the /?? path, so the user already has permission to access this resource.

4. Now click on “Payments”, on which we added the OTP stepped-up authentication. The plugin will redirect again to the OP. As per the OTP script, it will ask for the username and password.

5. After successful authentication, the OP Server asks you to enroll in a device. Scan the displayed QR Code in an authenticator application, then click on Finish. Check the Gluu CE docs for supported OTP applications.

6. After successful enrollment, it will prompt you to enter the OTP. Enter the OTP from the authenticator application and click on Login.

7. After OTP authentication, the OP server will redirect back to the Kong proxy and serve the Payments page.

Conclusion

At a high level, implementing a piece of infrastructure like an API or Web 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:

1. Multiple authentication is not in code — it’s in the HTTP routing infrastructure. That means you can change the authentication methods without touching your code.
2. Your backend web app is not Internet-facing
3. You can implement other security, like limiting transaction volume (i.e. how many calls per hour, day etc can a client make).
4. Developers don’t need to know anything about OpenID Connect 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!