3scale ActiveDocs and OAuth 2.0

How to secure your API documentation with Red Hat Single Sign-On?

This guide is designed to help you integrate your Red Hat Single Sign-On server with the OpenAPI (OAI)-based ActiveDocs in your 3scale developer portal. Although it has only been implemented with this particular Identity & Access Management solution (IAM), you could in theory make some customizations where necessary to integrate with another OpenID Connect-based solution.

This is the 1st part of a series of posts where each OAuth 2.0 flow will be covered separately. Here we start with the Authorization Code flow.

What is ActiveDocs?

ActiveDocs is the 3scale feature that is based on OAI 2.0 & SwaggerUI. You can host any OAI compliant spec on 3scale & publish it in the Developer Portal for your community’s reference & testing. One of the great advantages of 3scale ActiveDocs is that it has its own proxy, which supports Cross-Origin Resource Sharing (CORS) – This is only applicable when using the SaaS platform. Perfect! No need to configure your own API to support CORS for this purpose.

Additionally there are some custom 3scale fields that you can use inside the OAI spec to expose the currently logged in user’s credentials for easy use. No copy-pasting of those multiple sets of credentials to files where you’re never going to remember them. The ActiveDocs feature doesn’t support OAuth 2.0 out-of-the-box. Therefore, this “how to” is intended to provide a means of enabling an OAuth 2.0 flow on the documentation page exposing your API services.


  • A Red Hat Single Sign-On server configured according to our Supported Configurations. Create the realm as documented.
  • An HTTPS endpoint to access your server in the format: https://{my-rhsso-server.com}/auth/realms/{realm-name}.
  • An OAI compliant spec with an Authorization header field for each operation that requires a token to call the API.

What Will We Cover?

  • How to configure Red Hat Single Sign-On server and the test client.
  • How to configure 3scale.
  • Implementing the custom JavaScript client and Liquid to enable Authorization Code flow.

Configure Red Hat Single Sign-On & Test Client

Once you have configured the server and realm according to the documentation mentioned above, set up the test client following the below steps. You only need to use this client as a verification of the integration. If you are already using the OpenID Connect integration, then simply update an existing client according to the steps below. Otherwise, first create a client as described in Configuring red Hat Single Sign-On 1.4.1 and then follow these 3 steps.

Step 1

Add a redirect_uri equivalent to the developer portal domain, plus the path where the documentation is hosted. This value can also be a wildcard if the ActiveDocs specs are to be hosted on multiple pages in the portal.

Step 2

Enable the Standard Flow enabled switch for the Authorization Code flow.

Step 3

Add the developer portal domain as the Web Origin value. For example: https://{account-name}.example.com. This is necessary for the CORS requests to succeed for each client.

Configure 3scale

If you’re using the OpenID Connect integration then the 3scale platform manages the synchronization of clients into your Red Hat Single Sign-On server for you (in which case you can skip step 1). If you are also using the Red Hat Single Sign-On developer portal integration, then skip step 2 as well. Otherwise, follow all the steps below.

Step 1

Create a client in 3scale via the API if you have already created the client in your Red Hat Single Sign-On server. Use the credentials (client_id & client_secret) in the example request as shown here:

curl -v  -X POST "https://{account-name}-admin.3scale.net/admin/api/accounts/{account_id}/applications.xml"\ 
-d 'access_token={access_token}\

This is probably a bit quicker and easier for testing purposes. However, in production it makes much more sense that the synchronization is done from 3scale to Red Hat Single Sign-On, as these are the client and token masters respectively. The clients can be created via API in Red Hat Single Sign-On also.

Step 2

Add the Red Hat Single Sign-On URL to your developer portal SSO integrations if you haven’t already done so. Follow the Configuring 3scale section to do this. This will then be reused in the Liquid templates in the developer portal.

Note: This would enable the SSO integration for the developer portal. If you do not want this, you can hardcode the URL in the keycloak-client partial.

Step 3

