Chapter 7. APIcast self-managed (old version) and OAuth 2.0
The details of this section are for reference only. This option is no longer supported and you should consider migrating away from this configuration at the earliest opportunity.
SSL use is mandatory for all OAuth calls.
This document refers to OAuth for an old version of APIcast which consists of Nginx downloadable configuration files. Note that since May 2017, that version is no longer available in the GUI for new customers. For details on OAuth support in the latest version of APIcast, please see here.
This tutorial shows the necessary steps to set up APIcast self-managed with 3scale’s OAuth extensions to make APIcast act as an OAuth 2.0 provider.
Currently, only the authorization code (server-side) grant flow is available in APIcast. However, you can find config templates for all other flows on this GitHub repository.
7.1. Prerequisites
As 3scale doesn’t hold any details about the users that you authenticate, in order to integrate with 3scale using OAuth 2.0, we require that you handle user authentication on your side. To do this, you’ll have to provide the URL for a page where APIcast can send users to authorize an application. This page should be behind a login so that the user can be correctly identified and authenticated. Once the user has been authenticated and the application authorized, you should redirect back to APIcast with the outcome of the authorization grant from the user.
When APIcast redirects a user to the authorization URL, it will send the following parameters along with the request:
-
scope:the plan ID that the application belongs to. The application plan defines the scope in 3scale. -
state:a hash value shared between APIcast and the API to identify request and ensure its authenticity. -
tok:the value of the access token that will be given to the user if the application is authorized. The token will only be issued when it’s exchanged for an authorization code. If the authorization code is not exchanged, the access token will expire after 10 minutes.
If the user successfully identifies himself and authorizes the application, the authorization page should redirect to an endpoint on APIcast. By default this is located at /callback, but it can easily be changed within the APIcast config files to suit your needs.
Take a look and see how to set this up.
7.2. OAuth Configuration
To proceed with the installation, you’ll need to follow most of the same steps as with the basic APIcast Integration to configure your API and define your methods and enpdoints. You can find these steps in the link: Installing APIcast document. Additionally, you will need to make sure the following steps are followed:
7.2.1. Step 1: Edit Integration Settings
As per the screenshot below, you will need to set the "Production Deployment Option" to Self-Managed Gateway, as OAuth is not currently available on APIcast hosted.
On the same page, you will also need to set the "Authentication" to OAuth 2.0.
7.2.2. Step 2: Declare your OAuth Authorization Endpoint
This will be the url that your users are presented with when they need to log in to your service to authenticate themselves and provide consent.
The APIcast OAuth extension allows APIcast to act as an OAuth provider. However, you still need to provide an authorization endpoint for users to authenticate themselves and approve/reject third-party application access. This authorization endpoint should be behind a login so a user can be identified and authenticated. Once the approval is done, you will need to redirect your logged in user to the callback endpoint on APIcast, so it can take care of the rest of the workflow.
7.2.3. Step 3: Download the APIcast config files
3scale automatically generates all the files needed to use APIcast as your API gateway and OAuth provider based on the data you input into the integration page. Once you have entered all the required information, you can download these files and install them on your own APIcast instance. The zip file downloaded will contain a separate *.lua file for each service defined as well as lua files to support the OAuth handshake and a nginx_\*.conf file which is shared across services.
If you have multiple services defined, the user downloading the configuration files will receive a zip file where the Lua files will only contain Service tokens corresponding to the services that they have access to. This way the Provider Key is kept secret to full admins only.
7.3. Running your self-managed APIcast instance (production)
If you’re familiar with NGINX, it shouldn’t take you long to get APIcast up and running locally. Note that your NGINX installation must have the Lua plugin, and for some of the OAuth 2.0 grant types, you must also have Redis installed on your server.
If you’re not familiar with NGINX, we recommend you install OpenResty, a fantastic web application, which is basically a bundle of the standard NGINX core with almost all of the third-party NGINX modules that you’ll need built in.
7.3.1. Step 1: Install the dependencies (for Ubuntu)
For Debian/Ubuntu linux distribution you should install the following packages using apt-get:
sudo apt-get install libreadline-dev libncurses5-dev libpcre3 libpcre3-dev libssl-dev perl sudo apt-get build-dep nginx
For different systems, check out the OpenResty documentation.
7.3.2. Step 2: Compile and install OpenResty
Download the code and compile it, change VERSION with your desired version (we usually recommend running the latest stable version.)
wget http://agentzh.org/misc/nginx/ngx_openresty-VERSION.tar.gz tar -zxvf ngx_openresty-VERSION.tar.gz cd ngx_openresty-VERSION/ ./configure --prefix=/opt/openresty --with-luajit --with-http_iconv_module -j2 make make install
At this point, you have NGINX and Lua installed using the OpenResty bundle.
7.3.3. Step 3: Install Redis
Download and install Redis on APIcast server (we recommend to always use the latest stable version.)
tar zxvf redis-VERSION.tar.gz cd redis-VERSION make sudo make install
In order to to install and run the Redis server, run the following, accepting all the default values:
sudo ./utils/install_server.sh
7.3.4. Step 4: Download the APIcast configuration from 3scale
Please note that only the authorization code (server-side) grant flow configs are currently available for download from the Integration page. However, you can find configuration templates for all other flows on our GitHub repository here.
Download the APIcast configuration files from 3scale by clicking the Download button. This will give you a zip file with six files inside:
-
authorize.lua- This file contains the logic for authorizing the client, redirecting the end_user to the OAuth login page, generating the access token, and checking that the return URL matches the one specified by the API buyer. It runs when the /authorize endpoint is hit. -
authorized_callback.lua- This file contains the logic for redirecting an API end user back to the API buyer’s redirect URL. As an API provider, you’ll need to call this endpoint once your user successfully logs in and authorizes the API buyer’s requested access. This file gets executed when the /callback endpoint is called by your web application. -
get_token.lua- This file contains the logic to return the access token for the client identified by a client_id. It gets executed when the /oauth/token endpoint is called. -
nginx_*.conf- The .conf is a typical NGINX config file. Feel free to edit it or to copy/paste it into your existing .conf if you are already running NGINX. -
nginx_*.lua- This file contains the logic that you defined on the web interface to track usage for various metrics and methods. -
threescale_utils.lua
7.3.5. Step 5: Start and stop APIcast
The only thing left to do is start APIcast. There are many ways to do this, but the most straight-forward is:
sudo /opt/openresty/nginx/sbin/nginx -p /opt/openresty/nginx/ -c /opt/openresty/nginx/conf/YOUR-CONFIG-FILE.conf
The example assumes that the working directory of APIcast is /opt/openresty/nginx which is the path you passed during the installation to configure --prefix=/opt/openresty. You can change it, but be aware of the user privileges.
The example also assumes that the .conf generated by 3scale is placed at /opt/openresty/nginx/conf/. Of course, you should place the files and the directories at the location that best suits your production environment, as well as to start and stop the process as a system daemon instead of by executing the binary directly.
To stop a running APIcast instance:
sudo /opt/openresty/nginx/sbin/nginx -p /opt/openresty/nginx/ -c /opt/openresty/nginx/conf/YOUR-CONFIG-FILE.conf -s stop
The option -s let you pass a signal to nginx. The process that will be stopped is the one whose .pid is stored in /opt/openresty/nginx/logs/nginx.pid.
The APIcast logs are in the same directory by default: /opt/openresty/nginx/logs/. Check the error.log when setting up the whole process.
7.3.6. Step 6: Test your OAuth Flow
The best way to test that your API now supports OAuth is to use Google’s OAuth playground: https://developers.google.com/oauthplayground
You will need to set the redirect URL for the application you want to use to test this to the google OAuth Playground URL: https://developers.google.com/oauthplayground
You can then fill in the settings as in the screenshot below:
The authorization and token endpoint URLs are the URLs from your APIcast instance. In the scope, put the name of the application plan for the application (for example, “Default”).
Click on Authorize API, which will redirect you to your login URL. Then, log in to a user account on your application and authorize the application. Once that’s done, you’ll be redirected back to the Google OAuth Playground with an authorization code. Exchange this for an access token. You now have an access token to call protected endpoints on your API.
You can now make a request to your API, but replacing your API backend host name (in the example echo-api.3scale.net) by the hostname of your APIcast instance and adding the access_token parameter. For example:
curl -X GET "http://YOUR_APICAST_HOST/read?access_token=YOUR_ACCESS_TOKEN"
Now you have your API integrated with 3scale.
