81 lines
3 KiB
Org Mode
81 lines
3 KiB
Org Mode
|
# Created 2021-09-03 Fri 16:49
|
||
|
|
#+TITLE: Cisco Notes
|
||
|
|
#+AUTHOR: Yann Esposito
|
||
|
|
* DI/CSC Webhooks
|
||
|
|
|
||
|
|
For DI:
|
||
|
|
|
||
|
|
1. everytime an admin log in, DI will check and create a webhook for its
|
||
|
|
org
|
||
|
|
2. everytime anyone of this org change a module instance the webhook is
|
||
|
|
triggered to inform DI a module instance changed.
|
||
|
|
|
||
|
|
The HTTP call will be auth by whatever mean is preferable.
|
||
|
|
Basic Auth is possible, as well as API Token or even =iroh-jwt=.
|
||
|
|
But =iroh-jwt= is not mandatory, this is up to DI.
|
||
|
|
|
||
|
|
For CSC:
|
||
|
|
|
||
|
|
1. We (the admins of IROH) create a global webhook
|
||
|
|
2. Everytime anyone from any org change a module instance the webhook is triggered
|
||
|
|
|
||
|
|
For CSC the webhook must be configured to use a client-id.
|
||
|
|
With a configured client-id, we will generate an access token (using the
|
||
|
|
iroh-auth implementation that will perform a lot of checks).
|
||
|
|
|
||
|
|
*Note*: As we want the webhook to work for every user, the client for CSC must be
|
||
|
|
trusted (by us admin). It means, that the access token creation will almost
|
||
|
|
always be successful.
|
||
|
|
|
||
|
|
*Warning*: If a =client-id= is configured then the *body* should contain a
|
||
|
|
field =access_token= with the built access token (the function
|
||
|
|
=gen-access-token-resp= should take care of this part of the body).
|
||
|
|
Note you might also potentially want to provide an =id_token= in the body.
|
||
|
|
|
||
|
|
*Remark*: It is important to separate the Authentication concern from the
|
||
|
|
data send by the webhook.
|
||
|
|
|
||
|
|
The webhooks should support different type of authentication that could
|
||
|
|
potentially be changed without affecting the content of the webhooks.
|
||
|
|
So the webhook should be able to use:
|
||
|
|
|
||
|
|
- basic-auth
|
||
|
|
- api token
|
||
|
|
- iroh-jwt
|
||
|
|
|
||
|
|
In order to use =iroh-jwt= the webhook MUST configure a client-id that will
|
||
|
|
be used to generate access tokens, ideally the client-id will have a
|
||
|
|
configured =audiences=.
|
||
|
|
I do not have an opinion on the subject, but I could imagine there could be
|
||
|
|
a decorelation between the =client-id= used to use a JWT to call the webhook
|
||
|
|
endpoint and the =client-id= that will be used to generate the access token
|
||
|
|
in the body.
|
||
|
|
I think using a single =client-id= in the webhook configuration is fine.
|
||
|
|
|
||
|
|
The important point being that, one should not expect the webhook endpoint
|
||
|
|
to use the access token in their Authentication header but only the access
|
||
|
|
token in the body.
|
||
|
|
|
||
|
|
Ideally, the webhook http call should contain as much information as
|
||
|
|
possible about the event.
|
||
|
|
Typically:
|
||
|
|
|
||
|
|
#+begin_src clojure
|
||
|
|
{:user {:user-id ,,, :user-email ,,,} ;; <- the person that triggered the event
|
||
|
|
:org {:id ,,,} ;; <- the org of the triggerrer
|
||
|
|
;; metas about the webhook itself so the endpoint know how to find/update/delete a webhook
|
||
|
|
:webhook-creator {:user {:user-id ,,,}
|
||
|
|
:org {:org-id ,,,}}
|
||
|
|
;; in case the webhook contain a client-id configuration the token generated via this client
|
||
|
|
:token {:access-token "...."
|
||
|
|
:token-type "bearer"
|
||
|
|
:scopes [,,,]
|
||
|
|
:expires_in 300}
|
||
|
|
;; the event type (I havent double check the schemas, but I guess there is somethign similar)
|
||
|
|
:type :module-instance-update
|
||
|
|
;; the details about the event
|
||
|
|
:data {:module-instance-id ,,,
|
||
|
|
:diff {,,,}}
|
||
|
|
}
|
||
|
|
#+end_src
|