README.md

Running APIcast with RH-SSO and OIDC for API Authentication

This example shows you how to use Red Hat Single Sign-On to verify the identity of an End-User and issue access tokens for use by clients wishing to access the End-User resources. 3scale will add an API Management layer, which includes access control, rate-limiting policies, and also a self-service model of registering the client applications for consuming the API.

Pre-requisites

• 3scale account - You can sign up for a Free Trial here
• Red Hat SSO instance - Installation and Configuration instructions
• API - You can use the 3scale echo API
• Client Application to consume the API - You can use a client such as Postman
• APIcast instance

Red Hat Single Sign-On Configuration for APIcast

1. Create a new realm (different from Master)
2. Set up Tokens Policies (Realm Settings > Tokens) - e.g to configure access token ttl
3. Set up Initial Access Tokens. This is necessary to synchronise client registrations between 3scale and Red Hat Single Sign-On.
   • Define Expiration - This will determine how long the access token used to register clients from APIcas will be valid for, so make sure to choose a long lived value unless you want to be changing this token often.
   • Define Count - This will determine how many clients can be registered using this access token, make sure to choose a large value unless you want to be changing this token often.
4. Create some test End-Users

Client Registration in APIcast (Optional)

In order to authenticate clients in RH SSO and correctly track usage in 3scale, client credentials need to be synchronised between the 2 systems. Typically this functionality would fall outside the realm of the Gateway, but we will show how you can implement this within the Gateway to provide a self contained environment.

The following instructions are only required if you want to manage client registrations from APIcast. Otherwise you can skip this whole section.

Pre-requisites

• Redis server needs to be running

APIcast Set up

APIcast v2 should be installed as usual with the following additional dependencies:

• The following dependencies need to be installed via yum
  • expat-devel: sudo yum install expat-devel
  • C compiler and development tools: sudo yum group install "Development Tools"
• The following lua libraries should be installed using luarocks:
  • luaexpat: sudo luarocks install luaexpat --tree=/usr/local/openresty/luajit
  • luaxpath: sudo luarocks install luaxpath --tree=/usr/local/openresty/luajit
  • cjson: sudo luarocks install lua-cjson --tree=/usr/local/openresty/luajit
• And a symbolic link created: so openresty can find them ln -s /usr/local/openresty/luajit/lib64/lua/5.1/* /usr/local/openresty/luajit/lib/lua/5.1/

Otherwise, please follow the instructions on the 3scale support site based on your chosen deployment method.

When it comes to running APIcast v2, we will use the same approach as in the Custom Configuration example to add an additional server block to handle the client registration in RH SSO. In this case, clients will be created in 3scale first and imported into RH SSO, e.g the way to do this is in docker would be by mounting a volume inside sites.d folder in the container.

Additionally we need to add some additional code to deal with client registration webhooks. This is included in webhook-handler.lua. Before you use this file, you will need to fill in the "Initial Access Token" value. Simply find CHANGE_ME_INITIAL_ACCESS_TOKEN in webhook_handler.lua and replace with the initial access token value for your realm. You can read more about this initial access token in the RH SSO documentation.

Altogether these 2 files would be included into APIcast as follows, e.g for docker

docker run --publish 8080:8080 --volume $(pwd)/rh-sso.conf:/opt/app/sites.d/rh-sso.conf --volume $(pwd)/client-registrations:/opt/app/src/client-registrations --env RHSSO_ENDPOINT=https://{rh-sso-host}:{port}/auth/realms/{your-realm} --env THREESCALE_PORTAL_ENDPOINT=http://portal.example.com quay.io/3scale/apicast:master

If you're running natively, you can just add these files directly into apicast/sites.d and apicast/src respectively.

3scale Configuration

Webhooks

In order to register applications created in 3scale as clients in RH SSO, you need to enable and configure webhooks on 3scale.

1. Enter in the APIcast url followed by the /webhooks path.
2. Turn Webhooks "ON."
3. Select the following Webhooks under Settings:
   • Applications > Create
   • Applications > Update
4. Enable "Dashboard actions fire web hooks" if you want to create applications in 3scale through admin portal.

Create an Application/Client

Once the webhooks are configured, you will want to create an application in 3scale to test the flow. To do this through the admin portal:

1. Navigate to a Developer account you have previously created
2. Click on Applications > Create Application.
3. Select an Application Plan under the API service you have configured for RH-SSO and OpenId Connect
4. Enter name and description and click on "Create Application"

This will generate a set of credentials for your new application. You will then need to add the redirect url for your client. For Postman, this will be: https://www.getpostman.com/oauth2/callback

At the same time, in the background, 3scale sends a webhook to APIcast, which in turn makes a request to Red Hat Single Sign-On to create a Client with the same credentials.

APIcast setup

To get this working with a 3scale instance the following conditions should be met:

1. Self-managed deployment type and OAuth authentication method should be selected
2. OAuth Authorization Endpoint should be left blank as this is already defined by the RHSSO settings.
3. Set the Public Base URL in the Production section of the Integration page to the gateway host e.g http://localhost:8080
4. An application created in 3scale configured with its Redirect URL to point to Postman (if that's what you're using as your client), e.g https://www.getpostman.com/oauth2/callback

Once you have Integrated your API as above (and you're not using APIcast for client registrations) you can run APIcast with RH-SSO and OpenId Connect support as follows, e.g if running APIcast self-managed

RHSSO_ENDPOINT=https://{your-rh-sso-host}:{port}/auth/realms/{your-realm} THREESCALE_PORTAL_ENDPOINT=https://{3scale-access_token}@{3scale-domain}-admin.3scale.net bin/apicast

Testing the Integration

Once you have APIcast and RHSSO configured and up and runnign you can create a new request in Postman:

1. Under "Authorization", select "OAuth 2.0"
2. Click "Get New Access Token" and fill in the following details:
   1. Auth URL:
   2. Access Token URL:
   3. Client ID
   4. Client Secret
   5. Grant Type: "Authorization Code"

to request an access token.