Import the OAI spec using the ActiveDocs API. The easiest way to manage all your different API specifications is to host them directly on the 3scale platform. An example API call is shown here to import a spec. You can prepend the body of the JSON spec with the following query parameters:

  "swagger": "2.0",
  "info": {
    "version": "1.0.0",
    "title": "Echo API",
    "description": "A sample echo APIII"
  "securityDefinitions": {

You can pass the JSON file as a parameter with the cURL request as so:

curl -v  -X POST "https://{account-name}-admin.3scale.net/admin/api/active_docs.json" -d @/path/to/file.json

Ensure that the spec has the following field definition in the parameters array for each operation that requires a token to call the API endpoint:

"parameters": [
            "type": "string",
            "description": "Authorization header\n(format: Bearer [access_token])",
            "name": "Authorization",
            "in": "header",
            "required": true

Add the JavaScript Client & Custom Liquid

First let’s add the cookie.js module to the 3scale CMS. In the Developer Portal tab of the admin portal you can choose “New Page” or “New File” from the dropdown button. Configure the relevant attributes whether you add it as a file or page. Choose a Title that is appropriate; Section should be javascripts; Path should be the format /javascripts/cookie.js; Layout must be empty; and finally, the Content Type set to JavaScript.

Upload the partials for the oauth-widget & the keycloak-client to the CMS. The name you choose here will be reused in the main template in the {% include %} Liquid tag. From the same dropdown button choose “New Partial”. Now upload the changes required to your documentation template. You can see the necessary Liquid tags in the example docs template. This will work with both SwaggerUI 2.1.3 & 2.2.10. In the older version the Liquid tag to include the ActiveDocs spec would have looked something like: {% active_docs version: '2.0', services: 'spec_system_name' %} the spec_system_name is what you passed in the previous cURL request when importing to 3scale. If you want to upgrade to the latest version supported in the 3scale platform, then follow the upgrade tutorial. You should reference the OAuth widget partial in the first {% include %} and the Keycloak client last.

Everything in the JavaScript and Liquid is fully dynamic, therefore all the account specific attributes like developer portal domain, documentation page URL, application client_id, client_secret etc., do not need to be hardcoded anywhere.*

How the Client Works

The OAuth widget checks if the current page contains a state parameter in the URL and renders the appropriate button to authorize or get_token:

Authorize button for first leg of the flow

A dropdown of applications becomes available for the logged in user to retrieve a token. The application name and service name are rendered, but this is customizable to meet your needs. The authorize will execute the cookie.js module and it stores a state value in the cookies with a default expiration of 60 seconds. You can configure this expiration time as you wish. The browser then redirects the user to the login page, and upon successful authorization, a success message will be displayed. After the browser has redirected the user to the developer portal a get_token button will be rendered:

Get token button for last leg leg of the flow

You must select the same application for the next leg of the flow, which will result in a token returned to the browser if successful. The Red Hat Single Sign-On server returns the state parameter during the callback. The client validates this against the original value that it stored in the cookie:

Token is auto-populated into each Authorization field in the documentation


3scale by Red Hat API and Identity Management Series

Today’s modern infrastructure faces the complex challenge of managing user’s access to the resources. To protect system and data integrity, companies have implemented identity and access management (IAM) solutions for their in-house systems. IAM solutions address three major concepts: identity, authentication, and authorization.  Their job is to ensure that only authenticated and authorized users have access to resources or information. Every IAM solution on the market provides a great set of features such as:

  • Single Sign-On (SSO)
  • Centralized policy-based authentication and authorization
  • Identity federation

Continue reading “3scale by Red Hat API and Identity Management Series”


HOW-TO setup 3scale OpenID Connect (OIDC) Integration with RH SSO

This step-by-step guide is a follow-up to the Red Hat 3scale API Management new 2.1 version announcement. As many of you will know, this new version simplifies the integration between APIcast gateway and Red Hat Single Sign-On through OpenID Connect (OIDC) for API authentication. As a result, now you can select OpenID Connect as your authentication mechanism besides API Key, App Key pair, and OAuth. Also, the on-premise version adds a new component that synchronizes the client creation on the Red Hat Single Sign-On domain.

Continue reading “HOW-TO setup 3scale OpenID Connect (OIDC) Integration with RH SSO”


Managed File Transfer (MFT) 2.0 with Fuse, 3scale and AMQ

It was more than 2 years ago that I blogged about building a Managed File Transfer (MFT) solution using Fuse and AMQ. First, many things have progressed, particularly the technology landscape. Second, MFT protocols have evolved. AS4 provides a new and improved way of securely exchanging documents over HTTP. In addition, the OASIS consortium governs a vendor-neutral open standard. This is great news, but how do we achieve support for these new standards and transports with our antiquated, legacy, and proprietary MFT software?

Continue reading “Managed File Transfer (MFT) 2.0 with Fuse, 3scale and AMQ”


3scale API Management Simplifies OpenID Connect Integration

Red Hat 3scale API Management Platform simplifies the integration between APIcast gateway and Red Hat Single Sign-On through OpenID Connect (OIDC) for API authentication. Consequently, the new version enables API provider users to select and configure their API authentication process from the Admin Portal UI

Continue reading “3scale API Management Simplifies OpenID Connect Integration”


Innovating on Developers Events, Building the API Escape Room

It’s been almost a month after the first world edition of API Escape room at the Red Hat Summit in Boston. We thought you might be interested to hear details on how we prepared this event.

With the 3scale team, we often participated in classical hackathons where developers gather for 48 hours to come up with a working prototype. These were awesomely fun (!), but the outcomes of those events are quite uncertain for organizers, sponsors, and participants. You cannot guarantee that hackers will build stunning original hacks and it can be a tough ask to keep working for such a long period. You can’t be sure that it won’t just be another “recipe app” or “Uber for X”.

Continue reading “Innovating on Developers Events, Building the API Escape Room”


HOW-TO setup a 3scale AMP on-premise all-in-one install

As many of you already know, a couple of weeks ago, on April 25, 2017, Red Hat announced it’s fully containerized API Management Platform On-Premises version. Alongside the Software as a Service (SaaS) version, the 3Scale Openshift-based on-premise version opens new opportunities with customers looking for more control over their private APIs. Deploying API Management in their own data center or self-managed cloud environment is part of a critical path.

Continue reading “HOW-TO setup a 3scale AMP on-premise all-in-one install”