An API Journey: From Idea to Deployment the Agile Way–Part I

The goal of this series of posts is to describe a proposed approach for an agile API delivery process. It will cover not only the development part but also the design, the tests, the delivery, and the management in production. You will learn how to use mocking to speed up development and break dependencies, use the contract-first approach for defining tests that will harden your implementation, protect the exposed API through a management gateway and, finally, secure deliveries using a CI/CD pipeline.

I coauthored this series with Nicolas Massé, who is also a Red Hatter. This series is based on our own real-life experience from our work with the Red Hat customers we’ve met, as well as from my previous position as SOA architect at a large insurance company. This series is a translation of a typical use case we run during workshops or events such as APIdays.

Continue reading “An API Journey: From Idea to Deployment the Agile Way–Part I”


Red Hat Summit 2018: Develop Secure Apps and Services

Red Hat Summit 2018 will focus on modern application development. A critical part of modern application development is of course securing your applications and services. Things were challenging when you only needed to secure a single monolithic application. In a modern application landscape, you’re probably looking at building microservices and possibly exposing application services and APIs outside the boundaries of your enterprise. In order to deploy cloud-native applications and microservices you must be able to secure them. You might be faced with the challenge of securing both applications and back-end services accessed by mobile devices while using third party identity providers like social networks. Fortunately, Red Hat Summit 2018 has a number of developer-oriented sessions where you can learn how to secure your applications and services, integrate single-sign on, and manage your APIs. Session highlights include:

Continue reading “Red Hat Summit 2018: Develop Secure Apps and Services”


Unit Testing for Camel Rest DSL and Spring Boot

Hopefully by now, you know how to write your first Rest DSL Camel Route using Spring Boot.  If not, check this post first. Now that you have your route written, it’s time to write a unit test for it.  Many people find Apache Camel unit testing a big struggle to figure out.  Luckily, when using Spring Boot with the Apache Camel Rest DSL testing, a Rest Route isn’t too difficult.

Continue reading “Unit Testing for Camel Rest DSL and Spring Boot”


Writing Your First Camel Spring Boot Project With the Rest DSL

Rest services are becoming more and more popular for communication between systems.  Now that Red Hat supports the use of Red Hat JBoss Fuse with Apache Camel Spring Boot, learn how you can get started with the Rest DSL and Spring Boot.  These directions will use the camel-servlet component, although various components can be used.

Continue reading “Writing Your First Camel Spring Boot Project With the Rest DSL”


3Scale by Red Hat Integration with ForgeRock using OpenID Connect

In my last article, I wrote about how API Management and Identity Management can work together in a complementary fashion to secure and manage the services/endpoints which applications expose as APIs. In that article I covered how Red Hat 3scale API Management can be used to integrate an identity manager, in addition to providing API management functions such as rate limiting and throttling.

This article will show how to integrate ForgeRock with 3scale by Red Hat. ForgeRock is one of the popular and growing identity management companies. ForgeRock helps organizations interact securely with customers, employees, devices, and things.

For this tutorial, the following installers are used:

Below are the components:



  1. Client App sends requests to APIcast API gateway with desired request parameters.
  2. APIcast verifies the credentials with API Manager, and stores in cache if valid.
  3. APIcast sends the request to ForgeRock, where it authenticates the user and obtains end user consent/authorization.
  4. ForgeRock sends the End-User back to the Client with an id_token, and if requested, an access_token.
  5. For every API call, the JWT token is sent via APIcast to API backend where it verifies the incoming JWT with the ForgeRock public key. If valid, then proxy the call to the API backend.
  6. The backend API extracts the JWT, verifies the scope for the user, and sends back an API response to the client application.

Sequence Diagram


To complete the end-to-end integration we should set up all pieces one by one. Below are the components and the instructions.

Setting up API backend

For this demo, I will be using the echo API service hosted by 3scale by Red Hat. You can always write a service that will extract the JWT, parse the JSON payload, extract the user profile, and send back the product subscription status for that user.

