This project is a framework to ease the use of WebHooks with 3scale. It also provides out-of-the-box a sample implementation that synchronizes 3scale applications with Red Hat SSO clients (useful if you are implementing OAuth).

If you are interested only in the app/client synchronization between 3scale and Red Hat SSO, follow the instructions below.

First of all, Red Hat SSO needs to be deployed with the SSO_SERVICE_USERNAME, SSO_SERVICE_PASSWORD and SSO_REALM environment variables. If not already done, update your DeploymentConfig:

oc set env dc/sso SSO_SERVICE_USERNAME=cli
oc set env dc/sso SSO_SERVICE_PASSWORD=secret
oc set env dc/sso SSO_REALM=3scale
oc rollout latest sso

This will create a realm named 3scale, containing a user cli that has administrative privileges on this realm.

NOTE: If you created the realm by yourself, you have to create a user that has administrative privileges over this realm. Alternatively, you can use the built-in admin user but you have to be aware that the admin user lays in the master realm. So you will have to pass the SSO_AUTH_REALM environment variable accordingly (see below).

Then, you can instantiate this project:

oc new-app https://github.com/nmasse-itix/3scale-webhooks-sample.git --strategy=source --name=webhooks -e SSO_REALM=3scale -e SSO_HOSTNAME=your.sso.hostname -e SSO_SERVICE_USERNAME=cli -e SSO_SERVICE_PASSWORD=secret -e SSO_CLIENT_ID=admin-cli -e SHARED_SECRET=supersecret -e WEBHOOKS_MODULES=log,sso
oc expose service webhooks

The possible environment variables are explained below:

Then, in the 3scale admin console, go to Settings > Web Hooks. In the URL field, type in the URL of the webhooks route you created before, followed by /webhooks. If you defined a shared secret, append ?shared_secret=<your_shared_secret>

For instance:

https://webhooks-3scale.app.openshift.test/webhook?shared_secret=supersecret

Do not forget to enable Webhooks and check Dashboard actions fire webhooks !

You can use the built-in admin user as a service account to authenticate in Red Hat SSO. However, since the admin user lays in the master realm, you have to deploy this project with one additional environment variable: SSO_AUTH_REALM.

For instance, if you want to create clients in the 3scale realm and you want to use the default admin user to do this, you will have to use the following variables:

SSO_SERVICE_USERNAME=admin
SSO_SERVICE_PASSWORD=secret
SSO_AUTH_REALM=master
SSO_REALM=3scale

If you prefer not to use the admin user of the master realm, you can create an admin user in the target realm (let's say, the realm 3scale). Then, reset his password (make sure the "temporary password" option is NOT checked) and give him the administrative rights.

To give him the administrative rights :

• go to the Role Mapping tab of your admin user
• under Client Roles, select realm-management
• pick the manage-clients role on the left pane
• click Add selected >> to give those administrative rights to your admin user

Since your admin user is in the same realm as your clients, you can remove the SSO_AUTH_REALM environment variable.

If you plan to develop a module, you will have to export three methods from your module :

• init
• register
• handle

The init method can be used to initialize your module, such as reading configuration, initializing variables, etc.

The register method is used to choose the kind of webhooks you want to receive. To do this, you have to filter the list of available webhooks that you receive as a parameter and return the filtered list.

Currently, available types are :

• application
• account
• user

The handle method is called when a webhook is received.

See the log.js file that provides a minimal example of a working module.

Note that there might be multiple modules loaded to handle the same webhooks, so you have to take care of calling the next module in the chain. This is easy, just make sure in all cases (error or success), you call next().

If you developed a custom module, the easiest way is to fork this repository, make your changes, commit your custom module and deploy it in OpenShift using S2I (as explained above).

You just have to change the WEBHOOKS_MODULES environment variable to add your module to the list (or replace it completely):

oc set env dc/webhooks WEBHOOKS_MODULES=your_custom_module

But, if you do not want to fork this repository, you can install your module using ConfigMap.

Let's say you developed a module named test in a file test.js, you can deploy it like so:

oc create configmap custom-module --from-file=test.js
oc volume dc/webhooks --add -m /opt/app-root/src/custom -t configmap --configmap-name=custom-module --name custom-module
oc set env dc/webhooks WEBHOOKS_MODULES=custom/test

If you need to debug or have a non-trivial development to do, it is easier to run NodeJS locally:

export SSO_REALM=3scale
export SSO_HOSTNAME=secure-sso-sso.app.openshift.test
export SSO_CLIENT_ID=admin-cli
export SSO_SERVICE_USERNAME=cli
export SSO_SERVICE_PASSWORD=secret
export SHARED_SECRET=supersecret
export WEBHOOKS_MODULES=log,sso
node server.js

You should get a fairly good amount of logs on the console output. If you need to debug a module, you can issue a GET on / to get information:

$ curl https://webhooks-3scale.app.openshift.test/
{
  "name": "3scale Sample Webhook",
  "description": "A sample project that handles 3scale webhooks",
  "endpoints": [
    {
      "url": "/webhook",
      "verbs": [
        "GET",
        "POST"
      ]
    }
  ],
  "documentation": {
    "GitHub": "https://github.com/nmasse-itix/3scale-webhooks-sample"
  },
  "handlersByType": {
    "application": [
      "log",
      "sso"
    ]
  },
  "handlersState": {
    "log": {
      "loaded": true,
      "initialized": true,
      "registered": true
    },
    "custom/test": {
      "loaded": false,
      "error": "a is not defined"
    },
    "sso": {
      "loaded": true,
      "initialized": true,
      "registered": true
    }
  }
}

In this example, you can see that the module custom/test cannot be loaded because of a parse error (a is not defined).