Subject: [Id-event] Syntax of an event

From: Justin Richer <[email-masked]>
Date: Wed, 26 Oct 2016 07:32:39 -0700

In the session at IIW yesterday, there was a discussion on the event syntax in the current proposed draft. A few of us (myself included) questioned the current structure which is something like this:

   {
     "jti": "3d0c3cf797584bd193bd0fb1bd4e7d30",
     "events":[
       "urn:ietf:params:scim:event:passwordReset",
       "https://example.com/scim/event/passwordResetExt"
     ],
     "iat": 1458496025,
     "iss": "https://scim.example.com",
     "aud":[
       "https://jhub.example.com/Feeds/98d52461fa5bbc879593b7754",
       "https://jhub.example.com/Feeds/5d7604516b1d08641d7676ee7"
     ],
     "sub":"https://scim.example.com/Users/44f6142df96bd6ab61e7521d9",
     "urn:ietf:params:scim:event:passwordReset":{
       "id":"44f6142df96bd6ab61e7521d9"
     },
     "https://example.com/scim/event/passwordResetExt":{
        "resetAttempts":5
     }
   }

To get the above information, I need to walk through the values in the “events” array and then look for those values as members of the root JSON object to see if they have data. Instead, I’d like to raise an alternative way to codify the same event in a way that I believe will be more easily understandable by implementors and easier to parse by both humans and code. Namely, skip the array definition and build out the event above like so:

   {
     "jti": "3d0c3cf797584bd193bd0fb1bd4e7d30",
     "events”: {
        "urn:ietf:params:scim:event:passwordReset":{
          "id":"44f6142df96bd6ab61e7521d9"
        },
        "https://example.com/scim/event/passwordResetExt":{
           "resetAttempts":5
        }
     },
     "iat": 1458496025,
     "iss": "https://scim.example.com",
     "aud":[
       "https://jhub.example.com/Feeds/98d52461fa5bbc879593b7754",
       "https://jhub.example.com/Feeds/5d7604516b1d08641d7676ee7"
     ],
     "sub":"https://scim.example.com/Users/44f6142df96bd6ab61e7521d9"
   }
With this syntax, I need to loop through the keys of the “events” object and don’t need to reference anything else in the root object. This is *much* easier to code, and it enforces that each event key appear only once. Plus it keeps event information out of the root of the JWT, which has been shown (with JAR, dynamic registration’s software statements, and a couple others) to be problematic at times.

An argument for the current syntax is that it can handle event types that don’t have any additional payload. While I don’t think I’ve seen a concrete example of one yet (I might just be missing it), we can still handle that in this syntax in a number of ways. First, we could just use an empty object when there are no arguments.

     "events”: {
        "urn:ietf:params:scim:event:passwordReset":{}
     },

Second, we could just use “null”, which OpenID Connect uses in the “claims” object:

     "events”: {
        "urn:ietf:params:scim:event:passwordReset”:null
     },

Or a stand-in value like the “true” boolean:

     "events”: {
        "urn:ietf:params:scim:event:passwordReset”:true
     },

I prefer the first as it doesn’t change the expected object model for all claims, and it also takes fewer characters on the wire (not by much, so that’s not a driving factor, but with a lot of these saving a couple bytes won’t hurt). 

 — Justin

---

From: Brian Campbell <[email-masked]>
Date: Wed, 26 Oct 2016 11:50:52 -0500

I've just been loosely following the id event stuff but must admit I've
previously wondered why there was the events array that referenced other
claims/entries at the root. Nesting the related event information alongside
the event as Justin has suggested seems more natural and straightforward.
It's more compact too as the URI for each event isn't duplicated.

Was there some specific reasoning behind the current syntax?

On Wed, Oct 26, 2016 at 9:32 AM, Justin Richer <[email-masked]> wrote:

> In the session at IIW yesterday, there was a discussion on the event
> syntax in the current proposed draft. A few of us (myself included)
> questioned the current structure which is something like this:
>
>
>    {
> To get the above information, I need to walk through the values in the
> “events” array and then look for those values as members of the root JSON
> object to see if they have data. Instead, I’d like to raise an alternative
> way to codify the same event in a way that I believe will be more easily
> understandable by implementors and easier to parse by both humans and code.
> Namely, skip the array definition and build out the event above like so:
>
>    {
> With this syntax, I need to loop through the keys of the “events” object
> and don’t need to reference anything else in the root object. This is
> *much* easier to code, and it enforces that each event key appear only
> once. Plus it keeps event information out of the root of the JWT, which has
> been shown (with JAR, dynamic registration’s software statements, and a
> couple others) to be problematic at times.
>
> An argument for the current syntax is that it can handle event types that
> don’t have any additional payload. While I don’t think I’ve seen a concrete
> example of one yet (I might just be missing it), we can still handle that
> in this syntax in a number of ways. First, we could just use an empty
> object when there are no arguments.
>
>      "events”: {
> I prefer the first as it doesn’t change the expected object model for all
> claims, and it also takes fewer characters on the wire (not by much, so
> that’s not a driving factor, but with a lot of these saving a couple bytes
> won’t hurt).
>
>  — Justin
>
> _______________________________________________
> Id-event mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/id-event
>

---

From: Phil Hunt <[email-masked]>
Date: Wed, 26 Oct 2016 10:05:48 -0700

The history was evolved from SCIM which was trying to maintain some backwards compatibility when extensions were introduced.

I must confess I hadn’t really thought of the optimization and open to changing it if the group thinks a new format would be better. It would be helpful if some could check with issues with JWT libraries and any limitations that might be present - with any design including the current one.

The one concern I do have is I believe *most* events *should* just have a type and a “sub” value. Having to use a “null” to make this work, seems awkward.

We *really* want to encourage event designers to keep payload data to a minimum (ideally none). The objective is not to enable RPC functionality AND to avoid PII problems that would ensue.  “Less is more” is my thinking.   

Phil

@independentid
www.independentid.com <http://www.independentid.com/>[email-masked] <mailto:[email-masked]>

> On Oct 26, 2016, at 9:50 AM, Brian Campbell <[email-masked]> wrote:
> 
> I've just been loosely following the id event stuff but must admit I've previously wondered why there was the events array that referenced other claims/entries at the root. Nesting the related event information alongside the event as Justin has suggested seems more natural and straightforward. It's more compact too as the URI for each event isn't duplicated. 
> 
> On Wed, Oct 26, 2016 at 9:32 AM, Justin Richer <[email-masked] <mailto:[email-masked]>> wrote:
>        "https://example.com/scim/event/passwordResetExt <https://example.com/scim/event/passwordResetExt>"
>      ],
>      "iat": 1458496025,
>      "iss": "https://scim.example.com <https://scim.example.com/>",
>      "aud":[
>        "https://jhub.example.com/Feeds/98d52461fa5bbc879593b7754 <https://jhub.example.com/Feeds/98d52461fa5bbc879593b7754>",
>        "https://jhub.example.com/Feeds/5d7604516b1d08641d7676ee7 <https://jhub.example.com/Feeds/5d7604516b1d08641d7676ee7>"
>      ],
>      "sub":"https://scim.example.com/Users/44f6142df96bd6ab61e7521d9 <https://scim.example.com/Users/44f6142df96bd6ab61e7521d9>",
>      "https://example.com/scim/event/passwordResetExt <https://example.com/scim/event/passwordResetExt>":{
>         "resetAttempts":5
>      }
>    }
> 
>         "https://example.com/scim/event/passwordResetExt <https://example.com/scim/event/passwordResetExt>":{
>            "resetAttempts":5
>         }
>      },
>      "iat": 1458496025,
>      "iss": "https://scim.example.com <https://scim.example.com/>",
>      "aud":[
>        "https://jhub.example.com/Feeds/98d52461fa5bbc879593b7754 <https://jhub.example.com/Feeds/98d52461fa5bbc879593b7754>",
>        "https://jhub.example.com/Feeds/5d7604516b1d08641d7676ee7 <https://jhub.example.com/Feeds/5d7604516b1d08641d7676ee7>"
>      ],
>      "sub":"https://scim.example.com/Users/44f6142df96bd6ab61e7521d9 <https://scim.example.com/Users/44f6142df96bd6ab61e7521d9>"
>    }
> [email-masked] <mailto:[email-masked]>
> https://www.ietf.org/mailman/listinfo/id-event <https://www.ietf.org/mailman/listinfo/id-event>
>

---

From: Marius Scurtescu <[email-masked]>
Date: Wed, 26 Oct 2016 10:13:33 -0700

We are working on an early implementation and we looked at several events
(password change, session revoked, token revoked, account suspended,
account restored) and so far only the event type was needed, If this turns
out to be the norm then the current design is the less verbose one.

That being said, I don't see a big issue with the solutions proposed by
Justin, other than the concern raised by Phil that encouraging rich
payloads may not be a good idea.

Marius

On Wed, Oct 26, 2016 at 10:05 AM, Phil Hunt <[email-masked]> wrote:

> The history was evolved from SCIM which was trying to maintain some
> backwards compatibility when extensions were introduced.
>
> I must confess I hadn’t really thought of the optimization and open to
> changing it if the group thinks a new format would be better. It would be
> helpful if some could check with issues with JWT libraries and any
> limitations that might be present - with any design including the current
> one.
>
> The one concern I do have is I believe *most* events *should* just have a
> type and a “sub” value. Having to use a “null” to make this work, seems
> awkward.
>
> We *really* want to encourage event designers to keep payload data to a
> minimum (ideally none). The objective is not to enable RPC functionality
> AND to avoid PII problems that would ensue.  “Less is more” is my thinking.
>
>
> Phil
>
> @independentid
> www.independentid.com
> [email-masked]
>
>
>
>
>