Setting up API Manager

  1. Login to 3scale by Red Hat admin portal.
  2. Select the service that you want to use to enable OpenId Connect integration with ForgeRock. Click on the APIs tab, select the Service, and click on the Integration link. We are using the default Echo API:


3. Click on edit integration settings:


4. Select OpenID Connect and click on Update Service:


5. Go back to the integration page, and click on edit APIcast configuration:


6. Enter the Staging and Production base URL. We will deploy the APIcast gateway locally on docker, so name it as http://localhost:8080:


7. Finally, click on Update Staging Environment. You can also promote it to Production (optional).

8. Create an application and get the client_id and client_secret .

8.1 Go to the Developers tab and click on Developers:


8.2 Click on Application:


8.3 Click on Create Application link:


8.4 Select the Application Plan for the service and then click on Create Application:


8.5 Note down the client_id and client_secret .  We will use the Postman to test our integration so we will fill in the callback information with a fixed link. Type in ``. in the Redirect URL field. Click on the Update button.


That’s all!
Now let’s move toward the ForgeRock setup.

Setting up ForgeRock

Installation of ForgeRock is outside the scope of this tutorial. Please refer ForgeRock documentation for installation. After installing ForgeRock, make sure you are able to access the URL on

  1. Create Realm:


2. Click on Configure Oauth Provider → Configure OpenID Connect:



3. Click on Create:



4. Creating (or syncing) the 3scale by Red Hat client_id with ForgeRock.

Our lead developer, Michal Cichra, wrote a tool called Zync to synchronize all 3scale by Red Hat client_ids to IDP. So every time when an application is created (i.e client_id and client_secret  on 3scale by Red Hat), the same is automatically created on the IDP side. For this exercise, I have manually created the client_ids using the below registration. If you prefer to create the ids runtime, edit the tool with the client registration endpoint of ForgeRock. PRs are welcome.


4.1 Click on Agents → Oauth2.0/OpenID Connect Client → New:



4.2 Copy the 3scale by Red Hat client_id and client_secret from the admin portal that you created earlier. Enter Name as client_id and Password as client_secret. Click Create:

4.3 Enter Redirection URIs → and Scope → openid. Click Save:



5. Creating an End user that will Authenticate against the IDP.

5.1 Goto Realms → Subjects. Click on New:


5.2 Enter `ID: apiUser` and `password: 12345678`:


All set for ForgeRock!

Setting up APIcast API gateway

Make sure to install docker and docker-compose before executing the next commands. We will be running APIcast API gateway locally and it will accept all incoming requests from the client.

1. git clone
2. Edit the .env file per your setup
3. docker-compose up

Send Request to APIcast

  1. Send Authorize request to APIcast
GET http://localhost:8080/authorize?client_id=21657b2d&scope=openid&response_type=token id_token&nonce=1234&redirect_uri=
client_id = 3scale client id
scope = openid
response_type = token id_token
nonce = 1234
redirect_uri =
realm = internal


2. A login page is shown from Forgerock. Enter the credentials that we created earlier for End User:

Enter credentials as: apiUser / 12345678 :


Click on Allow:


An access_token and id_tokenis redirected back to the application. The id_token is the JWT token generated by the IDP.

Paste the token on website to decrypt the contents (optional):


The above token is sent to the APIcast gateway for every call. The gateway will verify the signature of JWT using the public key. If valid, the call is proxied to the API backend along with the JWT. It’s then the backend responsibility to base64 decode the JWT, extract the user profile from JSON payload, and then (depending on the profile) send back the API response. [Refer How microservices verify a JWT for in-depth details]

Request and Response from APIcast:

