Open Service Broker reference application

Overview

Every service onboarding into the IBM Cloud Catalog is required to build a Broker application that follows the Open Service Broker (OSB) specification.

This project provides:

• a NodeJs based OSB broker reference application that is capable of basic provisioning and deprovisioning of a service on IBM Cloud
• a Docker container image of the OSB broker app which one could deploy in a serverless environment

Note that this broker is not production ready. It to be used as a starter or reference to help you build your production ready Broker.

Running the code

Prerequisites

To run Broker application in development you will need:

• Docker Desktop or an alternative (e.g. Rancher)
• yarn
• NodeJs, install using nvm or a method of your choosing

Development

1. Configure the environment variables using a .env file, template a template example is provided with the repo.
2. Start the application using the following commands:

yarn install
docker compose up

Deployment

You can deploy this application using Code Engine.

Role of a OSB Broker

The general role of OSB is described in the specification and elaborated in an IBM Cloud specific context here.

Resource Controller integration

On IBM Cloud, the platform subsystem responsible for managing the lifecycle of service instances is the Resource Controller (RC). Your Broker will accept requests from the Resource Controller at certain lifecycle events (i.e. provisioning, deprovisioning, etc.). To configure where the platform can reach your Broker using which credentials, you will use Partner Center Sell

Metering (optional)

Some implementers choose to submit the usage data of the service instances using the their Broker. To do this, the implementer must submit their metering data int the appropriate format to IBM Cloud's Metering API.

Implementation details

Authentication methods

Incoming requests from IBM Cloud's Resource Controller towards your Broker can use can use either basic or bearer authentication, depend on how you configured your Broker registration with IBM Cloud and your application.

Basic

The OSB spec requires that the Broker supports authentication with the HTTP basic method.

To configure this authentication method, head over to Partner Center Sell, find your broker and configure your broker according to these instructions and pick auth_scheme: basic.

To configure this application to accept a basic authentication credential use the environment variables:

BROKER_BASIC_USERNAME=myUsername
BROKER_BASIC_PASSWORD=myPassword

Bearer JWT

With this extension of the spec, the requests from IBM Cloud will use a JWT token. This JWT token will belong to an IAM ID (e.g. user or service Id) of your choosing.

To configure this authentication method, ead over to Partner Center Sell, find your broker and configure your broker according to these instructions and pick auth_scheme: bearer and in the password field provide an API key belonging to the ID of your choosing.

To configure the application to accept requests from a set of IBM Cloud IAM Ids, use the environment variables:

# BROKER_BEARER_IDENTITIES accepts a comma separated list of IAM IDs
BROKER_BEARER_IDENTITIES=iam-ServiceId-e2b83083-cfef-40ee-8185-1f1332afaa1f

Cloud resource name JWT

With this extension of the spec, the requests from IBM Cloud will use a JWT token. This JWT token will belong to your broker's cloud resource name.

To configure this authentication method, ead over to Partner Center Sell, find your broker and configure your broker according to these instructions and pick auth_scheme: bearer-crn.

To configure the application to accept requests from a set of IBM Cloud IAM Ids, use the environment variables:

# BROKER_BEARER_IDENTITIES accepts a comma separated list of IAM IDs
BROKER_BEARER_IDENTITIES=crn-crn:v1:bluemix:public:resource-controller::a/f71446b6474d45bf81196da45de13940::resource-broker:1f4a9711-e359-4e00-8ad3-c8bfd38446b3