From 273a01697ab1e9bccf51378d6aa6782b6422dc6b Mon Sep 17 00:00:00 2001 From: Tim Cappalli Date: Thu, 6 Jun 2024 15:05:52 -0400 Subject: [PATCH 01/13] initial eventdef skeleton --- ...haredsignals-eventdef-specification-1_0.md | 109 ++++++++++++++++++ 1 file changed, 109 insertions(+) create mode 100644 openid-sharedsignals-eventdef-specification-1_0.md diff --git a/openid-sharedsignals-eventdef-specification-1_0.md b/openid-sharedsignals-eventdef-specification-1_0.md new file mode 100644 index 0000000..66853d8 --- /dev/null +++ b/openid-sharedsignals-eventdef-specification-1_0.md @@ -0,0 +1,109 @@ +--- +title: OpenID Shared Signals Event Definition Specification +abbrev: SSFEvents-Spec +docname: openid-sharedsignals-eventdef-specification-1_0 +date: 2024-06-06 + +ipr: none +cat: std +wg: Shared Signals + +coding: us-ascii +pi: + toc: yes + sortrefs: yes + symrefs: yes + private: yes + +author: + - + ins: T. Cappalli + name: Tim Cappalli + org: Okta + email: tim.cappalli@okta.com + - + ins: A. Deshpande + name: Apoorva Deshpande + org: Okta + email: apoorva.deshpande@okta.com + - + ins: J. Schreiber + name: Jen Schreiber + org: Workday + email: jennifer.winer@workday.com + + + +normative: + OpenID.Core: + author: + - ins: N. Sakimura + name: Nat Sakimura + - ins: J. Bradley + name: John Bradley + - ins: M.B. Jones + name: Michael B. Jones + - ins: B. de Medeiros + name: Breno de Medeiros + - ins: C. Mortimore + name: Chuck Mortimore + date: November 2014 + target: http://openid.net/specs/openid-connect-core-1_0.html#IDToken + title: OpenID Connect Core 1.0 - ID Token + RFC2119: + RFC8174: + RFC5280: + RFC5646: + RFC6711: + RFC8176: + SSF: + target: http://openid.net/specs/openid-sse-framework-1_0.html + title: OpenID Shared Signals and Events Framework Specification 1.0 + author: + - + ins: A. Tulshibagwale + name: Atul Tulshibagwale + org: Google + - + ins: T. Cappalli + name: Tim Cappalli + org: Microsoft + - + ins: M. Scurtescu + name: Marius Scurtescu + org: Coinbase + - + ins: A. Backman + name: Annabelle Backman + org: Amazon + - + ins: John Bradley + name: John Bradley + org: Yubico + date: 2021-05 + +--- abstract + +This document defines how to define events for the Shared Signals Framework {{SSF}} using JSON Schema. + +blah blah add more + +--- middle + +# Introduction {#introduction} + +## Notational Considerations +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 {{RFC2119}} {{RFC8174}} when, and only when, they appear in all capitals, as shown here. + + +# Acknowledgements + +The authors wish to thank all members of the OpenID Foundation Shared Signals Working Group who contributed to the development of this specification. + +# Notices + +Copyright (c) 2024 The OpenID Foundation. + +The OpenID Foundation (OIDF) grants to any Contributor, developer, implementer, or other interested party a non-exclusive, royalty free, worldwide copyright license to reproduce, prepare derivative works from, distribute, perform and display, this Implementers Draft or Final Specification solely for the purposes of (i) developing specifications, and (ii) implementing Implementers Drafts and Final Specifications based on such documents, provided that attribution be made to the OIDF as the source of the material, but that such attribution does not indicate an endorsement by the OIDF. + +The technology described in this specification was made available from contributions from various sources, including members of the OpenID Foundation and others. Although the OpenID Foundation has taken steps to help ensure that the technology is available for distribution, it takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this specification or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any independent effort to identify any such rights. The OpenID Foundation and the contributors to this specification make no (and hereby expressly disclaim any) warranties (express, implied, or otherwise), including implied warranties of merchantability, non-infringement, fitness for a particular purpose, or title, related to this specification, and the entire risk as to implementing this specification is assumed by the implementer. The OpenID Intellectual Property Rights policy requires contributors to offer a patent promise not to assert certain patent claims against other contributors and against implementers. The OpenID Foundation invites any interested party to bring to its attention any copyrights, patents, patent applications, or other proprietary rights that may cover technology that may be required to practice this specification. From 77f865aa36a549a4cb9d64cd3864fcf3de13f75d Mon Sep 17 00:00:00 2001 From: Jen Schreiber Date: Wed, 21 Aug 2024 08:27:03 -0600 Subject: [PATCH 02/13] starting to scaffold properties --- ...haredsignals-eventdef-specification-1_0.md | 135 +++++++++++++++++- 1 file changed, 130 insertions(+), 5 deletions(-) diff --git a/openid-sharedsignals-eventdef-specification-1_0.md b/openid-sharedsignals-eventdef-specification-1_0.md index 66853d8..0151058 100644 --- a/openid-sharedsignals-eventdef-specification-1_0.md +++ b/openid-sharedsignals-eventdef-specification-1_0.md @@ -32,8 +32,6 @@ author: org: Workday email: jennifer.winer@workday.com - - normative: OpenID.Core: author: @@ -81,17 +79,144 @@ normative: name: John Bradley org: Yubico date: 2021-05 + informative: + JSONSchemaValidation: # would these two be normative? + target: https://json-schema.org/draft/2020-12/json-schema-validation + title: JSON Schema Validation: A Vocabulary for Structural Validation of JSON + author: + - ins: A. Wright + name: Austin Wright + - ins: H. Andrews + name: Henry Andrews + - ins: B. Hutton + name: Ben Hutton + JSONSchema: + target: https://json-schema.org/draft/2020-12/json-schema-core + title: JSON Schema: A Media Type for Describing JSON Documents + author: + - ins: A. Wright + name: Austin Wright + - ins: H. Andrews + name: Henry Andrews + - ins: B. Hutton + name: Ben Hutton + - ins: G. Dennis + name: Greg Dennis --- abstract -This document defines how to define events for the Shared Signals Framework {{SSF}} using JSON Schema. - -blah blah add more +This document defines how to describe events for the Shared Signals Framework {{SSF}} using JSON Schema. It specifies how to translate normative requirements for event types into JSON Schema vocabulary and the process to register and discover new schemas. --- middle # Introduction {#introduction} +Shared Signals Framework {{SSF}} enables sharing of signals and events between cooperating peers. {{SSF}} can be profiled for different applications as event types, such as Risk Incident Sharing and Coordination {{RISC}} and the Continuous Access Evaluation Profile {{CAEP}}. + +This specification defines how to translate normative SSF event requirements into a JSON Schema. JSON Schema is a standardized way to describe the structure, constraints, and data types within a JSON document. JSON Schemas can also be used as validators to automatically check if a JSON document adheres to the defined schema, ensuring data integrity. + +Using JSON Schema to describe SSF has three main benefits. First, it enables a faster process to create, update and get approval for new event types. Second, JSON schema, rather than spec texts, is a more appropriate format to describe event types. And lastly, it allows event types to be versioned independently thus reducing the friction between the SSF core specification and event type publication. + +# JSON Schema Defintion + +Schema keywords - Normative +Validation keywords - Normative +Schema annotations - Non-normative + + +\\$schema +: REQUIRED, JSON string: URI of the version of JSON Schema that this document adheres to. E.g., `https://json-schema.org/draft/2020-12/schema`. Normative Schema Keyword. + +\\$id +: REQUIRED, JSON string: URI of the schema. SHOULD be publicly accessible and resolve to the JSON Schema document. Normative Schema Keyword. + +title +: REQUIRED, JSON string: Title of the schema. Informational Schema Annotation. + +description +: REQUIRED, JSON string: Intent of the schema. Informational Schema Annotation. + +type +: REQUIRED JSON string: Defines the first constraint on the JSON data. MUST be "object". Normative Validation Keyword. + +properties +: REQUIRED JSON object: Object that defines the keys in the JSON data that are being validated. Normative Validation Keyword. + + +~~~ json +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.openid.net/secevent/caep/event-type/session-revoked/v1.schema.json", + "title": "Session Revoked", + "description": "Session Revoked signals that the session identified by the subject has been revoked. The explicit session identifier may be directly referenced in the subject or other properties of the session may be included to allow the receiver to identify applicable sessions.", + "type": "object", + "properties": {} + } +~~~ + +## Properties + + +> ### Open Questions: +> - Should the schema contain just validate the events claim in the SET? +> - Typically you'd use another JWT library to validate the top level claims like iss, aud, etc. + + +The top level "properties" key contains an object "where each property represents a key in the JSON data that’s being validated." (https://json-schema.org/learn/getting-started-step-by-step. Within each property, all normative requirements and non-normative details are specified, such as a description of the property, if its required, what values are allowed, etc. + +The properties key MUST follow the vocabulary specified in {{JSONSchemaValidation}} + +~~~json +{ + "properties": { + "initiating_entity": { + "description": "Describes the entity that invoked the event.", + "type": "string", + "oneOf": [ + { + "const": "admin", + "description": "an administrative action triggered the event" + }, + { + "const": "user", + "description": "an end-user action triggered the event" + }, + { + "const": "policy", + "description": "a policy evaluation triggered the event" + }, + { + "const": "system", + "description": "a system or platform assertion triggered the event" + } + ] + }, + "required": [ "initiating_entity" ] + } +} +~~~ + +# Schema for mandatory claims in SET + + +# Discoverability/Registry + +## Event Types + +| Event Type | Schema URI | +|------|-------------| +| CAEP | | +| RISC | | + +{: title="Name this table..." #eventtypestable} + +### CAEP + +### RISC + +# Process for raising PRs and getting approved + ## Notational Considerations The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 {{RFC2119}} {{RFC8174}} when, and only when, they appear in all capitals, as shown here. From 9782c11a91d182b61fa03bd805b9a57cee9a3aca Mon Sep 17 00:00:00 2001 From: Jen Schreiber Date: Wed, 21 Aug 2024 08:45:00 -0600 Subject: [PATCH 03/13] specify just event --- openid-sharedsignals-eventdef-specification-1_0.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/openid-sharedsignals-eventdef-specification-1_0.md b/openid-sharedsignals-eventdef-specification-1_0.md index 0151058..d91b0eb 100644 --- a/openid-sharedsignals-eventdef-specification-1_0.md +++ b/openid-sharedsignals-eventdef-specification-1_0.md @@ -119,6 +119,10 @@ Using JSON Schema to describe SSF has three main benefits. First, it enables a f # JSON Schema Defintion +JSON Schema Documents SHOULD define value of each event statement within the "events" claim of a JWT as defined in Section 2.2 of {{SET}} where the key (event URN) is $id of the JSON schema + +^^ not sure about this. how would the even URN relate to the schema $id? + Schema keywords - Normative Validation keywords - Normative Schema annotations - Non-normative From e290728bbf72fb3bbb17a0ed55b90948842d4eb6 Mon Sep 17 00:00:00 2001 From: Apoorva Deshpande Date: Tue, 27 Aug 2024 10:50:38 -0700 Subject: [PATCH 04/13] Updates to the spec --- openid-sharedsignals-eventdef-specification-1_0.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/openid-sharedsignals-eventdef-specification-1_0.md b/openid-sharedsignals-eventdef-specification-1_0.md index d91b0eb..ecddfe4 100644 --- a/openid-sharedsignals-eventdef-specification-1_0.md +++ b/openid-sharedsignals-eventdef-specification-1_0.md @@ -111,15 +111,19 @@ This document defines how to describe events for the Shared Signals Framework {{ # Introduction {#introduction} -Shared Signals Framework {{SSF}} enables sharing of signals and events between cooperating peers. {{SSF}} can be profiled for different applications as event types, such as Risk Incident Sharing and Coordination {{RISC}} and the Continuous Access Evaluation Profile {{CAEP}}. +Shared Signals Framework {{SSF}} enables sharing of signals and events between cooperating peers. It is currently leveraged by two applications – the Continuous Access Evaluation Protocol {{CAEP}} and Risk Incident Sharing and Coordination {{RISC}}. This specification defines how to translate normative SSF event requirements into a JSON Schema. JSON Schema is a standardized way to describe the structure, constraints, and data types within a JSON document. JSON Schemas can also be used as validators to automatically check if a JSON document adheres to the defined schema, ensuring data integrity. -Using JSON Schema to describe SSF has three main benefits. First, it enables a faster process to create, update and get approval for new event types. Second, JSON schema, rather than spec texts, is a more appropriate format to describe event types. And lastly, it allows event types to be versioned independently thus reducing the friction between the SSF core specification and event type publication. +Using JSON Schema to describe SSF has the following main benefits. +- Allows machine readability to auto generation of stubs +- It enables a faster process to create, update and get approval for new event types. +- JSON schema, rather than spec texts, is a more appropriate format to describe event types. +- It also allows event types to be versioned independently thus reducing the friction between the SSF core specification and event type publication. # JSON Schema Defintion -JSON Schema Documents SHOULD define value of each event statement within the "events" claim of a JWT as defined in Section 2.2 of {{SET}} where the key (event URN) is $id of the JSON schema +JSON Schema Documents MUST define value of each event statement within the "events" claim of a JWT as defined in Section 2.2 of {{SET}} where the key (event URN) is $id of the JSON schema ^^ not sure about this. how would the even URN relate to the schema $id? From 346eb7fae7211e790837041235fee602b03aa656 Mon Sep 17 00:00:00 2001 From: Jen Schreiber Date: Tue, 24 Sep 2024 10:20:00 -0600 Subject: [PATCH 05/13] fix terminology --- ...haredsignals-eventdef-specification-1_0.md | 29 +++++++------------ 1 file changed, 10 insertions(+), 19 deletions(-) diff --git a/openid-sharedsignals-eventdef-specification-1_0.md b/openid-sharedsignals-eventdef-specification-1_0.md index ecddfe4..463f3ff 100644 --- a/openid-sharedsignals-eventdef-specification-1_0.md +++ b/openid-sharedsignals-eventdef-specification-1_0.md @@ -115,7 +115,7 @@ Shared Signals Framework {{SSF}} enables sharing of signals and events between c This specification defines how to translate normative SSF event requirements into a JSON Schema. JSON Schema is a standardized way to describe the structure, constraints, and data types within a JSON document. JSON Schemas can also be used as validators to automatically check if a JSON document adheres to the defined schema, ensuring data integrity. -Using JSON Schema to describe SSF has the following main benefits. +Using JSON Schema to describe SSF has the following benefits: - Allows machine readability to auto generation of stubs - It enables a faster process to create, update and get approval for new event types. - JSON schema, rather than spec texts, is a more appropriate format to describe event types. @@ -123,20 +123,20 @@ Using JSON Schema to describe SSF has the following main benefits. # JSON Schema Defintion -JSON Schema Documents MUST define value of each event statement within the "events" claim of a JWT as defined in Section 2.2 of {{SET}} where the key (event URN) is $id of the JSON schema +The following section describes how a map a SSF event to a JSON Schema Document. -^^ not sure about this. how would the even URN relate to the schema $id? +As defined in Section 4.3 of {{JSON Schema}}, a JSON Schema document, also called a "schema", is a JSON document used to describe another JSON Document, known as an instance. -Schema keywords - Normative -Validation keywords - Normative -Schema annotations - Non-normative +A JSON Schema document describes the instance of SSF SET event "payload" (Section 2 of {{SET}}). As such, the schema will defined the claims that pertian to the specific SSF event type. The $id for the schema document MUST be the same as the event identifier of the SET. +The schema is made up of the following top-level JSON keys: + \\$schema : REQUIRED, JSON string: URI of the version of JSON Schema that this document adheres to. E.g., `https://json-schema.org/draft/2020-12/schema`. Normative Schema Keyword. \\$id -: REQUIRED, JSON string: URI of the schema. SHOULD be publicly accessible and resolve to the JSON Schema document. Normative Schema Keyword. +: REQUIRED, JSON string: Event Identifier of the SET and URI of the schema. MUST be publicly accessible or available out-of-band and resolve to JSON Schema document. Normative Schema Keyword. title : REQUIRED, JSON string: Title of the schema. Informational Schema Annotation. @@ -151,6 +151,7 @@ properties : REQUIRED JSON object: Object that defines the keys in the JSON data that are being validated. Normative Validation Keyword. +The following is a non-normative example of a JSON Schema document for a CAEP event. ~~~ json { "$schema": "https://json-schema.org/draft/2020-12/schema", @@ -165,16 +166,9 @@ properties ## Properties - -> ### Open Questions: -> - Should the schema contain just validate the events claim in the SET? -> - Typically you'd use another JWT library to validate the top level claims like iss, aud, etc. - - -The top level "properties" key contains an object "where each property represents a key in the JSON data that’s being validated." (https://json-schema.org/learn/getting-started-step-by-step. Within each property, all normative requirements and non-normative details are specified, such as a description of the property, if its required, what values are allowed, etc. - -The properties key MUST follow the vocabulary specified in {{JSONSchemaValidation}} +The top level "properties" key contains an object where each property represents a key in the JSON data that’s being validated. Within each property, all normative requirements and non-normative details are specified by using the vocabulary in {{JSONSchemaValidation}}. +The following is a non-normative example of a "properties" object for a CAEP event schema. ~~~json { "properties": { @@ -205,9 +199,6 @@ The properties key MUST follow the vocabulary specified in {{JSONSchemaValidatio } ~~~ -# Schema for mandatory claims in SET - - # Discoverability/Registry ## Event Types From 6a8d0bfa4eb7569f37b4167f8a2362b3b4e2057a Mon Sep 17 00:00:00 2001 From: Jen Schreiber Date: Tue, 24 Sep 2024 10:50:44 -0600 Subject: [PATCH 06/13] fix registration --- ...haredsignals-eventdef-specification-1_0.md | 36 ++++++++++--------- 1 file changed, 20 insertions(+), 16 deletions(-) diff --git a/openid-sharedsignals-eventdef-specification-1_0.md b/openid-sharedsignals-eventdef-specification-1_0.md index 463f3ff..ea2d165 100644 --- a/openid-sharedsignals-eventdef-specification-1_0.md +++ b/openid-sharedsignals-eventdef-specification-1_0.md @@ -21,17 +21,16 @@ author: name: Tim Cappalli org: Okta email: tim.cappalli@okta.com - - - ins: A. Deshpande - name: Apoorva Deshpande - org: Okta - email: apoorva.deshpande@okta.com - ins: J. Schreiber name: Jen Schreiber org: Workday email: jennifer.winer@workday.com - + - + ins: A. Deshpande + name: Apoorva Deshpande + org: Okta + email: apoorva.deshpande@okta.com normative: OpenID.Core: author: @@ -198,23 +197,28 @@ The following is a non-normative example of a "properties" object for a CAEP eve } } ~~~ +# Registry -# Discoverability/Registry - -## Event Types +This section serves as a registry for the schemas of all registered SSF Event Types. -| Event Type | Schema URI | +| Event Type | Schema URI | Description |------|-------------| -| CAEP | | -| RISC | | +| CAEP | | brief description | +| RISC | | brief description | + +{: title="Registered Event Types" #eventtypestable} -{: title="Name this table..." #eventtypestable} +## The Registration Process -### CAEP +SSF Implementers may find that existing registered SSF event types do not meet the needs of their applications. In that case, they may propose a new SSF event type and register its schema. To do so, an implementer MUST create a request in the form of a Pull Request to https://github.com/openid/sharedsignals and meet the following requirements. The pull request will be reviewed by the Shared Signals Working Group and accepted at their discression. -### RISC +1. Author(s) of the pull request MUST be at least a contributing member of the OpenID Foundation. +1. The Pull Request MUST contain a human readable description of the new SSF event type. +1. The $id of the schema MUST be publicly accesbile on the internet and resolve to the schema document. +1. The "title" and "description" of the schema must be meaningful and indicative of its function. +1. The naming of all schema properties MUST be indicative of its function. +1. Schemas may not be removed, only deprecated. Any changes to schemas must follow semantic versioning. -# Process for raising PRs and getting approved ## Notational Considerations The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 {{RFC2119}} {{RFC8174}} when, and only when, they appear in all capitals, as shown here. From 954c7d3f798f0778ddb090914c39b68e34521e1b Mon Sep 17 00:00:00 2001 From: Apoorva Deshpande Date: Wed, 25 Sep 2024 11:31:52 -0700 Subject: [PATCH 07/13] Update openid-sharedsignals-eventdef-specification-1_0.md --- openid-sharedsignals-eventdef-specification-1_0.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/openid-sharedsignals-eventdef-specification-1_0.md b/openid-sharedsignals-eventdef-specification-1_0.md index ea2d165..fe5c92c 100644 --- a/openid-sharedsignals-eventdef-specification-1_0.md +++ b/openid-sharedsignals-eventdef-specification-1_0.md @@ -112,21 +112,22 @@ This document defines how to describe events for the Shared Signals Framework {{ Shared Signals Framework {{SSF}} enables sharing of signals and events between cooperating peers. It is currently leveraged by two applications – the Continuous Access Evaluation Protocol {{CAEP}} and Risk Incident Sharing and Coordination {{RISC}}. -This specification defines how to translate normative SSF event requirements into a JSON Schema. JSON Schema is a standardized way to describe the structure, constraints, and data types within a JSON document. JSON Schemas can also be used as validators to automatically check if a JSON document adheres to the defined schema, ensuring data integrity. +This specification defines how to translate normative SSF, CAEP, RISC event requirements into a JSON Schema. {{JSONSchema}} is a standardized way to describe the structure, constraints, and data types within a JSON document. JSON Schemas can also be used as {{JSONSchemaValidation}} to automatically check if a JSON document adheres to the defined schema, ensuring data integrity. Using JSON Schema to describe SSF has the following benefits: -- Allows machine readability to auto generation of stubs +- Allows machine readability to auto generation of stubs. - It enables a faster process to create, update and get approval for new event types. - JSON schema, rather than spec texts, is a more appropriate format to describe event types. - It also allows event types to be versioned independently thus reducing the friction between the SSF core specification and event type publication. +- Allows more events to be incorporated easily in the standards space beyond the usecases and charters of CAEP, RISC etc. # JSON Schema Defintion The following section describes how a map a SSF event to a JSON Schema Document. -As defined in Section 4.3 of {{JSON Schema}}, a JSON Schema document, also called a "schema", is a JSON document used to describe another JSON Document, known as an instance. +As defined in {{Section 4.3 of JSON Schema}}, a JSON Schema document, also called a "schema", is a JSON document used to describe another JSON Document, known as an instance. -A JSON Schema document describes the instance of SSF SET event "payload" (Section 2 of {{SET}}). As such, the schema will defined the claims that pertian to the specific SSF event type. The $id for the schema document MUST be the same as the event identifier of the SET. +A JSON Schema document describes the instance of SSF SET event "payload" ({{Section 2 of SET}}). As such, the schema will defined the claims that pertian to the specific SSF event type. The $id for the schema document MUST be the same as the event identifier of the SET. The schema is made up of the following top-level JSON keys: @@ -218,6 +219,7 @@ SSF Implementers may find that existing registered SSF event types do not meet t 1. The "title" and "description" of the schema must be meaningful and indicative of its function. 1. The naming of all schema properties MUST be indicative of its function. 1. Schemas may not be removed, only deprecated. Any changes to schemas must follow semantic versioning. +1. Event schema MUST include mandatory SET claims described in {{Section 2.2 of RFC8417}}. ## Notational Considerations From 7d20221ff2c0477fee5615dcce11d01662e34a7a Mon Sep 17 00:00:00 2001 From: Apoorva Deshpande Date: Wed, 25 Sep 2024 12:51:13 -0700 Subject: [PATCH 08/13] Updated example for the Session Revoked JSON Schema --- ...haredsignals-eventdef-specification-1_0.md | 63 ++++++++++++++++--- 1 file changed, 53 insertions(+), 10 deletions(-) diff --git a/openid-sharedsignals-eventdef-specification-1_0.md b/openid-sharedsignals-eventdef-specification-1_0.md index fe5c92c..11380e8 100644 --- a/openid-sharedsignals-eventdef-specification-1_0.md +++ b/openid-sharedsignals-eventdef-specification-1_0.md @@ -151,17 +151,61 @@ properties : REQUIRED JSON object: Object that defines the keys in the JSON data that are being validated. Normative Validation Keyword. -The following is a non-normative example of a JSON Schema document for a CAEP event. +The following is a non-normative example of a JSON Schema document for a Session Revoked CAEP event. ~~~ json { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.openid.net/secevent/caep/event-type/session-revoked/v1.schema.json", - "title": "Session Revoked", - "description": "Session Revoked signals that the session identified by the subject has been revoked. The explicit session identifier may be directly referenced in the subject or other properties of the session may be included to allow the receiver to identify applicable sessions.", - "type": "object", - "properties": {} - } + "$schema":"https://json-schema.org/draft/2020-12/schema", + "$id":"https://schemas.openid.net/secevent/caep/event-type/session-revoked/v1.schema.json", + "title":"Session Revoked", + "description":"Session Revoked signals that the session identified by the subject has been revoked. The explicit session identifier may be directly referenced in the subject or other properties of the session may be included to allow the receiver to identify applicable sessions.", + "type":"object", + "properties":{ + "initiating_entity":{ + "description":"Describes the entity that invoked the event.", + "type":"string", + "oneOf":[ + { + "const":"admin", + "description":"an administrative action triggered the event" + }, + { + "const":"user", + "description":"an end-user action triggered the event" + }, + { + "const":"policy", + "description":"a policy evaluation triggered the event" + }, + { + "const":"system", + "description":"a system or platform assertion triggered the event" + } + ] + }, + "reason_admin":{ + "type":"object", + "properties":{ + "en":{ + "type":"string" + } + } + }, + "reason_user":{ + "type":"object", + "properties":{ + "en":{ + "type":"string" + }, + "es-410":{ + "type":"string" + } + } + }, + "event_timestamp":{ + "type":"number" + } + } +} ~~~ ## Properties @@ -219,7 +263,6 @@ SSF Implementers may find that existing registered SSF event types do not meet t 1. The "title" and "description" of the schema must be meaningful and indicative of its function. 1. The naming of all schema properties MUST be indicative of its function. 1. Schemas may not be removed, only deprecated. Any changes to schemas must follow semantic versioning. -1. Event schema MUST include mandatory SET claims described in {{Section 2.2 of RFC8417}}. ## Notational Considerations From 8b3714ff6e8a8ebb9081bf6d0c32cf7e882deeca Mon Sep 17 00:00:00 2001 From: Jen Schreiber Date: Tue, 8 Oct 2024 08:04:12 -0600 Subject: [PATCH 09/13] Apply suggestions from code review Co-authored-by: Tim Cappalli Co-authored-by: Shayne Miel (he/him) --- ...-sharedsignals-eventdef-specification-1_0.md | 17 ++++++----------- 1 file changed, 6 insertions(+), 11 deletions(-) diff --git a/openid-sharedsignals-eventdef-specification-1_0.md b/openid-sharedsignals-eventdef-specification-1_0.md index 11380e8..503b582 100644 --- a/openid-sharedsignals-eventdef-specification-1_0.md +++ b/openid-sharedsignals-eventdef-specification-1_0.md @@ -16,11 +16,6 @@ pi: private: yes author: - - - ins: T. Cappalli - name: Tim Cappalli - org: Okta - email: tim.cappalli@okta.com - ins: J. Schreiber name: Jen Schreiber @@ -54,7 +49,7 @@ normative: RFC6711: RFC8176: SSF: - target: http://openid.net/specs/openid-sse-framework-1_0.html + target: https://openid.net/specs/openid-sharedsignals-framework-1_0-03.html title: OpenID Shared Signals and Events Framework Specification 1.0 author: - @@ -64,7 +59,7 @@ normative: - ins: T. Cappalli name: Tim Cappalli - org: Microsoft + org: Okta - ins: M. Scurtescu name: Marius Scurtescu @@ -110,20 +105,20 @@ This document defines how to describe events for the Shared Signals Framework {{ # Introduction {#introduction} -Shared Signals Framework {{SSF}} enables sharing of signals and events between cooperating peers. It is currently leveraged by two applications – the Continuous Access Evaluation Protocol {{CAEP}} and Risk Incident Sharing and Coordination {{RISC}}. +The Shared Signals Framework {{SSF}} enables sharing of signals and events between cooperating peers. It is currently leveraged by two applications – the Continuous Access Evaluation Profile {{CAEP}} and Risk Incident Sharing and Coordination {{RISC}}. This specification defines how to translate normative SSF, CAEP, RISC event requirements into a JSON Schema. {{JSONSchema}} is a standardized way to describe the structure, constraints, and data types within a JSON document. JSON Schemas can also be used as {{JSONSchemaValidation}} to automatically check if a JSON document adheres to the defined schema, ensuring data integrity. Using JSON Schema to describe SSF has the following benefits: -- Allows machine readability to auto generation of stubs. +- Allows machine readability for the auto generation of stubs. - It enables a faster process to create, update and get approval for new event types. - JSON schema, rather than spec texts, is a more appropriate format to describe event types. - It also allows event types to be versioned independently thus reducing the friction between the SSF core specification and event type publication. -- Allows more events to be incorporated easily in the standards space beyond the usecases and charters of CAEP, RISC etc. +- Allows more events to be incorporated easily in the standards space beyond the use cases and charters of CAEP, RISC etc. # JSON Schema Defintion -The following section describes how a map a SSF event to a JSON Schema Document. +The following section describes how to map a SSF event to a JSON Schema Document. As defined in {{Section 4.3 of JSON Schema}}, a JSON Schema document, also called a "schema", is a JSON document used to describe another JSON Document, known as an instance. From 239a2ed4162c501cac5e2d77d33bb8a6eb929fb3 Mon Sep 17 00:00:00 2001 From: Jen Schreiber Date: Tue, 8 Oct 2024 08:05:01 -0600 Subject: [PATCH 10/13] Apply suggestions from code review Co-authored-by: Tim Cappalli Co-authored-by: Shayne Miel (he/him) --- openid-sharedsignals-eventdef-specification-1_0.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/openid-sharedsignals-eventdef-specification-1_0.md b/openid-sharedsignals-eventdef-specification-1_0.md index 503b582..1e7d03c 100644 --- a/openid-sharedsignals-eventdef-specification-1_0.md +++ b/openid-sharedsignals-eventdef-specification-1_0.md @@ -120,9 +120,9 @@ Using JSON Schema to describe SSF has the following benefits: The following section describes how to map a SSF event to a JSON Schema Document. -As defined in {{Section 4.3 of JSON Schema}}, a JSON Schema document, also called a "schema", is a JSON document used to describe another JSON Document, known as an instance. +As defined in Section 4.3 of {{JSON Schema}}, a JSON Schema document, also called a "schema", is a JSON document used to describe another JSON Document, known as an instance. -A JSON Schema document describes the instance of SSF SET event "payload" ({{Section 2 of SET}}). As such, the schema will defined the claims that pertian to the specific SSF event type. The $id for the schema document MUST be the same as the event identifier of the SET. +A JSON Schema document describes the instance of SSF SET event "payload" ({{Section 2 of SET}}). As such, the schema will define the claims that pertain to the specific SSF event type. The $id for the schema document MUST be the same as the event identifier of the SET. The schema is made up of the following top-level JSON keys: @@ -241,8 +241,8 @@ The following is a non-normative example of a "properties" object for a CAEP eve This section serves as a registry for the schemas of all registered SSF Event Types. -| Event Type | Schema URI | Description -|------|-------------| +| Event Type | Schema URI | Description | +|------|-------------|-------| | CAEP | | brief description | | RISC | | brief description | @@ -250,11 +250,11 @@ This section serves as a registry for the schemas of all registered SSF Event Ty ## The Registration Process -SSF Implementers may find that existing registered SSF event types do not meet the needs of their applications. In that case, they may propose a new SSF event type and register its schema. To do so, an implementer MUST create a request in the form of a Pull Request to https://github.com/openid/sharedsignals and meet the following requirements. The pull request will be reviewed by the Shared Signals Working Group and accepted at their discression. +SSF Implementers may find that existing registered SSF event types do not meet the needs of their applications. In that case, they may propose a new SSF event type and register its schema. To do so, an implementer MUST create a request in the form of a Pull Request to https://github.com/openid/sharedsignals and meet the following requirements. The pull request will be reviewed by the Shared Signals Working Group and accepted at their discretion. 1. Author(s) of the pull request MUST be at least a contributing member of the OpenID Foundation. 1. The Pull Request MUST contain a human readable description of the new SSF event type. -1. The $id of the schema MUST be publicly accesbile on the internet and resolve to the schema document. +1. The $id of the schema MUST be publicly accessible on the internet and resolve to the schema document. 1. The "title" and "description" of the schema must be meaningful and indicative of its function. 1. The naming of all schema properties MUST be indicative of its function. 1. Schemas may not be removed, only deprecated. Any changes to schemas must follow semantic versioning. From 12b66b7a17f555701415bdd2295ba28ee3873a0c Mon Sep 17 00:00:00 2001 From: Jen Schreiber Date: Tue, 8 Oct 2024 08:06:18 -0600 Subject: [PATCH 11/13] Apply suggestions from code review --- openid-sharedsignals-eventdef-specification-1_0.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/openid-sharedsignals-eventdef-specification-1_0.md b/openid-sharedsignals-eventdef-specification-1_0.md index 1e7d03c..f9479ee 100644 --- a/openid-sharedsignals-eventdef-specification-1_0.md +++ b/openid-sharedsignals-eventdef-specification-1_0.md @@ -120,7 +120,7 @@ Using JSON Schema to describe SSF has the following benefits: The following section describes how to map a SSF event to a JSON Schema Document. -As defined in Section 4.3 of {{JSON Schema}}, a JSON Schema document, also called a "schema", is a JSON document used to describe another JSON Document, known as an instance. +As defined in Section 4.3 of {{JSON Schema}}, a JSON Schema document, also called a "schema", is a JSON document used to describe another JSON document, known as an instance. A JSON Schema document describes the instance of SSF SET event "payload" ({{Section 2 of SET}}). As such, the schema will define the claims that pertain to the specific SSF event type. The $id for the schema document MUST be the same as the event identifier of the SET. @@ -241,7 +241,7 @@ The following is a non-normative example of a "properties" object for a CAEP eve This section serves as a registry for the schemas of all registered SSF Event Types. -| Event Type | Schema URI | Description | +| Event Name | Schema URI | Description | |------|-------------|-------| | CAEP | | brief description | | RISC | | brief description | From 7a0fd05a07a296e4d7a216dc228bb33edba411e7 Mon Sep 17 00:00:00 2001 From: Jen Schreiber Date: Tue, 8 Oct 2024 08:34:24 -0600 Subject: [PATCH 12/13] another pass --- ...haredsignals-eventdef-specification-1_0.md | 106 ++++++++++-------- 1 file changed, 60 insertions(+), 46 deletions(-) diff --git a/openid-sharedsignals-eventdef-specification-1_0.md b/openid-sharedsignals-eventdef-specification-1_0.md index f9479ee..cc0d387 100644 --- a/openid-sharedsignals-eventdef-specification-1_0.md +++ b/openid-sharedsignals-eventdef-specification-1_0.md @@ -107,14 +107,14 @@ This document defines how to describe events for the Shared Signals Framework {{ The Shared Signals Framework {{SSF}} enables sharing of signals and events between cooperating peers. It is currently leveraged by two applications – the Continuous Access Evaluation Profile {{CAEP}} and Risk Incident Sharing and Coordination {{RISC}}. -This specification defines how to translate normative SSF, CAEP, RISC event requirements into a JSON Schema. {{JSONSchema}} is a standardized way to describe the structure, constraints, and data types within a JSON document. JSON Schemas can also be used as {{JSONSchemaValidation}} to automatically check if a JSON document adheres to the defined schema, ensuring data integrity. +This specification defines how to translate normative SSF event requirements, such as from CAEP and RISC events, into a JSON Schema. {{JSONSchema}} is a standardized way to describe the structure, constraints, and data types within a JSON document. JSON Schemas are often used with {{JSONSchemaValidation}} to automatically check if a JSON document adheres to the defined schema, thus ensuring data integrity. Using JSON Schema to describe SSF has the following benefits: -- Allows machine readability for the auto generation of stubs. -- It enables a faster process to create, update and get approval for new event types. -- JSON schema, rather than spec texts, is a more appropriate format to describe event types. -- It also allows event types to be versioned independently thus reducing the friction between the SSF core specification and event type publication. -- Allows more events to be incorporated easily in the standards space beyond the use cases and charters of CAEP, RISC etc. +- Machine readability for the auto generation of stubs +- Faster process to create, update and get approval for new event types +- Easy and appropriate format to describe event types, as opposed to traditional specification text +- Independent versioning to reduce the friction between the SSF core specification and event type publications +- Allows new SSF events to be incorporated into the SSF ecosystem # JSON Schema Defintion @@ -122,8 +122,7 @@ The following section describes how to map a SSF event to a JSON Schema Document As defined in Section 4.3 of {{JSON Schema}}, a JSON Schema document, also called a "schema", is a JSON document used to describe another JSON document, known as an instance. -A JSON Schema document describes the instance of SSF SET event "payload" ({{Section 2 of SET}}). As such, the schema will define the claims that pertain to the specific SSF event type. The $id for the schema document MUST be the same as the event identifier of the SET. - +A JSON Schema document describes the instance of SSF SET event "payload" (Section 2 of {{SET}}). As such, the schema will define the claims that pertain to the specific SSF event type. The $id for the schema document MUST be the same as the event identifier of the SET. The schema is made up of the following top-level JSON keys: @@ -146,7 +145,56 @@ properties : REQUIRED JSON object: Object that defines the keys in the JSON data that are being validated. Normative Validation Keyword. -The following is a non-normative example of a JSON Schema document for a Session Revoked CAEP event. +The following is a non-normative example of the top level properties of a JSON Schema document for a Session Revoked CAEP event. +~~~ json +{ + "$schema":"https://json-schema.org/draft/2020-12/schema", + "$id":"https://schemas.openid.net/secevent/caep/event-type/session-revoked/v1.schema.json", + "title":"Session Revoked", + "description":"Session Revoked signals that the session identified by the subject has been revoked. The explicit session identifier may be directly referenced in the subject or other properties of the session may be included to allow the receiver to identify applicable sessions.", + "type":"object", + "properties":{...} +} +~~~ + +## Properties + +The top level "properties" key contains an object where each property represents a key in the JSON data being validated. Within each property, all normative requirements and non-normative details are specified by using the vocabulary in {{JSONSchemaValidation}}. + +The following is a non-normative example of a "properties" object for a CAEP event schema. +~~~json +{ + "properties": { + "initiating_entity": { + "description": "Describes the entity that invoked the event.", + "type": "string", + "oneOf": [ + { + "const": "admin", + "description": "an administrative action triggered the event" + }, + { + "const": "user", + "description": "an end-user action triggered the event" + }, + { + "const": "policy", + "description": "a policy evaluation triggered the event" + }, + { + "const": "system", + "description": "a system or platform assertion triggered the event" + } + ] + }, + "required": [ "initiating_entity" ] + } +} +~~~ + +## Full Example + +The following is a non-normative example of the top level properties of a JSON Schema document for a Session Revoked CAEP event. ~~~ json { "$schema":"https://json-schema.org/draft/2020-12/schema", @@ -203,48 +251,14 @@ The following is a non-normative example of a JSON Schema document for a Session } ~~~ -## Properties - -The top level "properties" key contains an object where each property represents a key in the JSON data that’s being validated. Within each property, all normative requirements and non-normative details are specified by using the vocabulary in {{JSONSchemaValidation}}. - -The following is a non-normative example of a "properties" object for a CAEP event schema. -~~~json -{ - "properties": { - "initiating_entity": { - "description": "Describes the entity that invoked the event.", - "type": "string", - "oneOf": [ - { - "const": "admin", - "description": "an administrative action triggered the event" - }, - { - "const": "user", - "description": "an end-user action triggered the event" - }, - { - "const": "policy", - "description": "a policy evaluation triggered the event" - }, - { - "const": "system", - "description": "a system or platform assertion triggered the event" - } - ] - }, - "required": [ "initiating_entity" ] - } -} -~~~ # Registry This section serves as a registry for the schemas of all registered SSF Event Types. | Event Name | Schema URI | Description | -|------|-------------|-------| +|------------|------------|-------------| | CAEP | | brief description | -| RISC | | brief description | +| RISC | | brief description | {: title="Registered Event Types" #eventtypestable} @@ -257,7 +271,7 @@ SSF Implementers may find that existing registered SSF event types do not meet t 1. The $id of the schema MUST be publicly accessible on the internet and resolve to the schema document. 1. The "title" and "description" of the schema must be meaningful and indicative of its function. 1. The naming of all schema properties MUST be indicative of its function. -1. Schemas may not be removed, only deprecated. Any changes to schemas must follow semantic versioning. +1. Schemas may not be removed, only deprecated through . Any changes to schemas must follow semantic versioning. ## Notational Considerations From a1860ae9f507c7bad591788807162ac6b9747ba9 Mon Sep 17 00:00:00 2001 From: Jen Schreiber Date: Tue, 22 Oct 2024 09:38:32 -0600 Subject: [PATCH 13/13] review comments --- ...haredsignals-eventdef-specification-1_0.md | 32 +++++++++++-------- 1 file changed, 18 insertions(+), 14 deletions(-) diff --git a/openid-sharedsignals-eventdef-specification-1_0.md b/openid-sharedsignals-eventdef-specification-1_0.md index cc0d387..22e505d 100644 --- a/openid-sharedsignals-eventdef-specification-1_0.md +++ b/openid-sharedsignals-eventdef-specification-1_0.md @@ -2,7 +2,7 @@ title: OpenID Shared Signals Event Definition Specification abbrev: SSFEvents-Spec docname: openid-sharedsignals-eventdef-specification-1_0 -date: 2024-06-06 +date: 2024-10-22 ipr: none cat: std @@ -110,9 +110,9 @@ The Shared Signals Framework {{SSF}} enables sharing of signals and events betwe This specification defines how to translate normative SSF event requirements, such as from CAEP and RISC events, into a JSON Schema. {{JSONSchema}} is a standardized way to describe the structure, constraints, and data types within a JSON document. JSON Schemas are often used with {{JSONSchemaValidation}} to automatically check if a JSON document adheres to the defined schema, thus ensuring data integrity. Using JSON Schema to describe SSF has the following benefits: -- Machine readability for the auto generation of stubs - Faster process to create, update and get approval for new event types - Easy and appropriate format to describe event types, as opposed to traditional specification text +- Machine readability for creating and validating SSF event paylods - Independent versioning to reduce the friction between the SSF core specification and event type publications - Allows new SSF events to be incorporated into the SSF ecosystem @@ -130,7 +130,7 @@ The schema is made up of the following top-level JSON keys: : REQUIRED, JSON string: URI of the version of JSON Schema that this document adheres to. E.g., `https://json-schema.org/draft/2020-12/schema`. Normative Schema Keyword. \\$id -: REQUIRED, JSON string: Event Identifier of the SET and URI of the schema. MUST be publicly accessible or available out-of-band and resolve to JSON Schema document. Normative Schema Keyword. +: REQUIRED, JSON string: URI of the schema, also known as the Event Identifier of the SET appended in accordance with[Schema Ids](#schema-ids). MUST be publicly accessible or available out-of-band and resolve to JSON Schema document. Normative Schema Keyword. title : REQUIRED, JSON string: Title of the schema. Informational Schema Annotation. @@ -149,7 +149,7 @@ The following is a non-normative example of the top level properties of a JSON S ~~~ json { "$schema":"https://json-schema.org/draft/2020-12/schema", - "$id":"https://schemas.openid.net/secevent/caep/event-type/session-revoked/v1.schema.json", + "$id":"https://schemas.openid.net/secevent/caep/event-type/session-revoked/1.0.0/schema.json", "title":"Session Revoked", "description":"Session Revoked signals that the session identified by the subject has been revoked. The explicit session identifier may be directly referenced in the subject or other properties of the session may be included to allow the receiver to identify applicable sessions.", "type":"object", @@ -198,7 +198,7 @@ The following is a non-normative example of the top level properties of a JSON S ~~~ json { "$schema":"https://json-schema.org/draft/2020-12/schema", - "$id":"https://schemas.openid.net/secevent/caep/event-type/session-revoked/v1.schema.json", + "$id":"https://schemas.openid.net/secevent/caep/event-type/session-revoked/1.0.0/schema.json", "title":"Session Revoked", "description":"Session Revoked signals that the session identified by the subject has been revoked. The explicit session identifier may be directly referenced in the subject or other properties of the session may be included to allow the receiver to identify applicable sessions.", "type":"object", @@ -253,26 +253,30 @@ The following is a non-normative example of the top level properties of a JSON S # Registry -This section serves as a registry for the schemas of all registered SSF Event Types. +## Schema Ids -| Event Name | Schema URI | Description | -|------------|------------|-------------| -| CAEP | | brief description | -| RISC | | brief description | +Ids of SSF event schemas MUST adhere the following convention: + +{event type URI}/{semantic version}/schema.json + +For example, the schema id for a session revoked caep event would be constructed by concatenating the following: +- event type uri: https://schemas.openid.net/secevent/caep/event-type/session-revoked +- semantic version: 1.0.0 +- schema.json + +The resulting id would be "https://schemas.openid.net/secevent/caep/event-type/session-revoked/1.0.0/schema.json" -{: title="Registered Event Types" #eventtypestable} ## The Registration Process -SSF Implementers may find that existing registered SSF event types do not meet the needs of their applications. In that case, they may propose a new SSF event type and register its schema. To do so, an implementer MUST create a request in the form of a Pull Request to https://github.com/openid/sharedsignals and meet the following requirements. The pull request will be reviewed by the Shared Signals Working Group and accepted at their discretion. +SSF Implementers may find that existing registered SSF event types do not meet the needs of their applications. In that case, they may propose a new SSF event type and register its schema. To do so, an implementer MUST create a request in the form of a Pull Request to https://github.com/openid/sharedsignals following the PR Template and meeting the following requirements. The pull request will be reviewed by the Shared Signals Working Group and accepted at their discretion. 1. Author(s) of the pull request MUST be at least a contributing member of the OpenID Foundation. 1. The Pull Request MUST contain a human readable description of the new SSF event type. 1. The $id of the schema MUST be publicly accessible on the internet and resolve to the schema document. 1. The "title" and "description" of the schema must be meaningful and indicative of its function. 1. The naming of all schema properties MUST be indicative of its function. -1. Schemas may not be removed, only deprecated through . Any changes to schemas must follow semantic versioning. - +1. Schemas should not be removed, only incremented (via semantic versioning) or marked as deprecated in the repositiory. Any changes to schemas must follow semantic versioning. ## Notational Considerations The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 {{RFC2119}} {{RFC8174}} when, and only when, they appear in all capitals, as shown here.