WebHook Notifications and API

[ErmakovDmitriy]

Is your feature request related to a problem? Please describe. Currently, when I checked v1, it is possible to configure "internal notifications" and "email notifications".

Sometimes, it is necessary to do extra actions based on an event, my situation is: when a User is created, a script should run to create the user's home directory in a shared storage, populate it with default files (i.e. .bashrc etc) and chown the new directory to the new User.

I assume that it is possible to do even now by a way: Email Notification => Postfix SMTP Relay => Script handler (Postfix allows running scripts on some events as I remember).

but it might be a convenient feature to run a Service which is listening on some port and does actions based on events.

Describe the solution you'd like I think that a possible solution could be:

• Define web hooks with properties:
  • Verify CA (to be able to ignore TLS errors in some cases)
  • URL
  • Request method: POST, GET, etc.
  • Additional Headers: key-value fields - to provide a means for some authentication, like Authorization: Basic XXX or Authorization: Bearer YYY. This should be opaque from the perspective of BLAZAM. I mean, BLAZAM should just add these headers to the request.

For each event (Create, Update, Delete of an Active Directory User or Group) send in the HTTP request body a JSON (probably) like:

{
  "event": "create", // change, delete.
  "object_type": "User", // or Group
  "timestamp": " RFC 3339 time string",
  "object_name": "username or group name",
  "actor": "username of a person who performed the action"
}

In addition to that, for a User it might be a good idea to include extra fields:

{
  "first_name": "First Name",
  "middle_name": "Middle Name",
  "last_name": "Last Name",
  // Extra fields like "City", "Department" which are defined for the user.
  "groups": ["group1", "group2"] // List of groups the User belongs to.
}

Additional context The description above is probably "too much". For my case, it is enough to have a WebHook which will send just:

{
  "object_type": "User", // or "Group"
  "object_name": "username or group name"
}

as other fields are easy to get from the LDAP server in which this Object is modified.

The idea about adding the extra fields like actor, timestamp etc is not important for me but I think it might be useful for people who want to have some audit backend.

[jacobsen9026]

As always, an excellent feature suggestion.

I was waiting until v1.0 before working on any external integrations (API/Webhooks), obviously that time has come.

I don't use webhooks personally or professionally, so having a well written use case of what you need and how you want it to behave is incredibly helpful.

This can be implemented into Blazam relatively easily.

I need to update the documentation with the other features first before I forget but this feature would arguably warrant v1.1

Thank you.

[jacobsen9026]

FYI, this is second on the plate after a prior user's feature suggestion for "Request for assign access" on groups. As you probably can tell, most of my available time to work on these additions is over the weekends. I can't currently provide an eta but I would hope it's three weeks or less.

[ErmakovDmitriy]

Thank you for your help!

[jacobsen9026]

Work on this is about to begin, I apologize for the delay, access request notifications have taken slightly longer than anticipated to plan out. Planning is done and actual working code is now underway. Thankfully, there is very little planning required for WebHooks, and I am debating introducing the beginnings of an API alongside the WebHook update for even greater integration capability, just not 100% sure if anyone is ready for an actual API and would implement it in their own software.

eg: https://blazam.org/api/v1/users/create/[TemplateID] Form data: JSON body with Field variables and values { "Description": "A Description", "Groups" :{"Group1","Group2"}, "Manager": "My Manager" }

Shooting for Sunday on completion of notification WebHooks.

[jacobsen9026]

Shooting for Sunday on completion of notification WebHooks.

Or start...

[jacobsen9026]

@barroei1981 Continue API discussion here

At the very least....

Endpoint	Parameter	FormData
/api/v1.0/template/execute/[Parameter]	Template ID	JSON formatted required fields and values

[jacobsen9026]

Webhooks development has begun, I'm going to follow https://github.com/standard-webhooks/standard-webhooks/blob/main/spec/standard-webhooks.md in regards to webhook formatting.

[jacobsen9026]

API tokens and a couple basic endpoints have been created and are functional.

Eg: Endpoint - https://localhost/api/v1/search?query=goodman Authorization - Bearer Token generated in app Response

Eg: Endpoint - https://localhost/api/v1/test Authorization - Bearer Token generated in app Response

[jacobsen9026]

Progress Update: API Tokens modal showing token management.

[jacobsen9026]

Untested, but webhooks have been implemented at the most basic level in the dev branch.

Edited, already forgot to follow the standard I picked.

         Dictionary<string, object?> payload = new(){

{ "timestamp", DateTime.UtcNow.ToString() }, { "type", notificationType.ToString() } }; Dictionary<string, object?> data = new() { { "actor", actor?.Username }, // Use ?. to handle null actor { "object", target?.CanonicalName }, // Use ?. to handle null target { "objectDN", target?.DN }, // Use ?. to handle null target { "objectType", target?.ObjectType.ToString()}, // Use ?. to handle null target }; payload.Add("data", data);

As always, improvements to come.

[ErmakovDmitriy]

Hi! Thank you!

Could you, please, when you have time, point me (or describe) how I can "notify" an external system when BLAZAM changes/creates a User?

[jacobsen9026]

Hi @ErmakovDmitriy,

It's not quite ready for stable release so it's not available by default yet. If you really want to try it early, I would recommend switching to the nightly branch in your installation's update settings.

This feature will hit the nightly branch later today, and being on the dev branch is generally a bad idea unless you know how Blazam works internally. I would still backup the database before switching to nightly, and be prepared to lose any changes made in nightly, in case a database update rollback has to occur before stable release.

I will be testing the webhook notifications today as well to validate it's functionality. I also need to add lots of detailed auditing of these transmissions since it is invisible to the webapp user, and there would be no way to troubleshoot errors.

Lastly I need to complete documentation before it can be released on the stable branch.

[jacobsen9026]

in case a database update rollback has to occur before stable release

There is a high probability of a database rollback, >90%.

[ErmakovDmitriy]

Thank you. I will wait then.

[jacobsen9026]

Thank you. I will wait then.

Probably the best decision.

Heck, I'm not even gonna be ready for a nightly for at least half a day as it stands.

This turned out a bit more complicated than I originally anticipated, in regards to security, resiliency, troubleshooting by the end user.

[jacobsen9026]

Let me know if you see anything you would change in these example webhook messages...

[jacobsen9026]

Besides separating assign and unassign, I already have that desire myself.

[ErmakovDmitriy]

Hi Chris,

It looks very nice to me.

The fields which are needed to build integration with external systems are there (distinguished name of the modified objects). Thank you!

// Dmitrii.

On Sat, 23 Nov 2024, 00:34 Chris Jacobsen, @.***> wrote:

Besides separating assign and unassign, I already have that desire myself.

— Reply to this email directly, view it on GitHub https://github.com/Blazam-App/BLAZAM/issues/585#issuecomment-2495098178, or unsubscribe https://github.com/notifications/unsubscribe-auth/ABOCVF26H5PH2D7XCQ3HSQD2B65QLAVCNFSM6AAAAABQJTZVJCVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDIOJVGA4TQMJXHA . You are receiving this because you were mentioned.Message ID: @.***>