From ec4e00b896b2c21f28c2679d5403e8f0dc7b6876 Mon Sep 17 00:00:00 2001 From: Atul Tulshibagwale Date: Tue, 11 Feb 2025 09:53:15 -0800 Subject: [PATCH 01/13] Update build-everything.yml updating ruby version --- .github/workflows/build-everything.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/build-everything.yml b/.github/workflows/build-everything.yml index 7b6067f..22f8d48 100644 --- a/.github/workflows/build-everything.yml +++ b/.github/workflows/build-everything.yml @@ -38,9 +38,9 @@ jobs: steps: - uses: actions/checkout@v3 - name: Set up Ruby - uses: ruby/setup-ruby@ec02537da5712d66d4d50a0f33b7eb52773b5ed1 + uses: ruby/setup-ruby@ev4 with: - ruby-version: '3.1' + ruby-version: '4' - uses: actions/setup-python@v4 with: python-version: '3.10' From c9caa3206b392c5652275c80170459be326423fe Mon Sep 17 00:00:00 2001 From: Atul Tulshibagwale Date: Tue, 11 Feb 2025 09:54:40 -0800 Subject: [PATCH 02/13] Update openid-caep-1_0.md updating source file to trigger build --- openid-caep-1_0.md | 1 + 1 file changed, 1 insertion(+) diff --git a/openid-caep-1_0.md b/openid-caep-1_0.md index 21f849b..27a38bb 100644 --- a/openid-caep-1_0.md +++ b/openid-caep-1_0.md @@ -1,5 +1,6 @@ --- title: OpenID Continuous Access Evaluation Profile 1.0 - draft 03 + abbrev: CAEP-Spec docname: openid-caep-1_0 date: 2024-06-19 From 5a89efd2cb9cce680aa287952a8d74a98945aaeb Mon Sep 17 00:00:00 2001 From: Atul Tulshibagwale Date: Tue, 11 Feb 2025 09:55:39 -0800 Subject: [PATCH 03/13] Update build-everything.yml fixed typo --- .github/workflows/build-everything.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/build-everything.yml b/.github/workflows/build-everything.yml index 22f8d48..1a61738 100644 --- a/.github/workflows/build-everything.yml +++ b/.github/workflows/build-everything.yml @@ -38,7 +38,7 @@ jobs: steps: - uses: actions/checkout@v3 - name: Set up Ruby - uses: ruby/setup-ruby@ev4 + uses: ruby/setup-ruby@v4 with: ruby-version: '4' - uses: actions/setup-python@v4 From 040f97e0b805acf7363d0bc5ff5ecca9802fbf3d Mon Sep 17 00:00:00 2001 From: Atul Tulshibagwale Date: Tue, 11 Feb 2025 09:57:42 -0800 Subject: [PATCH 04/13] Update build-everything.yml removing version number for ruby --- .github/workflows/build-everything.yml | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/.github/workflows/build-everything.yml b/.github/workflows/build-everything.yml index 1a61738..43351b3 100644 --- a/.github/workflows/build-everything.yml +++ b/.github/workflows/build-everything.yml @@ -38,9 +38,7 @@ jobs: steps: - uses: actions/checkout@v3 - name: Set up Ruby - uses: ruby/setup-ruby@v4 - with: - ruby-version: '4' + uses: ruby/setup-ruby@main - uses: actions/setup-python@v4 with: python-version: '3.10' From 757cb8931b3f92e5a29c3fec466924b7ad4881ec Mon Sep 17 00:00:00 2001 From: Atul Tulshibagwale Date: Tue, 11 Feb 2025 12:34:54 -0800 Subject: [PATCH 05/13] sample from setup-ruby doc --- .github/workflows/build-everything.yml | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/.github/workflows/build-everything.yml b/.github/workflows/build-everything.yml index 43351b3..c402f4e 100644 --- a/.github/workflows/build-everything.yml +++ b/.github/workflows/build-everything.yml @@ -38,7 +38,9 @@ jobs: steps: - uses: actions/checkout@v3 - name: Set up Ruby - uses: ruby/setup-ruby@main + uses: ruby/setup-ruby@v1 + with: + ruby-version: '3.3' - uses: actions/setup-python@v4 with: python-version: '3.10' From e5cf61fc106296a00b5ce5b4048914070de90109 Mon Sep 17 00:00:00 2001 From: Atul Tulshibagwale Date: Tue, 11 Feb 2025 15:42:36 -0800 Subject: [PATCH 06/13] attempting to remove caep build error --- openid-caep-1_0.md | 2 +- openid-caep-1_0.xml | 1183 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 1184 insertions(+), 1 deletion(-) create mode 100644 openid-caep-1_0.xml diff --git a/openid-caep-1_0.md b/openid-caep-1_0.md index 27a38bb..eea8304 100644 --- a/openid-caep-1_0.md +++ b/openid-caep-1_0.md @@ -151,7 +151,7 @@ robotic users, devices, sessions and applications. # Introduction {#introduction} CAEP is the application of the Shared Signals Profile of IETF -Security Events 1.0 {{SSF}} (SSF Profile) to ensure access security in a +Security Events 1.0 {{SSF}} to ensure access security in a network of cooperating providers. CAEP specifies a set of event-types that conform to the SSF Profile. This document specifies the event-types required to achieve this goal. diff --git a/openid-caep-1_0.xml b/openid-caep-1_0.xml new file mode 100644 index 0000000..e28da0e --- /dev/null +++ b/openid-caep-1_0.xml @@ -0,0 +1,1183 @@ + + + + + + + + + + + + + + + + + +]> + + + + + + OpenID Continuous Access Evaluation Profile 1.0 - draft 03 + + + Microsoft +
+ tim.cappalli@microsoft.com +
+ + + SGNL +
+ atul@sgnl.ai +
+ + + + + + Shared Signals + + + + + + + +This document defines the Continuous Access Evaluation Profile (CAEP) of the +Shared Signals Framework . It specifies a set of event +types conforming to the Shared Signals Framework. These event types are intended to be used +between cooperating Transmitters and Receivers such that Transmitters may send +continuous updates using which Receivers can attenuate access to shared human or +robotic users, devices, sessions and applications. + + + + + + + + + + + + + + +
Introduction +CAEP is the application of the Shared Signals Profile of IETF +Security Events 1.0 (SSF Profile) to ensure access security in a +network of cooperating providers. CAEP specifies a set of event-types that +conform to the SSF Profile. This document specifies the event-types required to +achieve this goal. + +
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 +when, and only when, they appear in all capitals, as shown here. + +
+
+
Optional Event Claims +The following claims are optional unless otherwise specified in the event +definition. + +
+
event_timestamp
+
+ OPTIONAL, JSON number: the time at which the event described by this SET +occurred. Its value is a JSON number representing the number of seconds +from 1970-01-01T0:0:0Z as measured in UTC until the date/time. +
+
initiating_entity
+
+ OPTIONAL, JSON string: describes the entity that invoked the event. +
+
+
+ This MUST be one of the following strings: + + + + admin: an administrative action triggered the event + user: an end-user action triggered the event + policy: a policy evaluation triggered the event + system: a system or platform assertion triggered the event + +
+
reason_admin
+
+ OPTIONAL, JSON object: a localizable administrative message intended for +logging and auditing. The object MUST contain one or more key/value pairs, +with a BCP47 language tag as the key and the locale-specific +administrative message as the value. +
+
+ +
+ +
+
reason_user
+
+ OPTIONAL, JSON object: a localizable user-friendly message for display +to an end-user. The object MUST contain one or more key/value pairs, with a +BCP47 language tag as the key and the locale-specific end-user +message as the value. +
+
+ +
+ +
+
Event Types +The base URI for CAEP event types is: + +https://schemas.openid.net/secevent/caep/event-type/ + +
Session Revoked +Event Type URI: + +https://schemas.openid.net/secevent/caep/event-type/session-revoked + +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. + +When a Complex Claim is used as the subject, the revocation event applies +to any session derived from matching those combined claims. + +The actual reason why the session was revoked might be specified with the +nested reason_admin and/or reason_user claims described in . + +
Event-Specific Claims + +There are no event-specific claims for this event type. + +When event_timestamp is included, its value MUST represent the time at which +the session revocation occurred. + +
+
Examples + +NOTE: The event type URI is wrapped, the backslash is the continuation character. + +
+ +
+ +
+ +
+
+
Token Claims Change +Event Type URI: + +https://schemas.openid.net/secevent/caep/event-type/token-claims-change + +Token Claims Change signals that a claim in a token, identified by the +subject claim, has changed. + +The actual reason why the claims change occurred might be specified with the +nested reason_admin and/or reason_user claims made in . + +
Event-Specific Claims + +
+
claims
+
+ REQUIRED, JSON object: one or more claims with their new value(s) +
+
+ +When event_timestamp is included, its value MUST represent the time at which +the claim value(s) changed. + +
+
Examples + +NOTE: The event type URI is wrapped, the backslash is the continuation character. + +
+ +
+ +
+ +
+
+
Credential Change +Event Type URI: + +https://schemas.openid.net/secevent/caep/event-type/credential-change + +The Credential Change event signals that a credential was created, changed, +revoked or deleted. Credential Change scenarios include: + + + password/PIN change/reset + certificate enrollment, renewal, revocation and deletion + second factor / passwordless credential enrollment or deletion (U2F, FIDO2, OTP, app-based) + + +The actual reason why the credential change occurred might be specified with the +nested reason_admin and/or reason_user claims made in . + +
Event-Specific Claims + +
+
credential_type
+
+ REQUIRED, JSON string: This MUST be one of the following strings, or any other +credential type supported mutually by the Transmitter and the Receiver. + + + + password + pin + x509 + fido2-platform + fido2-roaming + fido-u2f + verifiable-credential + phone-voice + phone-sms + app + +
+
change_type
+
+ REQUIRED, JSON string: This MUST be one of the following strings: + + + + create + revoke + update + delete + +
+
friendly_name
+
+ OPTIONAL, JSON string: credential friendly name +
+
x509_issuer
+
+ OPTIONAL, JSON string: issuer of the X.509 certificate as defined in +
+
x509_serial
+
+ OPTIONAL, JSON string: serial number of the X.509 certificate as defined in +
+
fido2_aaguid
+
+ OPTIONAL, JSON string: FIDO2 Authenticator Attestation GUID as defined in +
+
+ +When event_timestamp is included, its value MUST represent the time at which +the credential change occurred. + +
+
Examples + +NOTE: The event type URI is wrapped, the backslash is the continuation character. + +
+ +
+
+
Assurance Level Change +Event Type URI: + +https://schemas.openid.net/secevent/caep/event-type/assurance-level-change + +The Assurance Level Change event signals that there has been a change in +authentication method since the initial user login. This change can be from +a weak authentication method to a strong authentication method, or vice versa. + +In the first scenario, Assurance Level Change will an increase, while in the +second scenario it will be a decrease. For example, a user can start a session +with Service Provider A using single factor authentication (such as a password). +The user can then open another session with Service Provider B using +two-factor authentication (such as OTP). In this scenario an increase +Assurance Level Change event will signal to Service Provider A that user has +authenticated with a stronger authentication method. + +The actual reason why the assurance level changed might be specified with the +nested reason_admin and/or reason_user claims made in . + +
Event-Specific Claims + +
+
namespace:
+
+ REQUIRED, JSON string: the namespace of the values in the current_level and previous_level claims. +This string MAY be one of the following strings: + + + + RFC8176: The assurance level values are from the specification + RFC6711: The assurance level values are from the specification + ISO-IEC-29115: The assurance level values are from the specification + NIST-IAL: The assurance level values are from the specification + NIST-AAL: The assurance level values are from the specification + NIST-FAL: The assurance level values are from the specification + Any other value that is an alias for a custom namespace agreed between the Transmitter and the Receiver + +
+
current_level
+
+ REQUIRED, JSON string: The current assurance level, as defined in the specified namespace +
+
previous_level
+
+ OPTIONAL, JSON string: the previous assurance level, as defined in the specified namespace +If the Transmitter omits this value, the Receiver MUST assume that the previous assurance level is unknown to the Transmitter +
+
change_direction
+
+ OPTIONAL, JSON string: the assurance level increased or decreased +If the Transmitter has specified the previous_level, then the Transmitter SHOULD provide a value for this claim. +If present, this MUST be one of the following strings: + + + + increase + decrease + +
+
+ +When event_timestamp is included, its value MUST represent the time at which +the assurance level changed. + +
+
Examples + +
+ +
+ +
+
+
Device Compliance Change +Event Type URI: + +https://schemas.openid.net/secevent/caep/event-type/device-compliance-change + +Device Compliance Change signals that a device's compliance status has changed. + +The actual reason why the status change occurred might be specified with the +nested reason_admin and/or reason_user claims made in . + +
Event-Specific Claims + +
+
previous_status
+
+ REQUIRED, JSON string: the compliance status prior to the change that triggered the event +
+
+
+ This MUST be one of the following strings: + + + + compliant + not-compliant + +
+
current_status
+
+ REQUIRED, JSON string: the current status that triggered the event +
+
+
+ This MUST be one of the following strings: + + + + compliant + not-compliant + +
+
+ +When event_timestamp is included, its value MUST represent the time at which +the device compliance status changed. + +
+
Examples + +NOTE: The event type URI is wrapped, the backslash is the continuation character. + +
+ +
+
+
Session Established +Event Type URI: + +https://schemas.openid.net/secevent/caep/event-type/session-established + +The Session Established event signifies that the Transmitter has established a new session for the subject. Receivers may use this information for a number of reasons, including: + + + A service acting as a Transmitter can close the loop with the IdP after a user has been federated from the IdP + An IdP can detect unintended logins + A Receiver can establish an inventory of user sessions + + +The event_timestamp in this event type specifies the time at which the session was established. + +
Event Specific Claims +The following optional claims MAY be included in the Session Established event: + +
+
ips
+
+ The array of IP addresses of the user as observed by the Transmitter. The value MUST be in the format of an array of strings, each one of which represents the RFC 4001 string representation of an IP address. (NOTE, this can be different from the one observed by the Receiver for the same user because of network translation) +
+
fp_ua
+
+ Fingerprint of the user agent computed by the Transmitter. (NOTE, this is not to identify the session, but to present some qualities of the session) +
+
acr
+
+ The authentication context class reference of the session, as established by the Transmitter. The value of this field MUST be interpreted in the same way as the corresponding field in an OpenID Connect ID Token +
+
amr
+
+ The authentication methods reference of the session, as established by the Transmitter. The value of this field MUST be an array of strings, each of which MUST be interpreted in the same way as the corresponding field in an OpenID Connect ID Token +
+
ext_id
+
+ The external session identifier, which may be used to correlate this session with a broader session (e.g., a federated session established using SAML) +
+
+ +
+
Examples +The following is a non-normative example of the session-established event type: + +
+ +
+
+
Session Presented +Event Type URI: + +https://schemas.openid.net/secevent/caep/event-type/session-presented + +The Session Presented event signifies that the Transmitter has observed the session to be present at the Transmitter at the time indicated by the event_timestamp field in the Session Presented event. Receivers may use this information for reasons that include: + + + Detecting abnormal user activity + Establishing an inventory of live sessions belonging to a user + + +
Event Specific Claims +The following optional claims MAY be present in a Session Presented event: + +
+
ips
+
+ The array of IP addresses of the user as observed by the Transmitter. The value MUST be in the format of an array of strings, each one of which represents the RFC 4001 string representation of an IP address. (NOTE, this can be different from the one observed by the Receiver for the same user because of network translation) +
+
fp_ua
+
+ Fingerprint of the user agent computed by the Transmitter. (NOTE, this is not to identify the session, but to present some qualities of the session) +
+
ext_id
+
+ The external session identifier, which may be used to correlate this session with a broader session (e.g., a federated session established using SAML) +
+
+ +
+
Examples +The following is a non-normative example of a Session Presented event: + +
+ +
+
+
+
Security Considerations +Any implementations of events described in this document SHOULD comply with the Shared Signals Framework . Exchanging events described herein without complying with the Shared Signals Framework may result in security issues. + +
+ + + + + + + + + + +&RFC4001; + + + ISO/IEC 29115:2013 -- Information technology - Security techniques - Entity authentication assurance framework + + + + + + + + + Digital Identity Guidelines, Authentication and Lifecycle Management + + + + + + + + + + + + + + + Digital Identity Guidelines, Federation and Assertions + + + + + + + + + + + + + + + + + + + + + Digital Identity Guidelines, Enrollment and Identity Proofing + + + + + + + + + + + + OpenID Connect Core 1.0 - ID Token + + + + + + + + + + + + + + + + + + +&RFC2119; +&RFC8174; +&RFC5280; +&RFC5646; +&RFC6711; +&RFC8176; + + + OpenID Shared Signals and Events Framework Specification 1.0 + + Google + + + Microsoft + + + Coinbase + + + Amazon + + + Yubico + + + + + + + Web Authentication: An API for accessing Public Key Credentials Level 2 + + Google + + + + + + + + + + + + + +
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. + +
+
Document History + +[[ To be removed from the final specification ]] + +-03 + + + New "Session Established" and "Session Presented" event types + Added namespace required field to Assurance Level Change event + Changed the name referencing SSE to SSF + Added format to the subjects in examples in CAEP + Formatting and typo changes + + +
+ + + + + + + + From 29bf1668abe8a08de63fb7d6fee0d2ad05991fd8 Mon Sep 17 00:00:00 2001 From: Atul Tulshibagwale Date: Tue, 11 Feb 2025 15:56:17 -0800 Subject: [PATCH 07/13] removed section 2 of inside SSF xref --- openid-caep-1_0.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/openid-caep-1_0.md b/openid-caep-1_0.md index 809a62e..67d73e4 100644 --- a/openid-caep-1_0.md +++ b/openid-caep-1_0.md @@ -141,7 +141,7 @@ normative: --- abstract This document defines the Continuous Access Evaluation Profile (CAEP) of the -Shared Signals Framework {{SSF}}. It specifies a set of event +Shared Signals Framework {{SharedSignals}}. It specifies a set of event types conforming to the Shared Signals Framework. These event types are intended to be used between cooperating Transmitters and Receivers such that Transmitters may send continuous updates using which Receivers can attenuate access to shared human or @@ -151,7 +151,7 @@ robotic users, devices, sessions and applications. # Introduction {#introduction} CAEP is the application of the Shared Signals Profile of IETF -Security Events 1.0 {{SSF}} to ensure access security in a +Security Events 1.0 {{SharedSignals}} to ensure access security in a network of cooperating providers. CAEP specifies a set of event-types that conform to the SSF Profile. This document specifies the event-types required to achieve this goal. @@ -820,7 +820,8 @@ The following is a non-normative example of a Session Presented event: "ext_id": "12345", "event_timestamp": 1615304991643 } - }} + } +} ~~~ ## Risk Level Change {#risk-level-change} @@ -843,7 +844,7 @@ risk_reason : RECOMMENDED, JSON string: indicates the reason that contributed to the risk level changes by the Transmitter. principal -: REQUIRED, JSON string: representing the principal entity involved in the observed risk event, as identified by the transmitter. The subject principal can be one of the following entities USER, DEVICE, SESSION, TENANT, ORG_UNIT, GROUP, or any other entity as defined in {{Section 2 of SSF}}. This claim identifies the primary subject associated with the event, and helps to contextualize the risk relative to the entity involved. +: REQUIRED, JSON string: representing the principal entity involved in the observed risk event, as identified by the transmitter. The subject principal can be one of the following entities USER, DEVICE, SESSION, TENANT, ORG_UNIT, GROUP, or any other entity as defined in Section 2 of {{SSF}}. This claim identifies the primary subject associated with the event, and helps to contextualize the risk relative to the entity involved. current_level : REQUIRED, JSON string: indicates the current level of the risk for the subject. Value MUST be one of LOW, MEDIUM, HIGH From 80997400c1e2787c7efebc675d7e7693d4006c2e Mon Sep 17 00:00:00 2001 From: Atul Tulshibagwale Date: Tue, 11 Feb 2025 17:40:55 -0800 Subject: [PATCH 08/13] reverted renamed reference to SSF --- openid-caep-1_0.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/openid-caep-1_0.md b/openid-caep-1_0.md index 67d73e4..3fc1ade 100644 --- a/openid-caep-1_0.md +++ b/openid-caep-1_0.md @@ -141,7 +141,7 @@ normative: --- abstract This document defines the Continuous Access Evaluation Profile (CAEP) of the -Shared Signals Framework {{SharedSignals}}. It specifies a set of event +Shared Signals Framework {{SSF}}. It specifies a set of event types conforming to the Shared Signals Framework. These event types are intended to be used between cooperating Transmitters and Receivers such that Transmitters may send continuous updates using which Receivers can attenuate access to shared human or @@ -151,7 +151,7 @@ robotic users, devices, sessions and applications. # Introduction {#introduction} CAEP is the application of the Shared Signals Profile of IETF -Security Events 1.0 {{SharedSignals}} to ensure access security in a +Security Events 1.0 {{SSF}} to ensure access security in a network of cooperating providers. CAEP specifies a set of event-types that conform to the SSF Profile. This document specifies the event-types required to achieve this goal. From 465ade0275dba71ead5e1315e022f75f32ebb741 Mon Sep 17 00:00:00 2001 From: Atul Tulshibagwale Date: Tue, 11 Feb 2025 17:44:42 -0800 Subject: [PATCH 09/13] restored SSF Profile text in caep spec --- openid-caep-1_0.md | 2 +- openid-caep-1_0.xml | 1183 ------------------------------------------- 2 files changed, 1 insertion(+), 1184 deletions(-) delete mode 100644 openid-caep-1_0.xml diff --git a/openid-caep-1_0.md b/openid-caep-1_0.md index 3fc1ade..3cb03e5 100644 --- a/openid-caep-1_0.md +++ b/openid-caep-1_0.md @@ -151,7 +151,7 @@ robotic users, devices, sessions and applications. # Introduction {#introduction} CAEP is the application of the Shared Signals Profile of IETF -Security Events 1.0 {{SSF}} to ensure access security in a +Security Events 1.0 {{SSF}} (SSF Profile) to ensure access security in a network of cooperating providers. CAEP specifies a set of event-types that conform to the SSF Profile. This document specifies the event-types required to achieve this goal. diff --git a/openid-caep-1_0.xml b/openid-caep-1_0.xml deleted file mode 100644 index e28da0e..0000000 --- a/openid-caep-1_0.xml +++ /dev/null @@ -1,1183 +0,0 @@ - - - - - - - - - - - - - - - - - -]> - - - - - - OpenID Continuous Access Evaluation Profile 1.0 - draft 03 - - - Microsoft -
- tim.cappalli@microsoft.com -
- - - SGNL -
- atul@sgnl.ai -
- - - - - - Shared Signals - - - - - - - -This document defines the Continuous Access Evaluation Profile (CAEP) of the -Shared Signals Framework . It specifies a set of event -types conforming to the Shared Signals Framework. These event types are intended to be used -between cooperating Transmitters and Receivers such that Transmitters may send -continuous updates using which Receivers can attenuate access to shared human or -robotic users, devices, sessions and applications. - - - - - - - - - - - - - - -
Introduction -CAEP is the application of the Shared Signals Profile of IETF -Security Events 1.0 (SSF Profile) to ensure access security in a -network of cooperating providers. CAEP specifies a set of event-types that -conform to the SSF Profile. This document specifies the event-types required to -achieve this goal. - -
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 -when, and only when, they appear in all capitals, as shown here. - -
-
-
Optional Event Claims -The following claims are optional unless otherwise specified in the event -definition. - -
-
event_timestamp
-
- OPTIONAL, JSON number: the time at which the event described by this SET -occurred. Its value is a JSON number representing the number of seconds -from 1970-01-01T0:0:0Z as measured in UTC until the date/time. -
-
initiating_entity
-
- OPTIONAL, JSON string: describes the entity that invoked the event. -
-
-
- This MUST be one of the following strings: - - - - admin: an administrative action triggered the event - user: an end-user action triggered the event - policy: a policy evaluation triggered the event - system: a system or platform assertion triggered the event - -
-
reason_admin
-
- OPTIONAL, JSON object: a localizable administrative message intended for -logging and auditing. The object MUST contain one or more key/value pairs, -with a BCP47 language tag as the key and the locale-specific -administrative message as the value. -
-
- -
- -
-
reason_user
-
- OPTIONAL, JSON object: a localizable user-friendly message for display -to an end-user. The object MUST contain one or more key/value pairs, with a -BCP47 language tag as the key and the locale-specific end-user -message as the value. -
-
- -
- -
-
Event Types -The base URI for CAEP event types is: - -https://schemas.openid.net/secevent/caep/event-type/ - -
Session Revoked -Event Type URI: - -https://schemas.openid.net/secevent/caep/event-type/session-revoked - -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. - -When a Complex Claim is used as the subject, the revocation event applies -to any session derived from matching those combined claims. - -The actual reason why the session was revoked might be specified with the -nested reason_admin and/or reason_user claims described in . - -
Event-Specific Claims - -There are no event-specific claims for this event type. - -When event_timestamp is included, its value MUST represent the time at which -the session revocation occurred. - -
-
Examples - -NOTE: The event type URI is wrapped, the backslash is the continuation character. - -
- -
- -
- -
-
-
Token Claims Change -Event Type URI: - -https://schemas.openid.net/secevent/caep/event-type/token-claims-change - -Token Claims Change signals that a claim in a token, identified by the -subject claim, has changed. - -The actual reason why the claims change occurred might be specified with the -nested reason_admin and/or reason_user claims made in . - -
Event-Specific Claims - -
-
claims
-
- REQUIRED, JSON object: one or more claims with their new value(s) -
-
- -When event_timestamp is included, its value MUST represent the time at which -the claim value(s) changed. - -
-
Examples - -NOTE: The event type URI is wrapped, the backslash is the continuation character. - -
- -
- -
- -
-
-
Credential Change -Event Type URI: - -https://schemas.openid.net/secevent/caep/event-type/credential-change - -The Credential Change event signals that a credential was created, changed, -revoked or deleted. Credential Change scenarios include: - - - password/PIN change/reset - certificate enrollment, renewal, revocation and deletion - second factor / passwordless credential enrollment or deletion (U2F, FIDO2, OTP, app-based) - - -The actual reason why the credential change occurred might be specified with the -nested reason_admin and/or reason_user claims made in . - -
Event-Specific Claims - -
-
credential_type
-
- REQUIRED, JSON string: This MUST be one of the following strings, or any other -credential type supported mutually by the Transmitter and the Receiver. - - - - password - pin - x509 - fido2-platform - fido2-roaming - fido-u2f - verifiable-credential - phone-voice - phone-sms - app - -
-
change_type
-
- REQUIRED, JSON string: This MUST be one of the following strings: - - - - create - revoke - update - delete - -
-
friendly_name
-
- OPTIONAL, JSON string: credential friendly name -
-
x509_issuer
-
- OPTIONAL, JSON string: issuer of the X.509 certificate as defined in -
-
x509_serial
-
- OPTIONAL, JSON string: serial number of the X.509 certificate as defined in -
-
fido2_aaguid
-
- OPTIONAL, JSON string: FIDO2 Authenticator Attestation GUID as defined in -
-
- -When event_timestamp is included, its value MUST represent the time at which -the credential change occurred. - -
-
Examples - -NOTE: The event type URI is wrapped, the backslash is the continuation character. - -
- -
-
-
Assurance Level Change -Event Type URI: - -https://schemas.openid.net/secevent/caep/event-type/assurance-level-change - -The Assurance Level Change event signals that there has been a change in -authentication method since the initial user login. This change can be from -a weak authentication method to a strong authentication method, or vice versa. - -In the first scenario, Assurance Level Change will an increase, while in the -second scenario it will be a decrease. For example, a user can start a session -with Service Provider A using single factor authentication (such as a password). -The user can then open another session with Service Provider B using -two-factor authentication (such as OTP). In this scenario an increase -Assurance Level Change event will signal to Service Provider A that user has -authenticated with a stronger authentication method. - -The actual reason why the assurance level changed might be specified with the -nested reason_admin and/or reason_user claims made in . - -
Event-Specific Claims - -
-
namespace:
-
- REQUIRED, JSON string: the namespace of the values in the current_level and previous_level claims. -This string MAY be one of the following strings: - - - - RFC8176: The assurance level values are from the specification - RFC6711: The assurance level values are from the specification - ISO-IEC-29115: The assurance level values are from the specification - NIST-IAL: The assurance level values are from the specification - NIST-AAL: The assurance level values are from the specification - NIST-FAL: The assurance level values are from the specification - Any other value that is an alias for a custom namespace agreed between the Transmitter and the Receiver - -
-
current_level
-
- REQUIRED, JSON string: The current assurance level, as defined in the specified namespace -
-
previous_level
-
- OPTIONAL, JSON string: the previous assurance level, as defined in the specified namespace -If the Transmitter omits this value, the Receiver MUST assume that the previous assurance level is unknown to the Transmitter -
-
change_direction
-
- OPTIONAL, JSON string: the assurance level increased or decreased -If the Transmitter has specified the previous_level, then the Transmitter SHOULD provide a value for this claim. -If present, this MUST be one of the following strings: - - - - increase - decrease - -
-
- -When event_timestamp is included, its value MUST represent the time at which -the assurance level changed. - -
-
Examples - -
- -
- -
-
-
Device Compliance Change -Event Type URI: - -https://schemas.openid.net/secevent/caep/event-type/device-compliance-change - -Device Compliance Change signals that a device's compliance status has changed. - -The actual reason why the status change occurred might be specified with the -nested reason_admin and/or reason_user claims made in . - -
Event-Specific Claims - -
-
previous_status
-
- REQUIRED, JSON string: the compliance status prior to the change that triggered the event -
-
-
- This MUST be one of the following strings: - - - - compliant - not-compliant - -
-
current_status
-
- REQUIRED, JSON string: the current status that triggered the event -
-
-
- This MUST be one of the following strings: - - - - compliant - not-compliant - -
-
- -When event_timestamp is included, its value MUST represent the time at which -the device compliance status changed. - -
-
Examples - -NOTE: The event type URI is wrapped, the backslash is the continuation character. - -
- -
-
-
Session Established -Event Type URI: - -https://schemas.openid.net/secevent/caep/event-type/session-established - -The Session Established event signifies that the Transmitter has established a new session for the subject. Receivers may use this information for a number of reasons, including: - - - A service acting as a Transmitter can close the loop with the IdP after a user has been federated from the IdP - An IdP can detect unintended logins - A Receiver can establish an inventory of user sessions - - -The event_timestamp in this event type specifies the time at which the session was established. - -
Event Specific Claims -The following optional claims MAY be included in the Session Established event: - -
-
ips
-
- The array of IP addresses of the user as observed by the Transmitter. The value MUST be in the format of an array of strings, each one of which represents the RFC 4001 string representation of an IP address. (NOTE, this can be different from the one observed by the Receiver for the same user because of network translation) -
-
fp_ua
-
- Fingerprint of the user agent computed by the Transmitter. (NOTE, this is not to identify the session, but to present some qualities of the session) -
-
acr
-
- The authentication context class reference of the session, as established by the Transmitter. The value of this field MUST be interpreted in the same way as the corresponding field in an OpenID Connect ID Token -
-
amr
-
- The authentication methods reference of the session, as established by the Transmitter. The value of this field MUST be an array of strings, each of which MUST be interpreted in the same way as the corresponding field in an OpenID Connect ID Token -
-
ext_id
-
- The external session identifier, which may be used to correlate this session with a broader session (e.g., a federated session established using SAML) -
-
- -
-
Examples -The following is a non-normative example of the session-established event type: - -
- -
-
-
Session Presented -Event Type URI: - -https://schemas.openid.net/secevent/caep/event-type/session-presented - -The Session Presented event signifies that the Transmitter has observed the session to be present at the Transmitter at the time indicated by the event_timestamp field in the Session Presented event. Receivers may use this information for reasons that include: - - - Detecting abnormal user activity - Establishing an inventory of live sessions belonging to a user - - -
Event Specific Claims -The following optional claims MAY be present in a Session Presented event: - -
-
ips
-
- The array of IP addresses of the user as observed by the Transmitter. The value MUST be in the format of an array of strings, each one of which represents the RFC 4001 string representation of an IP address. (NOTE, this can be different from the one observed by the Receiver for the same user because of network translation) -
-
fp_ua
-
- Fingerprint of the user agent computed by the Transmitter. (NOTE, this is not to identify the session, but to present some qualities of the session) -
-
ext_id
-
- The external session identifier, which may be used to correlate this session with a broader session (e.g., a federated session established using SAML) -
-
- -
-
Examples -The following is a non-normative example of a Session Presented event: - -
- -
-
-
-
Security Considerations -Any implementations of events described in this document SHOULD comply with the Shared Signals Framework . Exchanging events described herein without complying with the Shared Signals Framework may result in security issues. - -
- - - - - - - - - - -&RFC4001; - - - ISO/IEC 29115:2013 -- Information technology - Security techniques - Entity authentication assurance framework - - - - - - - - - Digital Identity Guidelines, Authentication and Lifecycle Management - - - - - - - - - - - - - - - Digital Identity Guidelines, Federation and Assertions - - - - - - - - - - - - - - - - - - - - - Digital Identity Guidelines, Enrollment and Identity Proofing - - - - - - - - - - - - OpenID Connect Core 1.0 - ID Token - - - - - - - - - - - - - - - - - - -&RFC2119; -&RFC8174; -&RFC5280; -&RFC5646; -&RFC6711; -&RFC8176; - - - OpenID Shared Signals and Events Framework Specification 1.0 - - Google - - - Microsoft - - - Coinbase - - - Amazon - - - Yubico - - - - - - - Web Authentication: An API for accessing Public Key Credentials Level 2 - - Google - - - - - - - - - - - - - -
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. - -
-
Document History - -[[ To be removed from the final specification ]] - --03 - - - New "Session Established" and "Session Presented" event types - Added namespace required field to Assurance Level Change event - Changed the name referencing SSE to SSF - Added format to the subjects in examples in CAEP - Formatting and typo changes - - -
- - - - - - - - From eb44530040a88f0dbc1a2b959e1709269b2394fd Mon Sep 17 00:00:00 2001 From: Atul Tulshibagwale Date: Tue, 11 Feb 2025 18:26:38 -0800 Subject: [PATCH 10/13] first commit: Moved 10.1, 10.2 to Section 4, reworded that section to match. --- openid-sharedsignals-framework-1_0.md | 293 +++++++++++++------------- 1 file changed, 145 insertions(+), 148 deletions(-) diff --git a/openid-sharedsignals-framework-1_0.md b/openid-sharedsignals-framework-1_0.md index 0a7a439..7acabca 100644 --- a/openid-sharedsignals-framework-1_0.md +++ b/openid-sharedsignals-framework-1_0.md @@ -176,7 +176,7 @@ This specification defines: * Subject principals * Subject claims in SSF events * Event types -* Event properties +* Events * Transmitter Configuration Metadata and its discovery method for Receivers * A management API for Event Streams @@ -397,14 +397,151 @@ below MAY define certain members within a Complex Subject to be Critical. A SSF Receiver MUST discard any event that contains a Subject with a Critical member that it is unable to process. -# Event Properties {#properties} +# Events {#events} -Additional members about an event may be included in the "events" claim. Some -of these members are required and specified as such in the respective event -types specs. If a Transmitter determines that it needs to include additional -members that are not specified in the event types spec, then the name of such -members MUST be a URI. The discoverability of all additional members is -specified in the Discovery section ({{discovery}}). +## Security Event Token Profile {#set-profle} +The Shared Signals Framework profiles the Security Event Token (SET) +{{RFC8417}} specification by defining certain properties of SETs as described in this section. + +### Distinguishing SETs from other Kinds of JWTs +Of particular concern is the possibility that SETs are confused for other kinds +of JWTs. The Security Considerations section of {{RFC8417}} has several sub-sections +on this subject. The Shared Signals Framework requires further restrictions: + +* The "sub" claim MUST NOT be present, as described in {{event-subjects}}. +* SSF SETs MUST use explicit typing, as described in {{explicit-typing}}. +* The "exp" claim MUST NOT be present, as described in {{exp-claim}}. + +### Signature Key Resolution {#signature-key-resolution} +The signature key can be obtained through "jwks_uri", see {{discovery}}. + +### SSF Event Subject {#event-subjects} +The primary Subject Member of SSF events is described in the "Subject Members" section ({{subject-ids}}). The JWT "sub" claim MUST NOT be present in any SET containing +an SSF event. + +### SSF Event Properties {#event-properties} +The SSF event MAY contain additional claims within the event payload that are +specific to the event type. + +~~~ json +{ + "iss": "https://idp.example.com/", + "jti": "756E69717565206964656E746966696572", + "iat": 1520364019, + "txn": 8675309, + "aud": "636C69656E745F6964", + "sub_id": { + "format": "phone", + "phone_number": "+1 206 555 0123" + }, + "events": { + "https://schemas.openid.net/secevent/risc/event-type/account-disabled": { + "reason": "hijacking" + } + } +} +~~~ +{: #risc-event-subject-example title="Example: SET Containing a RISC Event with a Phone Number Subject"} + +~~~ json +{ + "iss": "https://idp.example.com/", + "jti": "756E69717565206964656E746966696572", + "iat": 1520364019, + "txn": 8675309, + "aud": "636C69656E745F6964", + "sub_id": { + "format": "email", + "email": "user@example.com" + }, + "events": { + "https://schemas.openid.net/secevent/caep/event-type/token-claims-changed": { + "claims": { + "token": "some-token-value" + } + } + } +} +~~~ +{: #caep-event-properties-example title="Example: SET Containing a CAEP Event with Properties"} + +### Explicit Typing of SETs {#explicit-typing} +SSF events MUST use explicit typing as defined in Section 2.3 of {{RFC8417}}. + +~~~ json +{ + "typ":"secevent+jwt", + "alg":"HS256" +} +~~~ +{: title="Explicitly Typed JOSE Header" #explicit-type-header} + +The purpose is defense against confusion with other JWTs, as described in +Sections 4.5, 4.6 and 4.7 of {{RFC8417}}. While current Id Token {{OpenID.Core}} +validators may not be using the "typ" header parameter, requiring it for SSF +SETs guarantees a distinct value for future validators. + +## The "iss" Claim {#iss-claim} +The "iss" claim MUST match the "iss" value in the Stream Configuration data for the stream +that the event is sent on. Receivers MUST validate that this claim matches the "iss" +in the Stream Configuration data, as well as the Issuer from which the Receiver requested +the Transmitter Configuration data. + +### The "exp" Claim {#exp-claim} +The "exp" claim MUST NOT be used in SSF SETs. + +The purpose is defense in depth against confusion with other JWTs, as described +in Sections 4.5 and 4.6 of {{RFC8417}}. + +### The "aud" Claim {#aud-claim} +The "aud" claim can be a single string or an array of strings. Values that +uniquely identify the Receiver to the Transmitter MAY be used, if the two parties +have agreement on the format. + +More than one value can be present if the corresponding Receivers are known to +the Transmitter to be the same entity, for example a web client and a mobile +client of the same application. All the Receivers in this case MUST use the +exact same delivery method. + +If multiple Receivers have the exact same delivery configuration but the +Transmitter does not know if they belong to the same entity then the Transmitter +SHOULD issue distinct SETs for each Receiver and deliver them separately. In +this case the multiple Receivers might use the same service to process SETs, and +this service might reroute SETs to respective Receivers, an "aud" claim with +multiple Receivers would lead to unintended data disclosure. + +~~~ json +{ + "jti": "123456", + "iss": "https://transmitter.example.com", + "aud": ["receiver.example.com/web", "receiver.example.com/mobile"], + "iat": 1493856000, + "txn": 8675309, + "sub_id": { + "format": "opaque", + "id": "72e6991badb44e08a69672960053b342" + }, + "events": { + "https://schemas.openid.net/secevent/ssf/event-type/verification": { + "state": "VGhpcyBpcyBhbiBleGFtcGxlIHN0YXRlIHZhbHVlLgo=" + } + } +} +~~~ +{: title="Example: SET with array 'aud' claim" #figarrayaud} + +### The "txn" claim {#txn-claim} +Transmitters SHOULD set the "txn" claim value in Security Event Tokens (SETs). If the value is present, it MUST be unique to the underlying event that caused the Transmitter to generate the Security Event Token (SET). The Transmitter, however, may use the same value in the "txn" claim across different Security Events Tokens (SETs), such as session revoked and credential change, to indicate that the SETs originated from the same underlying cause or reason. + +## The "events" claim {#events-claim} +The "events" claim SHOULD contain only one event. Multiple event type URIs are +permitted only if they are alternative URIs defining the exact same event type. The type of the event is specified by the key in the value of the `events` claim. The value of this field is the event object. + +### Event type specific fields +The event object inside the `events` claim MAY have one or more fields that are uniquely determined by the type of the event. + +### The "event_data" field {#event-data-claim} +Any fields that the Transmitter wishes to communicate to the receiver, but which are not specified by the specific event type, SHOULD be placed in a `event_data` field inside the event object. If this field is present, then its value MUST be a JSON object. # Example SETs that conform to the Shared Signals Framework {#events-examples} @@ -2054,146 +2191,6 @@ RISC Use Cases {{USECASES}}. The CAEP use cases that set the requirements are described in CAEP Use Cases (TODO: Add reference when file is added to repository.) -## Security Event Token Profile {#set-profle} -This section provides SSF profiling specifications for the Security Event Token (SET) -{{RFC8417}} spec. - -### Signature Key Resolution {#signature-key-resolution} -The signature key can be obtained through "jwks_uri", see {{discovery}}. - -### SSF Event Subject {#event-subjects} -The primary Subject Member of SSF events is described in the "Subject Members" section ({{subject-ids}}). The JWT "sub" claim MUST NOT be present in any SET containing -an SSF event. - -### SSF Event Properties {#event-properties} -The SSF event MAY contain additional claims within the event payload that are -specific to the event type. - -~~~ json -{ - "iss": "https://idp.example.com/", - "jti": "756E69717565206964656E746966696572", - "iat": 1520364019, - "txn": 8675309, - "aud": "636C69656E745F6964", - "sub_id": { - "format": "phone", - "phone_number": "+1 206 555 0123" - }, - "events": { - "https://schemas.openid.net/secevent/risc/event-type/account-disabled": { - "reason": "hijacking" - } - } -} -~~~ -{: #risc-event-subject-example title="Example: SET Containing a RISC Event with a Phone Number Subject"} - -~~~ json -{ - "iss": "https://idp.example.com/", - "jti": "756E69717565206964656E746966696572", - "iat": 1520364019, - "txn": 8675309, - "aud": "636C69656E745F6964", - "sub_id": { - "format": "email", - "email": "user@example.com" - }, - "events": { - "https://schemas.openid.net/secevent/caep/event-type/token-claims-changed": { - "claims": { - "token": "some-token-value" - } - } - } -} -~~~ -{: #caep-event-properties-example title="Example: SET Containing a CAEP Event with Properties"} - -### Explicit Typing of SETs {#explicit-typing} -SSF events MUST use explicit typing as defined in Section 2.3 of {{RFC8417}}. - -~~~ json -{ - "typ":"secevent+jwt", - "alg":"HS256" -} -~~~ -{: title="Explicitly Typed JOSE Header" #explicit-type-header} - -The purpose is defense against confusion with other JWTs, as described in -Sections 4.5, 4.6 and 4.7 of {{RFC8417}}. While current Id Token {{OpenID.Core}} -validators may not be using the "typ" header parameter, requiring it for SSF -SETs guarantees a distinct value for future validators. - -## The "iss" Claim {#iss-claim} -The "iss" claim MUST match the "iss" value in the Stream Configuration data for the stream -that the event is sent on. Receivers MUST validate that this claim matches the "iss" -in the Stream Configuration data, as well as the Issuer from which the Receiver requested -the Transmitter Configuration data. - -### The "exp" Claim {#exp-claim} -The "exp" claim MUST NOT be used in SSF SETs. - -The purpose is defense in depth against confusion with other JWTs, as described -in Sections 4.5 and 4.6 of {{RFC8417}}. - -### The "aud" Claim {#aud-claim} -The "aud" claim can be a single string or an array of strings. Values that -uniquely identify the Receiver to the Transmitter MAY be used, if the two parties -have agreement on the format. - -More than one value can be present if the corresponding Receivers are known to -the Transmitter to be the same entity, for example a web client and a mobile -client of the same application. All the Receivers in this case MUST use the -exact same delivery method. - -If multiple Receivers have the exact same delivery configuration but the -Transmitter does not know if they belong to the same entity then the Transmitter -SHOULD issue distinct SETs for each Receiver and deliver them separately. In -this case the multiple Receivers might use the same service to process SETs, and -this service might reroute SETs to respective Receivers, an "aud" claim with -multiple Receivers would lead to unintended data disclosure. - -~~~ json -{ - "jti": "123456", - "iss": "https://transmitter.example.com", - "aud": ["receiver.example.com/web", "receiver.example.com/mobile"], - "iat": 1493856000, - "txn": 8675309, - "sub_id": { - "format": "opaque", - "id": "72e6991badb44e08a69672960053b342" - }, - "events": { - "https://schemas.openid.net/secevent/ssf/event-type/verification": { - "state": "VGhpcyBpcyBhbiBleGFtcGxlIHN0YXRlIHZhbHVlLgo=" - } - } -} -~~~ -{: title="Example: SET with array 'aud' claim" #figarrayaud} - -### The "txn" claim {#txn-claim} -Transmitters SHOULD set the "txn" claim value in Security Event Tokens (SETs). If the value is present, it MUST be unique to the underlying event that caused the Transmitter to generate the Security Event Token (SET). The Transmitter, however, may use the same value in the "txn" claim across different Security Events Tokens (SETs), such as session revoked and credential change, to indicate that the SETs originated from the same underlying cause or reason. - -### The "events" claim {#events-claim} -The "events" claim SHOULD contain only one event. Multiple event type URIs are -permitted only if they are alternative URIs defining the exact same event type. - -### Security Considerations - -#### Distinguishing SETs from other Kinds of JWTs -Of particular concern is the possibility that SETs are confused for other kinds -of JWTs. The Security Considerations section of {{RFC8417}} has several sub-sections -on this subject. The Shared Signals Framework requires further restrictions: - -* The "sub" claim MUST NOT be present, as described in {{event-subjects}}. -* SSF SETs MUST use explicit typing, as described in {{explicit-typing}}. -* The "exp" claim MUST NOT be present, as described in {{exp-claim}}. - ## SET Token Delivery Using HTTP Profile {#set-token-delivery-using-http-profile} This section provides SSF profiling specifications for the {{RFC8935}} and {{RFC8936}} specs. From 8b1c4571a06384cb3488380103def32c3d5483d2 Mon Sep 17 00:00:00 2001 From: Atul Tulshibagwale Date: Wed, 12 Feb 2025 13:43:29 -0800 Subject: [PATCH 11/13] reorganization completed --- openid-sharedsignals-framework-1_0.md | 223 ++++++++++++-------------- 1 file changed, 105 insertions(+), 118 deletions(-) diff --git a/openid-sharedsignals-framework-1_0.md b/openid-sharedsignals-framework-1_0.md index 7acabca..7fcdd73 100644 --- a/openid-sharedsignals-framework-1_0.md +++ b/openid-sharedsignals-framework-1_0.md @@ -403,68 +403,6 @@ that it is unable to process. The Shared Signals Framework profiles the Security Event Token (SET) {{RFC8417}} specification by defining certain properties of SETs as described in this section. -### Distinguishing SETs from other Kinds of JWTs -Of particular concern is the possibility that SETs are confused for other kinds -of JWTs. The Security Considerations section of {{RFC8417}} has several sub-sections -on this subject. The Shared Signals Framework requires further restrictions: - -* The "sub" claim MUST NOT be present, as described in {{event-subjects}}. -* SSF SETs MUST use explicit typing, as described in {{explicit-typing}}. -* The "exp" claim MUST NOT be present, as described in {{exp-claim}}. - -### Signature Key Resolution {#signature-key-resolution} -The signature key can be obtained through "jwks_uri", see {{discovery}}. - -### SSF Event Subject {#event-subjects} -The primary Subject Member of SSF events is described in the "Subject Members" section ({{subject-ids}}). The JWT "sub" claim MUST NOT be present in any SET containing -an SSF event. - -### SSF Event Properties {#event-properties} -The SSF event MAY contain additional claims within the event payload that are -specific to the event type. - -~~~ json -{ - "iss": "https://idp.example.com/", - "jti": "756E69717565206964656E746966696572", - "iat": 1520364019, - "txn": 8675309, - "aud": "636C69656E745F6964", - "sub_id": { - "format": "phone", - "phone_number": "+1 206 555 0123" - }, - "events": { - "https://schemas.openid.net/secevent/risc/event-type/account-disabled": { - "reason": "hijacking" - } - } -} -~~~ -{: #risc-event-subject-example title="Example: SET Containing a RISC Event with a Phone Number Subject"} - -~~~ json -{ - "iss": "https://idp.example.com/", - "jti": "756E69717565206964656E746966696572", - "iat": 1520364019, - "txn": 8675309, - "aud": "636C69656E745F6964", - "sub_id": { - "format": "email", - "email": "user@example.com" - }, - "events": { - "https://schemas.openid.net/secevent/caep/event-type/token-claims-changed": { - "claims": { - "token": "some-token-value" - } - } - } -} -~~~ -{: #caep-event-properties-example title="Example: SET Containing a CAEP Event with Properties"} - ### Explicit Typing of SETs {#explicit-typing} SSF events MUST use explicit typing as defined in Section 2.3 of {{RFC8417}}. @@ -481,7 +419,23 @@ Sections 4.5, 4.6 and 4.7 of {{RFC8417}}. While current Id Token {{OpenID.Core}} validators may not be using the "typ" header parameter, requiring it for SSF SETs guarantees a distinct value for future validators. -## The "iss" Claim {#iss-claim} +### SSF Event Subject {#event-subjects} +The primary Subject Member of SSF events is described in the "Subject Members" section ({{subject-ids}}). The JWT "sub" claim MUST NOT be present in any SET containing +an SSF event. + +### Distinguishing SETs from other Kinds of JWTs +Of particular concern is the possibility that SETs are confused for other kinds +of JWTs. The Security Considerations section of {{RFC8417}} has several sub-sections +on this subject. The Shared Signals Framework requires further restrictions: + +* The "sub" claim MUST NOT be present, as described in {{event-subjects}}. +* SSF SETs MUST use explicit typing, as described in {{explicit-typing}}. +* The "exp" claim MUST NOT be present, as described in {{exp-claim}}. + +### Signature Key Resolution {#signature-key-resolution} +The signature key can be obtained through "jwks_uri", see {{discovery}}. + +### The "iss" Claim {#iss-claim} The "iss" claim MUST match the "iss" value in the Stream Configuration data for the stream that the event is sent on. Receivers MUST validate that this claim matches the "iss" in the Stream Configuration data, as well as the Issuer from which the Receiver requested @@ -533,7 +487,9 @@ multiple Receivers would lead to unintended data disclosure. ### The "txn" claim {#txn-claim} Transmitters SHOULD set the "txn" claim value in Security Event Tokens (SETs). If the value is present, it MUST be unique to the underlying event that caused the Transmitter to generate the Security Event Token (SET). The Transmitter, however, may use the same value in the "txn" claim across different Security Events Tokens (SETs), such as session revoked and credential change, to indicate that the SETs originated from the same underlying cause or reason. -## The "events" claim {#events-claim} +## Event Properties {#event-properties} + +### The "events" claim {#events-claim} The "events" claim SHOULD contain only one event. Multiple event type URIs are permitted only if they are alternative URIs defining the exact same event type. The type of the event is specified by the key in the value of the `events` claim. The value of this field is the event object. @@ -565,6 +521,51 @@ The following are hypothetical examples of SETs that conform to the Shared Signa ~~~ {: #subject-ids-ex-simple title="Example: SET Containing an SSF Event with a Simple Subject Member"} +~~~ json +{ + "iss": "https://idp.example.com/", + "jti": "756E69717565206964656E746966696572", + "iat": 1520364019, + "txn": 8675309, + "aud": "636C69656E745F6964", + "sub_id": { + "format": "phone", + "phone_number": "+1 206 555 0123" + }, + "events": { + "https://schemas.openid.net/secevent/risc/event-type/account-disabled": { + "reason": "hijacking" + } + } +} +~~~ +{: #risc-event-subject-example title="Example: SET Containing a RISC Event with a Phone Number Subject"} + +~~~ json +{ + "iss": "https://idp.example.com/", + "jti": "756E69717565206964656E746966696572", + "iat": 1520364019, + "txn": 8675309, + "aud": "636C69656E745F6964", + "sub_id": { + "format": "email", + "email": "user@example.com" + }, + "events": { + "https://schemas.openid.net/secevent/caep/event-type/token-claims-changed": { + "claims": { + "token": "some-token-value" + }, + "event_data": { + "context": "additional context of the event" + } + } + } +} +~~~ +{: #caep-event-properties-example title="Example: SET Containing a CAEP Event with Properties and Event Data"} + ~~~ json { "iss": "https://idp.example.com/", @@ -648,6 +649,46 @@ The following are hypothetical examples of SETs that conform to the Shared Signa ~~~ {: #subject-custom-type-ex title="Example: SET Containing an SSF Event with a Proprietary Subject Identifier Format"} +# Event Delivery {#event-delivery} +This section describes the supported methods of delivering SSF Events. It provides SSF profiling specifications for the {{RFC8935}} and {{RFC8936}} specs. + +## Stream Configuration Metadata {#delivery-meta} +Each delivery method is identified by a URI, specified below by the "method" +metadata. + +## Push Delivery using HTTP +This section provides SSF profiling specifications for the {{RFC8935}} spec. + +method + +> "urn:ietf:rfc:8935" + +endpoint_url + +> The URL where events are pushed through HTTP POST. This is set by the + Receiver. If a Receiver is using multiple streams from a single Transmitter + and needs to keep the SETs separated, it is RECOMMENDED that the URL for each + stream be unique. + +authorization_header + +> The HTTP Authorization header that the Transmitter MUST set with each event + delivery, if the configuration is present. The value is optional and it is set + by the Receiver. + +## Poll Delivery using HTTP +This section provides SSF profiling specifications for the {{RFC8936}} spec. + +method + +> "urn:ietf:rfc:8936" + +endpoint_url + +> The URL where events can be retrieved from. This is specified by the + Transmitter. These URLs MAY be reused across Receivers, but MUST be unique per + stream for a given Receiver. + # Transmitter Configuration Discovery {#discovery} This section defines a mechanism for Receivers to obtain the Transmitter @@ -2178,60 +2219,6 @@ consented to be released by the user, then the Transmitter MUST obtain consent to release such data from the user in accordance with the Transmitter's privacy policy. -# Profiles {#profiles} -This section is a profile of the following IETF Security Event specifications: - -* Security Event Token (SET) {{RFC8417}} -* Push-Based SET Token Delivery Using HTTP {{RFC8935}} -* Poll-Based SET Token Delivery Using HTTP {{RFC8936}} - -The RISC use cases that set the requirements are described in Security Events -RISC Use Cases {{USECASES}}. - -The CAEP use cases that set the requirements are described in CAEP Use Cases (TODO: Add - reference when file is added to repository.) - -## SET Token Delivery Using HTTP Profile {#set-token-delivery-using-http-profile} -This section provides SSF profiling specifications for the {{RFC8935}} and -{{RFC8936}} specs. - -### Stream Configuration Metadata {#delivery-meta} -Each delivery method is identified by a URI, specified below by the "method" -metadata. - -#### Push Delivery using HTTP -This section provides SSF profiling specifications for the {{RFC8935}} spec. - -method - -> "urn:ietf:rfc:8935" - -endpoint_url - -> The URL where events are pushed through HTTP POST. This is set by the - Receiver. If a Receiver is using multiple streams from a single Transmitter - and needs to keep the SETs separated, it is RECOMMENDED that the URL for each - stream be unique. - -authorization_header - -> The HTTP Authorization header that the Transmitter MUST set with each event - delivery, if the configuration is present. The value is optional and it is set - by the Receiver. - -#### Polling Delivery using HTTP -This section provides SSF profiling specifications for the {{RFC8936}} spec. - -method - -> "urn:ietf:rfc:8936" - -endpoint_url - -> The URL where events can be retrieved from. This is specified by the - Transmitter. These URLs MAY be reused across Receivers, but MUST be unique per - stream for a given Receiver. - # IANA Considerations {#iana} Subject Identifiers defined in this document will be added to the "Security Events Subject Identifier Types" registry. This registry is defined in the From dfa8cf44c11615f9cfd071e26e0b6e22b2c08091 Mon Sep 17 00:00:00 2001 From: Atul Tulshibagwale Date: Thu, 13 Feb 2025 13:10:58 -0800 Subject: [PATCH 12/13] removed event_data related text so that this PR is strictly about refactoring. --- openid-sharedsignals-framework-1_0.md | 10 ++-------- 1 file changed, 2 insertions(+), 8 deletions(-) diff --git a/openid-sharedsignals-framework-1_0.md b/openid-sharedsignals-framework-1_0.md index 7fcdd73..3deebd8 100644 --- a/openid-sharedsignals-framework-1_0.md +++ b/openid-sharedsignals-framework-1_0.md @@ -442,7 +442,7 @@ in the Stream Configuration data, as well as the Issuer from which the Receiver the Transmitter Configuration data. ### The "exp" Claim {#exp-claim} -The "exp" claim MUST NOT be used in SSF SETs. +The "exp" claim MUST NOT be used in SETs. The purpose is defense in depth against confusion with other JWTs, as described in Sections 4.5 and 4.6 of {{RFC8417}}. @@ -496,9 +496,6 @@ permitted only if they are alternative URIs defining the exact same event type. ### Event type specific fields The event object inside the `events` claim MAY have one or more fields that are uniquely determined by the type of the event. -### The "event_data" field {#event-data-claim} -Any fields that the Transmitter wishes to communicate to the receiver, but which are not specified by the specific event type, SHOULD be placed in a `event_data` field inside the event object. If this field is present, then its value MUST be a JSON object. - # Example SETs that conform to the Shared Signals Framework {#events-examples} The following are hypothetical examples of SETs that conform to the Shared Signals Framework. @@ -556,15 +553,12 @@ The following are hypothetical examples of SETs that conform to the Shared Signa "https://schemas.openid.net/secevent/caep/event-type/token-claims-changed": { "claims": { "token": "some-token-value" - }, - "event_data": { - "context": "additional context of the event" } } } } ~~~ -{: #caep-event-properties-example title="Example: SET Containing a CAEP Event with Properties and Event Data"} +{: #caep-event-properties-example title="Example: SET Containing a CAEP Event with Properties"} ~~~ json { From 0e429bc76dc9c45eb85c6fffe158f2799e619011 Mon Sep 17 00:00:00 2001 From: Atul Tulshibagwale Date: Fri, 14 Feb 2025 11:43:45 -0800 Subject: [PATCH 13/13] Update openid-sharedsignals-framework-1_0.md Co-authored-by: Jen Schreiber --- openid-sharedsignals-framework-1_0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/openid-sharedsignals-framework-1_0.md b/openid-sharedsignals-framework-1_0.md index 3deebd8..f9e3c0f 100644 --- a/openid-sharedsignals-framework-1_0.md +++ b/openid-sharedsignals-framework-1_0.md @@ -397,7 +397,7 @@ below MAY define certain members within a Complex Subject to be Critical. A SSF Receiver MUST discard any event that contains a Subject with a Critical member that it is unable to process. -# Events {#events} +# Events {#events} ## Security Event Token Profile {#set-profle} The Shared Signals Framework profiles the Security Event Token (SET)