Your browser is out-of-date!

Update your browser to view this website correctly. Update my browser now

Fresh Espresso & Open Source Cloud

I have a passion for all things open source. I live in Ipswich MA and work for Red Hat, on the fabric8 project. Fabric8 is a cloud micro-services platform so you can deploy your applications to an all open source cloud. I kayak on the Atlantic Ocean along the coastal North East from Massachusetts to Maine whenever I can.

Protect a Fabric8 REST Service with Apiman

Apiman is a API Management application that help you add policies to your service and set up and enforce contracts between service producers and consumers. Fabric8 is cloud infrastructure build on Kubernetes and Docker. Please follow these steps to get Apiman running on Fabric8. In this post I will show you how to deploy a REST quickstart to Fabric8 and how to publish it as a Public Service on the Apiman Gateway protected by Simple Authentication.

1. Deploy a REST based service to Fabric8

When Fabric8 is running follow these steps to deploy the CXFCDI quickstart

git clone
cd ipaas-quickstarts/quickstarts/java/cxf-cdi/
mvn clean install fabric8:json docker:build  fabric8:apply

When the build succeeds the CXFCDI service appears in the http://fabric8.vagrant.f8 console as shown below

CxfCdi quickstart running on Fabric8.

and you can access the endpoint in your browser at http://quickstart-java-cxf-cdi.vagrant.f8/quickstart-java-cxf-cdi/cxfcdi/, and http://quickstart-java-cxf-cdi.vagrant.f8/quickstart-java-cxf-cdi/cxfcdi/swagger.json for the swagger definition.


2. Publish the CxfCdi service to the Apiman Gateway

CxfCdi service listing.

You may notice there is no authentication required to use this REST service. The easiest way to add security or any other policies is to publish the service to the Apiman Gateway and to expose the gateway on your firewall. So let’s go ahead and publish the CxfCdi service as a Public Service. A Public Service is a service that consumers can use without having a Contract in place.

2.1. Add your Organization

If you don’t have an Organization already create one now by navigating to the API Management tab and clicking Create a new Organization. Create your Organization.

2.2. Import Services

Within your Organization select Services and then click on the little dropdown next to the New Service button. Click on the Import Service popup to enter the Import Services wizzard.

Service import.

This wizzards allows you to bulk-import service endpoints by doing a lookup in Kubernetes. At this point it is worth mentioning that the following Kubernetes Service Annotations are used to find the service and swagger endpoint, which are defined as properties in the service pom (More on that in a different blog post):


In the Find Services searchbox type 'quickstart' to find the quickstarts in the current namespace (or '*' for all services in the namespace). Then select to add the CxfCdi Quickstart, and when select the 'Public Service' check box (For this it’s ok that we don’t yet have any plans setup). Then click Finish and your new Service should show up under the list of Services for your Organization. Go ahead and click on the CxfCdi Service. You should now see that it found the service endpoint of our service in the implementation tab

service implementation.png

2.3. Swagger apidocs

Service implementation.

As mentioned above the CxfCdi service publishes a swagger.json service definition and this document that was imported by Apiman as shown in below

service definition.png
Service definition.

This swagger document is used to build the swagger editor page in Apiman.

2.4. Publish CxfCxf Service to the Gateway

At this point all we really need to do is to Publish the service to the gateway. So let’s click on the Publish button. In the leftnav an 'Endpoint' tab will now appear. This shows the URL under which the Gateway has now published the service. This should something like


3. Protect the CxfCdi service with a Policies

We now have a the service published on gateway however it is still not protected in any way! We need to add an authentication policy to make this happen. Since the service is already published we need to create a new version of this service in Apiman. So let’s create version 1.1.

3.1. Add Simple Auth Policy

Under version 1.1 we on Policies tab we can now click on the Add Policy button. On the policy screen select the BASIC Authentication Policy and for the realm set 'quickstart', set a check in the Basic Auth required checkbox and select a 'Static' identity source. Finally type 'admin' in both the Username and Password box and click 'Add' and 'Add Policy'. Now you should have a BASIC Authentication Policy.

service policy.png

3.2. Publish version 1.1

Service policy.

Finally we need to publish version 1.1 of this service, so go ahead and click on 'Publish', the endpoint of this version on the gateway should now be something like


and when you hit it with your browser it should pop a Basic Auth 'Authentication Required'.

basic auth.png
Basic Authentication.

Providing it with the credentials we set above (admin/admin), it should let us in.

3.3. Retire version 1.0

Note that the service endpoint for version 1.0 still works. You can select version 1.0 in Apiman and click on 'Retire' to disable the unprotected version 1.0 endpoint.

3.4. Add a Rate Limiting Policy

What if in addition to the BASIC Auth Policy we want to have a Rate Limiting Policy in place? Simple create version 1.2 of this service and add this policy. In the Policy screen for this policy set '5 requests' per 'service' per 'minute'. Click 'Add Policy' and see that you now have two policies on this service.

two policies.png
Add a Rate Limiting Policy.

On this screen you can also changes the order in which these policies are applied. When you are happy click 'Publish' to bring up the endpoint for this version on the gateway. When you use this end point more then 5 times in minute, it should return a nice JSON payload saying something like

  type: "Other",
  failureCode: 10005,
  responseCode: 429,
  message: "Rate limit exceeded.",
  headers: {
    X-RateLimit-Limit: "5",
    X-RateLimit-Remaining: "-1",
    X-RateLimit-Reset: "19"

This condition will be cleared when you wait 19 more seconds. Don’t for get to retire version 1.1 of the service (unless you have a good reason not to).

4. Conclusion

We’ve shown how to publish a service on the gateway and how to apply policies. We’ve applied both a Basic Auth and a Rate limiting Policy. The service in question was published as a Public Service which means it does not discriminate application of te policies based on 'who is calling'. If you do need to discriminate then you will need to set up Plans and Contracts. We will talk about that in a differnet post so stay tuned!



About the author

Kurt Stam


comments powered by Disqus