The match and query rule together with and/or rules are flexible enough to solve most complex authorization logic out there. However, in certain edge cases, we need to write custom validation logic. That’s where the webhook rule comes into the picture.
The basic syntax for the webhook rule is:
{
"rule": "webhook",
"url": "<webhook-url>",
"store": "<variable to store the response>"
}
The webhook rule triggers an HTTP POST request on the URL specified in the rule.
The target service performs custom validation and responds accordingly. The webhook rule is resolved, only if the webhook target responds with status code 2xx.
You can optionally specify the variable to store the result of the webhook so that you can use the fields from the webhook response body in your other security rules like match.
The webhook request made by Space Cloud contains the following headers:
| Header field name | Header field value |
|---|---|
Content-Type |
application/json |
Authorization |
Bearer <token> |
x-sc-token |
Bearer <sc-access-token> |
The token is nothing but the token from the client. sc-access-token on the other hand is a token generated by Space Cloud itself so that the webhook target can verify whether the webhook source is Space Cloud only.
The request body to the webhook target is a JSON object containing all the variables available inside security rules for that particular operation.
For example, let’s say that you are writing a webhook rule for database create operation. The variables available for the database create operation are args.auth, args.token, args.doc. Thus your webhook target, in this case, would receive a JSON body similar to this:
{
"args": {
"auth": {
...token claims
},
"token": "<some-token>",
"doc": {
...fields of the document to be created
}
}
}
As a best practice, you should always verify that the incoming webhook request to your service is actually from Space Cloud only and not an intruder.
Space Cloud sends an access token in the headers of each webhook request to do so:
x-sc-token: Bearer <sc-access-token>The access token is generated by Space Cloud itself with the primary secret provided to it. You can check the primary secret from the Settings page of your project in Mission Control.
The access token contains the following claims:
{
"id": "<space-cloud-gateway-node-id>",
"role": "SpaceCloud"
}
To verify whether a webhook is coming from Space Cloud only, you can verify the access token with the primary secret. As an additional security step, you can also check the value of role inside the token claims.
Often while securing your remote services via the webhook rule, you might even want to forward the result of the webhook call to your remote service. You can do that easily by using the store field. Just point the store field to any variable inside the payload (args.params) of the remote service.
Example:
{
"rule": "webhook",
"url": "<webhook-url>",
"store": "args.params.foo"
}
args.params is nothing but a variable available in the security rules of remote services that contain the payload of the remote service call. (Check out the list of all available variables). Hence, storing the result in args.params.foo will make sure that the request payload to your remote service contains a field call `foo’, which is nothing but the response of your webhook request.
You can easily the transform the JWT claims and the body of the webhook request using Go templates. Check out the documentation of transformations to learn more about transformations in detail.
To specify the Go templates for JWT claims and request body, we need to configure the following fields in the webhook rule:
yaml|jsongo (Templating language. Currently only Go templates are supported.)To set the templates via security rule builder, check the Apply transformations option and provide the output format, JWT claims template and the request body template:
Have a technical question?
Improve the docs!
