Chapter 7. APIcast and OAuth 2.0
Please note that OAuth authentication mode is not available on APIcast hosted yet.
This document refers to configuring OAuth 2.0 for the latest version of APIcast. To run APIcast, follow any of its deployment method instructions: Self-Managed, the Docker containerized environment or OpenShift.
For details on OAuth support in the previous version of APIcast (Nginx downloadable configuration files), please see here.
APIcast offers support for the OAuth 2.0 Authorization Code flow out of the box as long as the following pre-requisites are met:
7.2. APIcast Configuration in 3scale Admin Portal
In order to configure this, we will first need to choose the OAuth Authentication method from the Integration Settings ( API > Integration > edit integration settings ) screen on our 3scale Admin Portal. We will also need to ensure we have selected the Self-managed Gateway option, as it is not currently possible to run APIcast with OAuth 2.0 Authorization Code support on the APIcast cloud gateway.
Once that is done, we will see an additional field in the Integration Screen ( API > Integration ) under Authentication Settings: OAuth Authorization Endpoint. Here we define where Resource Owners will be redirected to in order to authenticate and confirm they authorize a given client access to their resources (as per RFC6749#4.1).
All other fields on the Integration Screen should be configured as per the APIcast Overview document. Since we will be running all components locally for this example, my Public Base URL where APIcast is running will be
In order to show a sample integration with an Authorization Server we will use a very simple Ruby app to act as an Authorization Server. This app will run on localhost port 3000 with the OAuth Authorization Endpoint at
The sample code for this app can be found in the
apicast/examples directory under
oauth2/auth-server. There is also a file named
docker-compose.yml that allows you to deploy a test environment to test the API Integration and OAuth 2.0 Authorization Code Flow..
7.3. Running APIcast with OAuth
In order to start APIcast in OAuth mode, we will first need to have a Redis instance running and pass in the instance details when running APIcast.
In our case, this is running on
localhost:6379. Since this is running on the default port, we only need to specify
REDIS_HOST, if this were running on any other port, we would also have to specify
REDIS_PORT. We can then start APIcast like so:
REDIS_HOST=localhost THREESCALE_PORTAL_ENDPOINT=https://MY_PROVIDER_KEY@MY_ADMIN_PORTAL.3scale.net bin/apicast -v
Here we have added the
-v flag to run APIcast in verbose mode, in order to allow us to get more debugging output in case anything goes wrong, but this can be omitted.
Our Authorization Server should also be up and running and ready to receive requests.
7.4. Testing the Flow
In order to test this flow, we will be running all components: APIcast, Redis, Authorization Server and Client, using the Docker Compose tool as per the oauth2 example listed in the
examples directory in the APIcast GitHub repository. This will take care of starting up all of the required components. However, you can also start each of them up individually. Please ensure you do not already have any APIcast, Redis or other component instances already running on the same ports at the same time. Note that you will need to have the Docker containerized environment and the Docker Compose tool installed to use these examples.
The first component to come into play is the sample client application, which would be written by a Developer to request an access token from APIcast. This is a simple Ruby app that will act as the client (as per the client role defined in RFC6749#1.1) in the Authorization Code Flow. The sample code for the client app can be found in the
apicast/examples folder under
We will be running this application on
localhost:3001. The application has a
/callback endpoint defined to receive and process any authorization codes and access tokens from APIcast. As such, this location will need to be set up on our 3scale account, under a test application, as the Redirect URL.