
## Introduction

OAuth2 Proxy is a reverse proxy and static file server that provides authentication using third-party providers like Google, GitHub, and others for validating accounts by email, domain, or group.

Oauth2 Proxy is useful when you want:

- One or more of your applications to be accessible only by authenticated users, for instance, users using a specific domain, emails whitelisting, and more
- To rely on a third-party provider to handle the authentication process (Google, GitHub, etc.)
- To keep a clear separation between the authentication service and the rest of your applications

In this guide, we will explain how to deploy OAuth2 Proxy on Koyeb to secure access to a sample application.
We will configure OAuth2 Proxy to use Google as a provider for the authentication. If you are interested in using other providers, you can find the list of supported providers on the [OAuth2 documentation](https://oauth2-proxy.github.io/oauth2-proxy/docs/configuration/oauth_provider).

For this tutorial, we will make use of the Koyeb [service mesh and discovery](/docs/reference/service-mesh-and-discovery) and will deploy:

- The OAuth2 Proxy service using the official Docker image and expose it publicly to act as our authentication layer and gateway access our sample application
- A sample application accessible only via the Koyeb [service mesh](/blog/service-mesh-and-microservices-improving-network-management-and-observability) and accessible to authenticated users via OAuth2 Proxy

Below is the diagram of what our deployment will look like:

![OAuth2 proxy deployment on Koyeb](/static/images/tutorials/oauth2-proxy-diagram.svg)

## Requirements

To successfully follow and complete this tutorial, you need:

- A [Koyeb account](https://app.koyeb.com) to deploy and run
- A [GitHub account](https://github.com/) to deploy the sample application

## Steps

To successfully follow this guide, you need to follow these steps:

1. [Create and configure a new Google OAuth application](#create-and-configure-a-new-google-oauth-application)
2. [Deploy and configure OAuth2 Proxy on Koyeb](#deploy-and-configure-oauth2-proxy-on-koyeb)
3. [Deploy a private sample application on Koyeb](#deploy-a-private-sample-application-on-koyeb)
4. [Validate the setup](#validate-the-setup)

## Deploy a private sample application on Koyeb

First, get started by deploying the sample application that the OAuth2 Proxy will serve once a user is authenticated.
In this guide, we will deploy the Koyeb ExpressJS example application available on the following [GitHub repository](https://github.com/koyeb/example-expressjs).

Deploy it inside a new Koyeb App, clicking the **Deploy to Koyeb** button in the readme.
You land on the pre-filled App creation page to deploy the application.

In the **Exposed ports** section, disable the **Public** exposure of the service by clicking the switch.

Change the App name to **oauth2-proxy-on-koyeb** and click **Deploy**

Our Koyeb App is created, and our sample application is being deployed. We can now move to the next section.

## Create and configure a new Google OAuth application

Before deploying the OAuth Proxy service, we need to create a new Google OAuth application we will use to authenticate our users.

Go to https://console.developers.google.com/project and create a new project that will own our application by clicking **New project** on the project dropdown menu in the navigation bar.
Once your project is created, in the search bar, type **OAuth consent screen** and press **Enter**.

You land on the **OAuth consent screen** creation page.

1. Select **External** as User type
2. Fill in the **App information** form with your app's name, logo, scopes, test users, etc.

Once the configuration is completed, click the **Save** button.

Then, in the search bar, type **Credentials** and press **Enter** to create a new OAuth2 client. On the **Credentials** page, click the **Create credentials** button and select **OAuth client ID**.

1. Select **Web application** as the application type
2. Name your OAuth 2.0 client, for example, **Koyeb OAuth2 client**
3. In the **Authorized redirect URIs** click **Add URI** and set the URI to ` https://<yourApp>-<yourOrg>.koyeb.app/oauth2/callback` where `<yourApp>` is your Koyeb App name and `<yourOrg>` your Koyeb organization name

Click the **Create** button, your OAuth client **ID** and **Secret** appear. You can also download them as a JSON file. Save them in a safe place. We will need them in a future step.

Our application is now ready and will allow us to obtain limited access to Google user accounts by delegating user authentication to Google.

## Deploy and configure OAuth2 Proxy on Koyeb

We are now ready to deploy the OAuth2 Proxy service on Koyeb. Go to the **Apps** tab of the [Koyeb control panel](https://app.koyeb.com) and select the App you previously created.

On the chosen App page, click the **Create Service** button to deploy the OAuth2 Proxy service:

1. Select **Docker** as the deployment method.
2. In the **Docker image** field, enter `quay.io/oauth2-proxy/oauth2-proxy`.
3. In the **Environment variables** section, create the following environment variables:

- `OAUTH2_PROXY_COOKIE_SECRET`: with a seed string for secure cookie as value. You can create the following shell command to generate once: `dd if=/dev/urandom bs=32 count=1 2>/dev/null | base64 | tr -d -- '\n' | tr -- '+/' '-_'; echo`
- `OAUTH2_PROXY_CLIENT_ID`: with Google Oauth2 client ID you previously created as value
- `OAUTH2_PROXY_CLIENT_SECRET`: with Google Oauth2 client Secret you previously created as value
- `OAUTH2_PROXY_PROVIDER`: with the Oauth provider name as value, here `google`
- `OAUTH2_PROXY_EMAIL_DOMAINS`: with the authenticate emails domains as value, here `*`
- `OAUTH2_PROXY_HTTP_ADDRESS`: with `0.0.0.0:8080` to ensure the OAuth2 Proxy is listening on all interfaces
- `OAUTH2_PROXY_UPSTREAMS`: with the private domain of the Koyeb Service you want to restrict access, example: `http://<myService>.<myApp>.koyeb:3000`

4. Click **Deploy**.

The Oauth Proxy service is being deployed and will be up and running in a few seconds.

## Validate the setup

With the OAuth2 Proxy deployed, we are now ready to test the authentication flow.

In your browser, open your Koyeb App URL of form `https://<yourApp>-<yourOrg>.koyeb.app/`.

You land the OAuth2 Proxy landing page, where you can authenticate with your Google account.

Click the **Sign in with Google** button and select the Google account you want to use to authenticate.
Once the authentication has succeeded, the Oauth2 Proxy will proxy requests to your private sample application.

## Conclusion

In this guide, we demonstrate how OAuth Proxy helps to delegate user authentication to a third-party provider and secure applications without any code changes in your existing application.

We took advantage of the Koyeb Mesh and discovery to make our OAuth2 Proxy and the sample application services communicate effortlessly and securely.

OAuth2 Proxy provides many options you can use to fine-tune the authentication flow and more. You can learn more about what you can achieve by reading the configuration options available in the [documentation](https://oauth2-proxy.github.io/oauth2-proxy/docs/configuration/overview).


This guide explains how to deploy OAuth2 Proxy to secure and add authentication to all your services on the Koyeb serverless platform.

Add Authentication to your Apps using OAuth2 Proxy


## Introduction

Kong Gateway is a fast, scalable, and distributed API Gateway offering powerful primitives to ease microservices and distributed architecture management.
Combining both Kong Gateway with the Koyeb serverless platform, you benefit from all the built-in blocks to deploy modern applications at scale:

- **Koyeb**: to easily deploy your applications globally and providing native TLS encryption, [global edge network](/docs/reference/edge-network), [service mesh and discovery](/docs/reference/service-mesh-and-discovery), horizontal scaling, and more.

- **Kong Gateway**: acting as distributed microservice abstraction layer offering rate-limiting, auth features, proxy caching, and more.

![Kong Gateway](/static/images/tutorials/kong-gateway.svg)

In this guide, we will deploy a Koyeb App with the following Services:

- Kong Gateway: to proxy requests and forward them to the target microservices.
- A simple HTTP echo service

We will then configure Kong rate-limiting to restrict the number of requests our services can receive, implement basic auth to one of our simple HTTP services, and see how to secure the Kong admin API.

## Requirements

To successfully follow and complete this guide, you need:

- A [Koyeb account](https://www.koyeb.com) to deploy the microservices and Kong API Gateway
- A PostgreSQL database Koyeb can access
- Docker installed on your machine to prepare the Kong Gateway database

## Steps

To successfully follow this guide and deploy Kong Gateway, you need to follow these steps:

1. [Deploy Kong Gateway](#deploy-kong-gateway)
2. [Deploy a simple HTTP echo service](#deploy-a-simple-http-echo-service)
3. [Configure Kong Gateway](#configure-kong-gateway)

## Deploy Kong Gateway

### Prepare your database

The first step is to prepare your database to run Kong Gateway. This database is used by Kong to store its configuration such as routes, services, etc.
In your terminal, run the following command to run the Kong database migration:

```bash
docker run --rm \
  -e "KONG_DATABASE=kong" \
  -e "KONG_PG_HOST=<PG_HOST>" \
  -e "KONG_PG_PORT=<PG_PORT" \
  -e "KONG_PG_USER=<PG_USER>" \
  -e "KONG_PG_PASSWORD=<PG_PASSWORD>" \
  -e "KONG_PG_SSL=on"
kong:latest kong migrations bootstrap
```

### Deploy Kong on Koyeb

With the Kong database migration performed, we can now deploy Kong Gateway, we use the official Kong Docker image `kong`.

On the [Koyeb control panel](https://app.koyeb.com/), in the **Overview** tab, click **Create Web Servcie** to begin:

1. Choose **Docker** as your deployment method.
2. Fill the **Docker image** field with `kong`.
3. In the **Environment variables** section, configure the environment variables required to properly run Kong Gateway:
   - `KONG_DATABASE`: The environment variable containing the type of database, here `postgres`.
   - `KONG_PG_DATABASE`: The environment variable containing the database name, here `kong`.
   - `KONG_PG_HOST`: The environment variable containing the PostgreSQL port.
   - `KONG_PG_PORT`: The environment variable containing the PostgreSQL host.
   - `KONG_PG_USER`: The environment variable containing the PostgreSQL user, in my case: `kong`.
   - `KONG_PG_PASSWORD`: The environment variable containing the PostgreSQL password. To store this value which contains sensitive information, we strongly recommend configuring the environment variable using the **Secret** type to encrypt it at rest.
   - `KONG_PG_SSL`: The environment variable use to connect the PostgreSQL connection using SSL, in my case: `on`.
   - `KONG_ADMIN_LISTEN`: The environment variable containing the host and port the admin need to listen, `0.0.0.0:8001`.
   - `KONG_PROXY_ACCESS_LOG`: `/dev/stdout`
   - `KONG_ADMIN_ACCESS_LOG`: `/dev/stdout`
   - `KONG_PROXY_ERROR_LOG`: `/dev/stderr`
   - `KONG_ADMIN_ERROR_LOG`: `/dev/stderr`
4. In the **Exposed ports** section, leave the existing root path (`/`) set to port 8000. Click **Add port** and add an entry exposing port 8001 using the `/admin` path in order to expose the Kong Gateway admin API.
5. Choose a name for your App and Service, for example `kong-gateway`, and click **Deploy**.

Within a few seconds, your Kong Gateway service will be up and running. You will be able to access it via the Koyeb App URL displayed in the Koyeb control panel: `<appname>-<orgname>.koyeb.app`

## Deploy a simple HTTP echo service

To implement a complete demo and showcase how Kong Gateway works, we will add a simple HTTP echo services in our Koyeb App.

This service will not be exposed directly to the Internet. Instead, we will take advantage of the Koyeb service mesh and discovery built-in features which provide
an isolated, secure private network to allow Koyeb Services to communicate inside a Koyeb App.

In your App, click the **Create Service** button, and deploy the service as below:

1. Fill the `Docker image` field with `mendhak/http-https-echo`.
2. In the _Ports_ section, keep the export port to `80` which is the port the `mendhak/http-https-echo` Docker image app is listening on. This setting is required to let Koyeb know which port your application is listening to and properly route incoming HTTP requests. Uncheck the checkbox **Expose publicly** to make the application only reachable via the Koyeb App mesh.
3. Give the Service a name, i.e `http-echo`, and click **Create Service**.

## Configure Kong Gateway

### Create new Kong services and register new routes

The next step is to configure the Kong Gateway to:

- Create two new services pointing to our simple HTTP echo service

In your terminal, run the following commands:

```bash
curl -i -X POST \
  --url https://<appname>-<orgname>.koyeb.app/admin/services \
  --data 'name=hello-service1' \
  --data 'url=http://http-echo/service1'

curl -i -X POST \
  --url https://<appname>-<orgname>.koyeb.app/admin/services \
  --data 'name=hello-service2' \
  --data 'url=http://http-echo/service2'
```

These commands create two Kong services with the name `hello-service1` and `hello-service2`. Each one of these services is configured with an upstream server URL pointing to two different paths of our HTTP echo service.

- Register two routes, one for each service we created to route incoming requests to each one of this service via a specific path

In your terminal, run the following commands:

```bash
curl -i -X POST \
--url https://<appname>-<orgname>.koyeb.app/admin/services/hello-service1/routes \
--data 'hosts[]=<appname>-<orgname>.koyeb.app' \
--data 'paths[]=/service1' \
--data 'methods[]=GET'

curl -i -X POST \
--url https://<appname>-<orgname>.koyeb.app/admin/services/hello-service2/routes \
--data 'hosts[]=<appname>-<orgname>.koyeb.app' \
--data 'paths[]=/service2' \
--data 'methods[]=GET'
```

These commands create two Kong routes, one for each service we previously created. That way, from our Koyeb App url, we will be able to access `https://<appname>-<orgname>.koyeb.app/service2` and `https://<appname>-<orgname>.koyeb.app/service1`.

### Add rate limiting

Kong Gateway provide a rate limiting plugin to protect your services and restrict the number of requests your upstream services receive from your API consumers.
To add rate limiting and protect your services, in a terminal run the following command:

```bash
curl -i -X POST https://<appname>-<orgname>.koyeb.app/admin/plugins \
  --data name=rate-limiting \
  --data config.minute=5 \
  --data config.policy=local
```

The rule above restricts the number of requests a service can receive to five requests per minute. You can validate the rate-limiting rule works as expected running six times the query below from the terminal:

```bash
curl -i -X GET https://<appname>-<orgname>.koyeb.app/service1
```

When you hit the rate-limiting limit you will see the following:

```bash
{
"message": "API rate limit exceeded"
}
```

### Enable basic auth on a service

Kong provides a large choice of [authentication plugins](https://docs.konghq.com/hub/#authentication) which can be helpful to secure one or all of your services.
In this guide, we will enable basic authentication on our `hello-service1` Kong service.

In the terminal, run the following command to enable basic auth:

```bash
curl -X POST https://<appname>-<orgname>.koyeb.app/admin/services/hello-service1/plugins \
    --data "name=basic-auth"  \
    --data "config.hide_credentials=true"
```

And create a consumer (in Kong represents a consumer or a user of a Service) by executing the following request:

```bash
curl -d "username=demo&custom_id=<REPLACE_ME_WITH_AN_ID>" https://<appname>-<orgname>.koyeb.app/admin/consumers
```

Last, create a new credential you will use to access the service:

```bash
curl -X POST https://<appname>-<orgname>.koyeb.app/admin/consumers/demo/basic-auth \
    --data "username=koyeb" \
    --data "password=demo"
```

Now if you go to `https://<appname>-<orgname>.koyeb.app/service1`, the basic auth form appears and asks for a username and password to access the service.

### Secure the Kong Gateway admin API

As we have previously seen, Kong allows you to secure your services using different methods. We will now use Kong to secure the admin API.
In the previous step, we add using the basic auth method, to secure the admin, we will use API key authentication.

1. Create a new service to access the admin

```bash
curl -i -X POST \
  --url https://<appname>-<orgname>.koyeb.app/admin/services \
  --data 'name=admin-api' \
  --data 'url=http://localhost:8001'
```

2. Register a new Route to access the`admin-api` service:

```bash
curl -X POST https://<appname>-<orgname>.koyeb.app/admin/services/admin-api/routes \
  --data 'hosts[]=<appname>-<orgname>.koyeb.app' \
  --data 'paths[]=/admin' \
```

3. Create an `admin` consumer:

```bash
curl -d "username=admin&custom_id=<REPLACE_ME_WITH_AN_ID>" https://<appname>-<orgname>.koyeb.app/admin/consumers
```

4. Enable API key auth on the admin api:

```bash
curl -i -X POST \
   --url https://<appname>-<orgname>.koyeb.app/admin/services/admin-api/plugins/ \
   --data 'name=key-auth' \
   --data 'config.hide_credentials=true'
```

5. Create the API key

```bash
curl -i -X POST https://<appname>-<orgname>.koyeb.app/admin/consumers/admin/key-auth \
  --data key=<YOUR_API_KEY>
```

6. Validate authentication

```bash
curl -i https://<appname>-<orgname>.koyeb.app/admin-api \
  -H 'apikey: <YOUR_API_KEY>'
```

If everything works as expected, you can now update your Koyeb Kong service and disable the exposition of port 8001 to the Internet by unchecking **Expose publicly**.
That way the Kong admin API will be only accessible via the secure endpoint `https://<appname>-<orgname>.koyeb.app/admin-api`.

## Conclusion

In this guide, we did a quick tour of how to configure and use Kong Gateway. We explored the Kong plugin system and enable rate-limiting and auth on our services. We also showcased how to secure and restrict access to the Kong admin API.

We took advantage of the Koyeb mesh and service discovery built-in features offering a simple, secure, and powerful private network to host your microservices and access them from the Internet using Kong Gateway.

To go deeper and learn more about how Kong Gateway works, we recommend you to check out the Kong official [documentation](https://docs.konghq.com/gateway-oss/)

Questions or suggestions to improve this guide? Join us on the **[community platform](https://community.koyeb.com/)** to chat!


Discover how to leverage your microservices stack using Kong API Gateway with Koyeb Serverless Platform. In this guide, we do a quick tour of how to configure and use Kong Gateway. We explored the Kong plugin system and enable rate-limiting and auth on our services. We also showcase how to secure and restrict access to the Kong admin API.

Service Mesh

Add Authentication to your Apps using OAuth2 Proxy

Use Kong API Gateway on Koyeb Serverless Platform