curl -H "Authorization: Bearer eyAidHlwIjogIkpXVCIsICJraWQiOiAiU3lsTEM2Tmp0MUtHUWt0RDlNdCswemNlUVNVPSIsICJhbGciOiAiUlMyNTYiIH0.eyAiYXRfaGFzaCI6ICJUcUd5c2dRZURsWDhIOFNHR1FjcEF3IiwgInN1YiI6ICJhcGlVc2VyIiwgImlzcyI6ICJodHRwOi8vdmJoYWxlcmEub3NlY2xvdWQuY29tOjgwODAvb3BlbmFtL29hdXRoMi9pbnRlcm5hbCIsICJ0b2tlbk5hbWUiOiAiaWRfdG9rZW4iLCAibm9uY2UiOiAiMTIzNCIsICJhdWQiOiBbICIyMTY1N2IyZCIgXSwgIm9yZy5mb3JnZXJvY2sub3BlbmlkY29ubmVjdC5vcHMiOiAiNjk2YmRlNTYtZmNiZi00ZTFkLWIzOGItYmMzNzQ4OGVhODRiIiwgImF6cCI6ICIyMTY1N2IyZCIsICJhdXRoX3RpbWUiOiAxNTE2OTE3NTQwLCAicmVhbG0iOiAiL2ludGVybmFsIiwgImV4cCI6IDE1MTY5MjEyMzUsICJ0b2tlblR5cGUiOiAiSldUVG9rZW4iLCAiaWF0IjogMTUxNjkxNzYzNSB9.SuYI1tP5uJ94y8XRc6QQClXlmuLzMFEcE1LlW_31GafXv91jg3QwbRI-1RV1XOISfWnLW7l-1eGyKZtK_P8nroLjXYs2c-HrIgTwK16FBTcM9-Gt_jzbntwN4hiLD4PbhVb562fTkdqQCA4ZlNR9QOmQUE0ZKlMSwB3b0bNSmys" http://localhost:8080/subscriptions -v
*   Trying ::1...
* Connected to localhost (::1) port 8080 (#0)
> GET /subscriptions HTTP/1.1
> Host: localhost:8080
> User-Agent: curl/7.43.0
> Accept: */*
> Authorization: Bearer eyAidHlwIjogIkpXVCIsICJraWQiOiAiU3lsTEM2Tmp0MUtHUWt0RDlNdCswemNlUVNVPSIsICJhbGciOiAiUlMyNTYiIH0.eyAiYXRfaGFzaCI6ICJUcUd5c2dRZURsWDhIOFNHR1FjcEF3IiwgInN1YiI6ICJhcGlVc2VyIiwgImlzcyI6ICJodHRwOi8vdmJoYWxlcmEub3NlY2xvdWQuY29tOjgwODAvb3BlbmFtL29hdXRoMi9pbnRlcm5hbCIsICJ0b2tlbk5hbWUiOiAiaWRfdG9rZW4iLCAibm9uY2UiOiAiMTIzNCIsICJhdWQiOiBbICIyMTY1N2IyZCIgXSwgIm9yZy5mb3JnZXJvY2sub3BlbmlkY29ubmVjdC5vcHMiOiAiNjk2YmRlNTYtZmNiZi00ZTFkLWIzOGItYmMzNzQ4OGVhODRiIiwgImF6cCI6ICIyMTY1N2IyZCIsICJhdXRoX3RpbWUiOiAxNTE2OTE3NTQwLCAicmVhbG0iOiAiL2ludGVybmFsIiwgImV4cCI6IDE1MTY5MjEyMzUsICJ0b2tlblR5cGUiOiAiSldUVG9rZW4iLCAiaWF0IjogMTUxNjkxNzYzNSB9.SuYI1tP5uJ94y8XRc6QQClXlmuLzMFEcE1LlW_31GafXv91jg3QwbRI-1RV1XOISfWnLW7l-1eGyKZtK_P8nroLjXYs2c-HrIgTwK16FBTcM9-Gt_jzbntwN4hiLD4PbhVb562fTkdqQCA4ZlNR9QOmQUE0ZKlMSwB3b0bNSmys
< HTTP/1.1 200 OK
< Server: openresty/
< Date: Thu, 25 Jan 2018 22:03:31 GMT
< Content-Type: application/json
< Content-Length: 1480
< Connection: keep-alive
< Cache-control: private
< Set-Cookie: d8c1dd0e39ac4456ed39ce5889b9a5a5=e3380f4380dfce29d71b1a31cd3dd973; path=/; HttpOnly
< Vary: Origin
< X-Content-Type-Options: nosniff
  "method": "GET",
  "path": "/subscriptions",
  "args": "",
  "body": "",
  "headers": {
    "HTTP_VERSION": "HTTP/1.1",
    "HTTP_HOST": "",
    "HTTP_ACCEPT": "*/*",
    "HTTP_AUTHORIZATION": "Bearer eyAidHlwIjogIkpXVCIsICJraWQiOiAiU3lsTEM2Tmp0MUtHUWt0RDlNdCswemNlUVNVPSIsICJhbGciOiAiUlMyNTYiIH0.eyAiYXRfaGFzaCI6ICJUcUd5c2dRZURsWDhIOFNHR1FjcEF3IiwgInN1YiI6ICJhcGlVc2VyIiwgImlzcyI6ICJodHRwOi8vdmJoYWxlcmEub3NlY2xvdWQuY29tOjgwODAvb3BlbmFtL29hdXRoMi9pbnRlcm5hbCIsICJ0b2tlbk5hbWUiOiAiaWRfdG9rZW4iLCAibm9uY2UiOiAiMTIzNCIsICJhdWQiOiBbICIyMTY1N2IyZCIgXSwgIm9yZy5mb3JnZXJvY2sub3BlbmlkY29ubmVjdC5vcHMiOiAiNjk2YmRlNTYtZmNiZi00ZTFkLWIzOGItYmMzNzQ4OGVhODRiIiwgImF6cCI6ICIyMTY1N2IyZCIsICJhdXRoX3RpbWUiOiAxNTE2OTE3NTQwLCAicmVhbG0iOiAiL2ludGVybmFsIiwgImV4cCI6IDE1MTY5MjEyMzUsICJ0b2tlblR5cGUiOiAiSldUVG9rZW4iLCAiaWF0IjogMTUxNjkxNzYzNSB9.SuYI1tP5uJ94y8XRc6QQClXlmuLzMFEcE1LlW_31GafXv91jg3QwbRI-1RV1XOISfWnLW7l-1eGyKZtK_P8nroLjXYs2c-HrIgTwK16FBTcM9-Gt_jzbntwN4hiLD4PbhVb562fTkdqQCA4ZlNR9QOmQUE0ZKlMSwB3b0bNSmys",
    "HTTP_USER_AGENT": "curl/7.43.0",
    "HTTP_X_3SCALE_PROXY_SECRET_TOKEN": "secret_token_vinay_demo",
    "HTTP_X_REAL_IP": "",
    "HTTP_X_FORWARDED_PROTO": "https",
    "HTTP_FORWARDED": "for=;;proto=https"
  "uuid": "4b100977-4b31-4dc7-9b45-bf5dadb50d97"
* Connection #0 to host localhost left intact

Thanks for taking the time and reading this tutorial. In my next blog post, I will cover how to integrate 3scale by Red Hat with PingFederate using OpenID Connect.


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://{}/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} 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}{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}" -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”


3Scale Developer Portal Docs Per Application

Having Swagger Documentation in any developer portal is very important for developers to know how to use APIs.  However, not all developers may be using the same applications.  How can you make it so developers only see the docs relevant to them?  Luckily some JavaScript magic can make this possible for the 3Scale developer portal.

Continue reading “3Scale Developer Portal Docs Per Application”


3scale Developer Portal signup flows

There are 4 custom signup flows in this example parent homepage. As all the flows are separated into each partial you can include them into the homepage using Liquid tags as shown in this snippet: {% include 'partial name' %}. You can include the partials into your 3scale developer portal individually or all together. It depends on which flows you want to enable in your portal and to make it easier to switch between flows in the future with minimum fuss.

NOTE: If you prefer you can create a separate page to host the Plan subscription forms. This is particularly useful if you want to allow multiple applications per account for the Custom Field & Group Membership Flows.

Continue reading “3scale Developer Portal signup flows”


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”